For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Batch create multiple Instances for Tenant with NVLink domain-aware machine allocation.
This endpoint creates multiple instances in a single atomic transaction. All instances share the same configuration (interfaces, OS, SSH keys, etc.) but are assigned different machines.
When `topologyOptimized` is true (default), all instances must be allocated on machines within the same NVLink domain. If insufficient machines are available in a single NVLink domain, the request will fail.
When `topologyOptimized` is false, instances can be spread across different NVLink domains.
Instance names are automatically generated using the `namePrefix` with a random 6-character suffix (e.g., "worker" becomes "worker-abc123", "worker-def456").
Org must have a Tenant entity. User must have `FORGE_TENANT_ADMIN` authorization role.
Authentication
AuthorizationBearer
```
export JWT_BEARER_TOKEN="<jwt-bearer-token>"
# Example org name: "acme-inc
export ORG_NAME=<org-name>
# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://carbide-rest-api.carbide.svc.cluster.local/v2/org/$ORG_NAME/carbide/user/current
```
Path parameters
orgstringRequired
Request
This endpoint expects an object.
namePrefixstringRequired2-240 characters
Prefix for instance names. Instances will be named with this prefix followed by a random 6-character suffix (e.g., “worker” becomes “worker-abc123”)
countintegerRequired2-18
Number of instances to create in this batch. Minimum 2, maximum 18 (limited by topology domain size)
tenantIdstringRequiredformat: "uuid"
ID of the Tenant creating the Instances
instanceTypeIdstringRequiredformat: "uuid"
ID of the Instance Type to use for all Instances in the batch
vpcIdstringRequiredformat: "uuid"
ID of the VPC the Instances should belong to
interfaceslist of objectsRequired
Interface configuration shared across all instances. At least one interface must be specified. Either Subnet or VPC Prefix interfaces allowed, only one of the Subnets or VPC Prefixes can be attached over Physical interface. Interface ipAddress is not supported for batch instance creation requests.
descriptionstring or nullOptional<=1024 characters
Description applied to all instances in the batch, optional
secondaryVpcIdslist of stringsOptional
IDs of additional VPCs the Instances should attach to through non-primary interfaces. This field may only be specified when every entry in interfaces uses vpcPrefixId. IDs must be unique, must be valid UUIDs, and must not include the primary vpcId.
userDatastring or nullOptional
User data applied to all instances. Can only be specified if allowOverride is set to true in Operating System
operatingSystemIdstring or nullOptionalformat: "uuid"
Must be specified if iPXE Script field is empty
networkSecurityGroupIdstring or nullOptionalformat: "uuid"
ID of a Network Security Group to attach to all instances
ipxeScriptstring or nullOptional
Override iPXE script specified in OS, must be specified if Operating System is not specified
alwaysBootWithCustomIpxebooleanOptional
When set to true, the iPXE script specified by OS or overridden here will always be run when rebooting the Instances. OS must be of iPXE type.
phoneHomeEnabledbooleanOptional
When set to true, the Instances will be enabled with the Phone Home service.
labelsmap from strings to stringsOptional
infinibandInterfaceslist of objectsOptional
InfiniBand interface configuration shared across all instances
dpuExtensionServiceDeploymentslist of objectsOptional
DPU Extension Services to deploy to all instances in the batch
nvLinkInterfaceslist of objectsOptional
NVLink interface configuration shared across all instances. A subset of GPUs may be specified. Each item references one GPU index (deviceInstance) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.
sshKeyGroupIdslist of stringsOptional
SSH Key Group IDs that will provide Serial over LAN access to all instances
topologyOptimizedbooleanOptionalDefaults to true
When true (default), all instances must be allocated on machines within the same NVLink domain. When false, instances can be spread across different NVLink domains.
Response
Created
idstringRead-onlyformat: "uuid"
Unique identifier for the Instance
namestring2-256 characters
Name for the Instance
descriptionstring
Description for the Instance
tenantIdstringformat: "uuid"
ID of the Tenant the Instance belongs to
infrastructureProviderIdstringformat: "uuid"
ID of the Infrastructure Provider that owns the Site where the Instance is located
siteIdstringformat: "uuid"
ID of the Site where the Instance is located
instanceTypeIdstringformat: "uuid"
vpcIdstringformat: "uuid"
secondaryVpcIdslist of strings
IDs of VPCs attached to the Instance through non-primary interfaces
machineIdstring or null
operatingSystemIdstringformat: "uuid"
networkSecurityGroupIdstring or null
networkSecurityGroupPropagationDetailsobject
Propagation details for the attached Network Security Group
networkSecurityGroupInheritedboolean
Indicates if the Network Security Group is inherited from VPC
controllerInstanceIdstring or nullformat: "uuid"
ipxeScriptstring or null
alwaysBootWithCustomIpxeboolean
Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabledboolean
Indicates whether the Phone Home service should be enabled or disabled for Instance
userDatastring or null
labelsmap from strings to strings
isUpdatePendingboolean
Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrlstring or null
Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname
interfaceslist of objects
infinibandInterfaceslist of objects
nvLinkInterfaceslist of objects
dpuExtensionServiceDeploymentslist of objects
DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIdslist of strings
IDs of SSH Key Groups associated with this Instance
sshKeyGroupslist of objects
IDs of SSH Key Groups associated with this Instance
tpmEkCertificatestring or null
base64 encoded TPM EK Certificate associated with this Instance
statusenum
Status values for Instance objects
statusHistorylist of objects
deprecationslist of objects
createddatetimeRead-only
updateddatetimeRead-only
Errors
400
Bad Request Error
403
Forbidden Error
Batch create multiple Instances for Tenant with NVLink domain-aware machine allocation.
This endpoint creates multiple instances in a single atomic transaction. All instances share the same configuration (interfaces, OS, SSH keys, etc.) but are assigned different machines.
When topologyOptimized is true (default), all instances must be allocated on machines within the same NVLink domain. If insufficient machines are available in a single NVLink domain, the request will fail.
When topologyOptimized is false, instances can be spread across different NVLink domains.
Instance names are automatically generated using the namePrefix with a random 6-character suffix (e.g., “worker” becomes “worker-abc123”, “worker-def456”).
Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.
export JWT_BEARER_TOKEN="<jwt-bearer-token>"
# Example org name: "acme-inc
export ORG_NAME=<org-name>
# Use the JWT bearer token in your API request auth header:
