v57

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-08-012143051018.3 KB

Instance

Batch Create Instances

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 authorization role with TENANT_ADMIN suffix.

post/v2/org/{org}/nico/instance/batch

Request body

namePrefixstring required

Prefix for instance names. Instances will be named with this prefix followed by a random 6-character suffix (e.g., "worker" becomes "worker-abc123")

countinteger required

Number of instances to create in this batch. Minimum 2, maximum 18 (limited by topology domain size)

descriptionstring nullable

Description applied to all instances in the batch, optional

tenantIdstring uuid required

ID of the Tenant creating the Instances

instanceTypeIdstring uuid required

ID of the Instance Type to use for all Instances in the batch

vpcIdstring uuid required

ID of the VPC the Instances should belong to

secondaryVpcIdsstring[]

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 or vpcId. IDs must be unique, must be valid UUIDs, and must not include the primary vpcId.

userDatastring nullable

User data applied to all instances. Can only be specified if allowOverride is set to true in Operating System

operatingSystemIdstring uuid nullable

Must be specified if iPXE Script field is empty

networkSecurityGroupIdstring uuid nullable

ID of a Network Security Group to attach to all instances

ipxeScriptstring nullable

Override iPXE script specified in OS, must be specified if Operating System is not specified

alwaysBootWithCustomIpxeboolean

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.

phoneHomeEnabledboolean

When set to true, the Instances will be enabled with the Phone Home service.

labelsLabels

autoNetworkboolean

When true, asks NICo to auto-resolve each Instance's network interfaces from the host's underlay (HostInband) network segments. Intended for instances on zero-DPU hosts (or hosts with their DPU in NIC mode). When true: (1) the target VPC's networkVirtualizationType MUST be FLAT, (2) interfaces MUST be empty or omitted, and (3) secondaryVpcIds MUST be empty or omitted.

sshKeyGroupIdsstring[]

SSH Key Group IDs that will provide Serial over LAN access to all instances

topologyOptimizedboolean

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.

Example request

{
  "namePrefix": "gpu-worker",
  "count": 4,
  "description": "GPU worker nodes for distributed training",
  "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
  "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
  "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
  "topologyOptimized": true,
  "labels": {
    "workload": "training",
    "env": "production"
  },
  "interfaces": [
    {
      "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
      "isPhysical": true
    }
  ],
  "infinibandInterfaces": [
    {
      "partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 0,
      "isPhysical": true
    }
  ],
  "nvLinkInterfaces": [
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 0
    },
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 1
    }
  ],
  "sshKeyGroupIds": [
    "a7bf2f9c-12f0-4673-be47-12be6d9e16c8"
  ]
}

Response

Created

idstring uuid

Unique identifier for the Instance

namestring

Name for the Instance

descriptionstring nullable

Description for the Instance

tenantIdstring uuid

ID of the Tenant the Instance belongs to

infrastructureProviderIdstring uuid

ID of the Infrastructure Provider that owns the Site where the Instance is located

siteIdstring uuid

ID of the Site where the Instance is located

instanceTypeIdstring uuid nullable

ID of the Instance Type

vpcIdstring uuid

ID of the VPC

secondaryVpcIdsstring[]

IDs of VPCs attached to the Instance through non-primary interfaces

machineIdstring nullable

ID of the Machine

operatingSystemIdstring uuid nullable

ID of the Operating System

networkSecurityGroupIdstring nullable

ID of the attached Network Security Group, if any

networkSecurityGroupInheritedboolean

Indicates if the Network Security Group is inherited from VPC

controllerInstanceIdstring uuid nullable

ID of the Instance in Site Controller

ipxeScriptstring nullable

Attribute which is inherited from Operating System

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 the Instance

userDatastring nullable

UserData is inherited from Operating System or specified by user if allowed

labelsLabels

isUpdatePendingboolean

Indicates whether an update is available for the Instance. Updates can be applied on reboot

serialConsoleUrlstring nullable

Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname

autoNetworkboolean

True when this Instance uses NICo auto-resolved networking from the host's underlay (HostInband) network segments. When true, the caller's request interfaces list was empty, this interfaces field remains empty on readback, and the resolved per-interface details surface under status.network.interfaces.

sshKeyGroupIdsstring[]

IDs of SSH Key Groups associated with this Instance

tpmEkCertificatestring nullable

base64 encoded TPM EK Certificate associated with this Instance

Status values for Instance objects

createdstring date-time

Date/time when the Instance was created

updatedstring date-time

Date/time when the Instance was last updated

Example response

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "spark-monitor-1",
    "description": "Node for monitoring Spark",
    "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
    "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
    "controllerInstanceId": null,
    "ipxeScript": null,
    "alwaysBootWithCustomIpxe": false,
    "networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e",
    "networkSecurityGroupPropagationDetails": {
      "objectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "detailedStatus": "Partial",
      "status": "Synchronizing",
      "details": "",
      "unpropagatedInstanceIds": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "relatedInstanceIds": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ]
    },
    "networkSecurityGroupInherited": false,
    "userData": null,
    "labels": {
      "region": "portland",
      "env": "staging"
    },
    "isUpdatePending": false,
    "serialConsoleUrl": "ssh://user@nico.acme.com",
    "interfaces": [
      {
        "id": "64d2028c-ae87-4069-a624-66089d957ef9",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
        "isPhysical": true,
        "virtualFunctionId": null,
        "macAddress": null,
        "ipAddresses": [],
        "status": "Pending",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      }
    ],
    "infinibandInterfaces": [
      {
        "id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
        "device": "MT2910 Family [ConnectX-7]",
        "deviceInstance": 0,
        "isPhysical": true,
        "virtualFunctionId": null,
        "guid": "946dae0300339498",
        "status": "Ready",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      }
    ],
    "nvLinkInterfaces": [
      {
        "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
        "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
        "deviceInstance": 0,
        "status": "Ready",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      },
      {
        "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
        "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
        "deviceInstance": 1,
        "status": "Ready",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      },
      {
        "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
        "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
        "deviceInstance": 2,
        "status": "Ready",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      },
      {
        "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
        "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
        "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
        "deviceInstance": 3,
        "status": "Ready",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      }
    ],
    "dpuExtensionServiceDeployments": [],
    "sshKeyGroupIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "sshKeyGroups": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "reno-integration-sre",
        "description": "SRE access SSH keys for Reno Integration",
        "version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
        "status": "Syncing",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      }
    ],
    "tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
    "status": "Pending",
    "statusHistory": [
      {
        "status": "Pending",
        "message": "Request received, pending processing",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z"
      }
    ],
    "created": "2019-08-24T14:15:22Z",
    "updated": "2019-08-24T14:15:22Z"
  }
]