> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/infra-controller/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/infra-controller/_mcp/server.
# Example API Workflows
This section provides example REST API workflows for common NICo tasks. All examples use `curl` for API calls and assume a bearer token authentication system is in place.
## Viewing Site Inventory
Use the value of `id` from the output of the preceding example as the value for the infrastructureProviderId URL parameter:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/site" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
The Site ID in the response is a required input for many configuration requests.
```json title={"Example Response"}
[
{
"id": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"name": "demo-site",
"description": "nico site",
"org": "wdksahew1rqv",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteControllerVersion": null,
"siteAgentVersion": null,
"registrationToken": null,
"registrationTokenExpiration": "2023-05-03T22:18:45.23286Z",
"serialConsoleHostname": "example.console.com",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": null,
"serialConsoleMaxSessionLength": null,
"deprecations": [],
"status": "Registered",
"statusHistory": [
{
"status": "Registered",
"message": "Site has been successfully paired",
"created": "2023-05-02T22:20:04.627469Z",
"updated": "2023-05-02T22:20:04.627469Z"
},
{
"status": "Pending",
"message": "registration token renewed, pending pairing",
"created": "2023-05-02T22:18:45.262934Z",
"updated": "2023-05-02T22:18:45.262934Z"
}
],
"created": "2023-01-20T21:36:41.339466Z",
"updated": "2023-07-06T16:19:20.104353Z"
}
]
```
Use the `id` value from the output of the preceding examples as the values for the `infrastructureProviderId` and `siteId` URL parameters. The following sample command uses URL parameters to filter for machines that are in a `Ready` state and are not assigned an instance type.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/machine?siteId=157627d6-d742-440b-ac04-77a618d94459&hasInstanceType=false&status=Ready" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
[
{
"id": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": null,
"controllerMachineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"controllerMachineType": "PowerEdge R750",
"hostname": "sad-uniform",
"machineCapabilities": [
{
"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{
"type": "Storage",
"name": "Dell Ent NVMe CM6 RI 1.92TB",
"count": 3
},
{
"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2
},
{
"type": "Network",
"name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
"count": 2
},
{
"type": "Network",
"name": "BCM57414 NetXtreme-E 10Gb/25Gb RDMA Ethernet Controller",
"count": 2
}
],
"machineInterfaces": [
{
"id": "6dd628a3-cc5b-4b12-8a5b-acad0160c7c3",
"machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"controllerInterfaceId": "029a9fdf-c232-4e8d-9327-4c271ad7ea01",
"controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
"subnetId": null,
"hostname": "sad-uniform",
"isPrimary": true,
"macAddress": "B8:3F:D2:90:97:04",
"ipAddresses": [
"10.180.90.10/32"
],
"created": "2023-05-04T14:22:17.121178Z",
"updated": "2023-07-06T16:16:22.777176Z"
}
],
"status": "Ready",
"statusHistory": [],
"created": "2023-04-13T19:37:17.954195Z",
"updated": "2023-07-06T16:16:22.75737Z"
},
{
"id": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": null,
"controllerMachineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"controllerMachineType": "PowerEdge R750",
"hostname": "social-whiskey",
"machineCapabilities": [
{
"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2
},
{
"type": "Network",
"name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
"count": 2
},
{
"type": "Storage",
"name": "Dell Ent NVMe v2 AGN RI U.2 1.92TB",
"count": 2
},
{
"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"cores": 18,
"threads": 36,
"count": 2
}
],
"machineInterfaces": [
{
"id": "41847749-03af-4c8c-94b6-6722e32a603e",
"machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"controllerInterfaceId": "8b7ea73b-76d1-46be-8194-4c183c816a8f",
"controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
"subnetId": null,
"hostname": "social-whiskey",
"isPrimary": true,
"macAddress": "B8:3F:D2:90:99:B4",
"ipAddresses": [
"10.180.90.15/32"
],
"created": "2023-05-04T14:58:20.087651Z",
"updated": "2023-07-06T16:16:22.861989Z"
}
],
"status": "Ready",
"statusHistory": [],
"created": "2023-04-25T14:19:20.895831Z",
"updated": "2023-07-06T16:16:22.82906Z"
}
]
```
Use the value of `id` from the output of the preceding example as the value for the `infrastructureProviderId` and `siteId` URL parameters.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/ipblock?siteId=157627d6-d742-440b-ac04-77a618d94459" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
[
{
"id": "06c3d1a5-ed84-489a-96cc-4d644dc57ebb",
"name": "test-megan",
"description": null,
"siteId": "157627d6-d742-440b-ac04-77a618d94459",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": null,
"routingType": "Public",
"prefix": "100.100.0.0",
"prefixLength": 19,
"protocolVersion": "IPv4",
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "IP Block is ready for use",
"created": "2023-10-18T19:44:38.921567Z",
"updated": "2023-10-18T19:44:38.921567Z"
}
],
"deprecations": [],
"created": "2023-10-18T19:44:38.921567Z",
"updated": "2023-10-18T19:44:38.921567Z"
},
{
"id": "b88be53c-ba35-4b55-844b-fa581921f6f3",
"name": "demo-ipv4-block",
"description": "Demonstration IPv4 block",
"siteId": "157627d6-d742-440b-ac04-77a618d94459",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": null,
"routingType": "Public",
"prefix": "192.168.20.0",
"prefixLength": 24,
"protocolVersion": "IPv4",
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "IP Block is ready for use",
"created": "2023-10-16T17:20:21.214662Z",
"updated": "2023-10-16T17:20:21.214662Z"
}
],
"deprecations": [],
"created": "2023-10-16T17:20:21.214662Z",
"updated": "2023-10-16T17:20:21.214662Z"
},
{
"id": "a65e537e-ba93-4d69-ac5c-b7d177344890",
"name": "demo-ipv4-network-gold",
"description": "Demo IPv4 - Gold",
"siteId": "157627d6-d742-440b-ac04-77a618d94459",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": null,
"routingType": "Public",
"prefix": "192.168.4.128",
"prefixLength": 26,
"protocolVersion": "IPv4",
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "IP Block is ready for use",
"created": "2023-04-25T13:49:15.699358Z",
"updated": "2023-04-25T13:49:15.699358Z"
}
],
"deprecations": [],
"created": "2023-04-25T13:49:15.699358Z",
"updated": "2023-04-25T13:49:15.699358Z"
}
]
```
## Managing Virtual Private Clouds
`networkVirtualizationType` supports two VPC networking mechanisms: **FNN** is recommended for all deployments that include DPUs (instances in FNN VPCs reference a `vpcPrefixId` in their interface configuration.); **Legacy** VPCs use subnets instead of VPC prefixes. New deployments with DPUs should use FNN exclusively.
`tenantId` is the ID of the Tenant organization generated during setup. This value is distinct from the organization name used in the API URL path.
Create the VPC and specify a name.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-vpc",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"description": "Demo tenant VPC",
"networkVirtualizationType": "FNN"
}'
```
```json title={"Example Response"}
{
"id": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"name": "demo-vpc",
"description": "Demo tenant VPC",
"org": "tenant-org-name",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"controllerVpcId": null,
"networkVirtualizationType": "FNN",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "received vpc creation request, pending pairing",
"created": "2023-07-06T16:20:43.335989Z",
"updated": "2023-07-06T16:20:43.335989Z"
}
],
"created": "2023-07-06T16:20:43.335989Z",
"updated": "2023-07-06T16:20:43.335989Z"
}
```
Poll the VPC endpoint to confirm the status changes to `Ready`:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc/0b1c53a0-a27e-4714-98d7-0cd3bc579db2" \
-H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
{
"id": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"name": "demo-vpc",
"description": "Demo tenant VPC",
"org": "tenant-org-name",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"controllerVpcId": "b1e32ce0-49d4-48c7-bdc9-ecc1623c02f4",
"networkVirtualizationType": "FNN",
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "VPC successfully provisioned on Site",
"created": "2023-07-06T16:20:44.490895Z",
"updated": "2023-07-06T16:20:44.490895Z"
},
{
"status": "Provisioning",
"message": "initiated VPC provisioning via Site Agent",
"created": "2023-07-06T16:20:43.63647Z",
"updated": "2023-07-06T16:20:43.63647Z"
},
{
"status": "Pending",
"message": "received vpc creation request, pending pairing",
"created": "2023-07-06T16:20:43.335989Z",
"updated": "2023-07-06T16:20:43.335989Z"
}
],
"created": "2023-07-06T16:20:43.335989Z",
"updated": "2023-07-06T16:20:44.497876Z"
}
```
Add one or more compute instances. The `interfaces` array configures how each DPU port is assigned a network address. For FNN VPCs, specify a `vpcPrefixId`; for Legacy VPCs, specify a `subnetId`.
The `isPhysical` flag determines whether a physical function (PF) or a virtual function (VF) is configured on the DPU port. Set `isPhysical: true` for standard bare-metal configurations. VFs (`isPhysical: false`) are used when running VMs on the host that require direct hardware passthrough of a DPU port.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/instance" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-compute-instance-0",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
"userData": null,
"interfaces": [
{
"subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08"
}
]
}'
```
```json title={"Example Response"}
{
"id": "a4a1895b-d696-4d90-a670-357c2f3485b6",
"name": "demo-compute-instance-0",
"controllerInstanceId": "",
"allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userData": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123\n username: ubuntu\n\n ntp:\n enabled: true\n ntp_client: chrony\n servers:\n - 129.6.15.32\n\n keyboard:\n layout: us\n toggle: null\n variant: \"\"\n locale: en_US\n network:\n version: 2\n ethernets:\n ens5f0:\n critical: true\n dhcp-identifier: mac\n dhcp4: true\n nameservers:\n addresses: [8.8.8.8]\n ssh:\n allow-pw: true\n authorized-keys: []\n install-server: true\n\n disk_setup:\n ephemeral0:\n table_type: \"mbr\"\n layout: true\n /dev/nvme0n1:\n table_type: \"mbr\"\n layout:\n - 33\n - [33, 82]\n - 33\n overwrite: True\n",
"serialConsoleUrl": null,
"status": "Pending",
"interfaces": [
{
"id": "752bf819-a740-4e19-9f0e-b99ee9162392",
"instanceId": "a4a1895b-d696-4d90-a670-357c2f3485b6",
"subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
"isPhysical": true,
"macAddress": null,
"ipAddresses": null,
"status": "Pending",
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:04:00.338968Z"
}
],
"statusHistory": [
{
"status": "Pending",
"message": "received instance creation request, pending",
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:04:00.338968Z"
}
],
"deprecations": [],
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:04:00.338968Z"
}
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/instance" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-compute-instance-multiple-interfaces",
"instanceTypeId": "364dd639-5122-420c-a663-fa56e290e187",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
"userData": null,
"interfaces": [
{
"vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
"isPhysical": true,
"device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
"deviceInstance": 0
},
{
"vpcPrefixId": "8988dbd3-f038-4338-b961-8e5cbf89a77e",
"isPhysical": true,
"device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
"deviceInstance": 1
}
]
}'
```
```json title={"Example Response"}
{
"id": "9db49890-d015-464d-95d9-26e6714dbf8a",
"name": "demo-compute-instance-1",
"controllerInstanceId": "",
"allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userData": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123\n username: ubuntu\n\n ntp:\n enabled: true\n ntp_client: chrony\n servers:\n - 129.6.15.32\n\n keyboard:\n layout: us\n toggle: null\n variant: \"\"\n locale: en_US\n network:\n version: 2\n ethernets:\n ens5f0:\n critical: true\n dhcp-identifier: mac\n dhcp4: true\n nameservers:\n addresses: [8.8.8.8]\n ssh:\n allow-pw: true\n authorized-keys: []\n install-server: true\n\n disk_setup:\n ephemeral0:\n table_type: \"mbr\"\n layout: true\n /dev/nvme0n1:\n table_type: \"mbr\"\n layout:\n - 33\n - [33, 82]\n - 33\n overwrite: True\n",
"serialConsoleUrl": null,
"status": "Pending",
"interfaces": [
{
"id": "277fec57-abbc-43e1-8d81-1ae7b960b22f",
"instanceId": "9db49890-d015-464d-95d9-26e6714dbf8a",
"vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
"device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
"deviceInstance": 0,
"isPhysical": true,
"macAddress": null,
"ipAddresses": null,
"status": "Pending",
"created": "2023-07-06T17:07:36.268362Z",
"updated": "2023-07-06T17:07:36.268362Z"
},
{
"id": "62220366-4453-4f25-ae7c-d0109285c06f",
"instanceId": "9db49890-d015-464d-95d9-26e6714dbf8a",
"vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
"device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
"deviceInstance": 1,
"isPhysical": true,
"macAddress": null,
"ipAddresses": null,
"status": "Pending",
"created": "2023-07-06T17:07:36.268362Z",
"updated": "2023-07-06T17:07:36.268362Z"
}
],
"statusHistory": [
{
"status": "Pending",
"message": "received instance creation request, pending",
"created": "2023-07-06T17:07:36.268362Z",
"updated": "2023-07-06T17:07:36.268362Z"
}
],
"deprecations": [],
"created": "2023-07-06T17:07:36.268362Z",
"updated": "2023-07-06T17:07:36.268362Z"
}
```
Poll the Instance to confirm the status changes to `Ready`:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/instance/a4a1895b-d696-4d90-a670-357c2f3485b6" \
-H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
{
"id": "a4a1895b-d696-4d90-a670-357c2f3485b6",
"name": "demo-compute-instance-0",
"controllerInstanceId": "53ecddf2-fbaf-432f-9231-dc2f6bb8cf28",
"allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userData": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123\n username: ubuntu\n\n ntp:\n enabled: true\n ntp_client: chrony\n servers:\n - 129.6.15.32\n\n keyboard:\n layout: us\n toggle: null\n variant: \"\"\n locale: en_US\n network:\n version: 2\n ethernets:\n ens5f0:\n critical: true\n dhcp-identifier: mac\n dhcp4: true\n nameservers:\n addresses: [8.8.8.8]\n ssh:\n allow-pw: true\n authorized-keys: []\n install-server: true\n\n disk_setup:\n ephemeral0:\n table_type: \"mbr\"\n layout: true\n /dev/nvme0n1:\n table_type: \"mbr\"\n layout:\n - 33\n - [33, 82]\n - 33\n overwrite: True\n",
"serialConsoleUrl": "ssh://53ecddf2-fbaf-432f-9231-dc2f6bb8cf28@demo-site.example.com",
"status": "Ready",
"interfaces": [
{
"id": "752bf819-a740-4e19-9f0e-b99ee9162392",
"instanceId": "a4a1895b-d696-4d90-a670-357c2f3485b6",
"subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
"isPhysical": true,
"macAddress": null,
"ipAddresses": [
"192.166.128.2"
],
"status": "Ready",
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:07:23.628998Z"
}
],
"statusHistory": [
{
"status": "BootCompleted",
"message": "Instance is ready for use",
"created": "2023-07-06T17:07:23.618478Z",
"updated": "2023-07-06T17:07:23.618478Z"
},
{
"status": "Provisioning",
"message": "Instance provisioning was successfully initiated on Site",
"created": "2023-07-06T17:04:03.277049Z",
"updated": "2023-07-06T17:04:03.277049Z"
},
{
"status": "Provisioning",
"message": "Provisioning request was sent to the Site",
"created": "2023-07-06T17:04:02.269136Z",
"updated": "2023-07-06T17:04:02.269136Z"
},
{
"status": "Pending",
"message": "received instance creation request, pending",
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:04:00.338968Z"
}
],
"deprecations": [],
"created": "2023-07-06T17:04:00.338968Z",
"updated": "2023-07-06T17:07:23.608281Z"
}
```
## Allocating Machines
Before allocating Machines, you should have the ID of the Instance Type. You can get the ID by making a `GET` request to the `/v2/org/{org-name}/nico/instance/type` endpoint and specifying the `infrastructureProviderId=` and `siteId=` parameters.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/allocation" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-compute-allocation",
"description": "Demo compute instance allocation",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"allocationConstraints": [
{
"resourceType": "InstanceType",
"resourceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"constraintType": "Reserved",
"constraintValue": 2
}
]
}'
```
```json title={"Example Response"}
{
"id": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
"name": "demo-compute-allocation",
"description": "Demo compute instance allocation",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"status": "Registered",
"statusHistory": [
{
"status": "Registered",
"message": "received allocation creation request, registered",
"created": "2023-07-06T16:18:59.35228Z",
"updated": "2023-07-06T16:18:59.35228Z"
}
],
"created": "2023-07-06T16:18:59.35228Z",
"updated": "2023-07-06T16:18:59.35228Z",
"allocationConstraints": [
{
"id": "13eab768-4e65-4582-84de-d524be8a7830",
"allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
"resourceType": "InstanceType",
"ResourceTypeID": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"constraintType": "Reserved",
"constraintValue": 2,
"derivedResourceId": null,
"created": "2023-07-06T16:18:59.35228Z",
"updated": "2023-07-06T16:18:59.35228Z"
}
]
}
```
## Assigning Instance Types to Machines
Before assigning Instance Types, you should have the ID of the Instance Type. You can get the ID by making a `GET` request to the `/v2/org/{org-name}/nico/instance/type` endpoint and specifying the `siteId=` parameter.
Get the machines that do not have an instance type assigned and that report a status of `Ready`:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/machine?siteId=157627d6-d742-440b-ac04-77a618d94459&hasInstanceType=false&status=Ready" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
[
{
"id": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": null,
"controllerMachineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"controllerMachineType": "PowerEdge R750",
"hostname": "sad-uniform",
"machineCapabilities": [
{
"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"cores": 18,
"threads": 36,
"count": 2
},
{
"type": "Storage",
"name": "Dell Ent NVMe CM6 RI 1.92TB",
"count": 3
},
{
"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2
},
{
"type": "Network",
"name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
"count": 2
},
{
"type": "Network",
"name": "BCM57414 NetXtreme-E 10Gb/25Gb RDMA Ethernet Controller",
"count": 2
}
],
"machineInterfaces": [
{
"id": "6dd628a3-cc5b-4b12-8a5b-acad0160c7c3",
"machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"controllerInterfaceId": "029a9fdf-c232-4e8d-9327-4c271ad7ea01",
"controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
"subnetId": null,
"hostname": "sad-uniform",
"isPrimary": true,
"macAddress": "B8:3F:D2:90:97:04",
"ipAddresses": [
"10.180.90.10/32"
],
"created": "2023-05-04T14:22:17.121178Z",
"updated": "2023-07-06T16:16:22.777176Z"
}
],
"status": "Ready",
"statusHistory": [],
"created": "2023-04-13T19:37:17.954195Z",
"updated": "2023-07-06T16:16:22.75737Z"
},
{
"id": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": null,
"controllerMachineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"controllerMachineType": "PowerEdge R750",
"hostname": "social-whiskey",
"machineCapabilities": [
{
"type": "Network",
"name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
"count": 2
},
{
"type": "Network",
"name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
"count": 2
},
{
"type": "Storage",
"name": "Dell Ent NVMe v2 AGN RI U.2 1.92TB",
"count": 2
},
{
"type": "CPU",
"name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
"cores": 18,
"threads": 36,
"count": 2
}
],
"machineInterfaces": [
{
"id": "41847749-03af-4c8c-94b6-6722e32a603e",
"machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"controllerInterfaceId": "8b7ea73b-76d1-46be-8194-4c183c816a8f",
"controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
"subnetId": null,
"hostname": "social-whiskey",
"isPrimary": true,
"macAddress": "B8:3F:D2:90:99:B4",
"ipAddresses": [
"10.180.90.15/32"
],
"created": "2023-05-04T14:58:20.087651Z",
"updated": "2023-07-06T16:16:22.861989Z"
}
],
"status": "Ready",
"statusHistory": [],
"created": "2023-04-25T14:19:20.895831Z",
"updated": "2023-07-06T16:16:22.82906Z"
}
]
```
You can specify one or more machine IDs in the `machineIds` parameter.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/instance/type/9c4aaa6a-3934-4274-b0a9-5143b253039e/machine" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"machineIds": [
"fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g"
]
}'
```
```json title={"Example Response"}
[
{
"id": "5e782d7f-78f6-47bf-a540-13b7e56897e7",
"machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"created": "2023-07-06T16:18:26.611048Z",
"updated": "2023-07-06T16:18:26.611048Z"
},
{
"id": "335fc255-fd3b-4602-bd2e-86b5b444a178",
"machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
"instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
"created": "2023-07-06T16:18:26.611048Z",
"updated": "2023-07-06T16:18:26.611048Z"
}
]
```
## Managing Operating Systems
Before adding an operating system image, ensure you have:
- An iPXE script as a one-line string.
- **Optional**: A cloud-init script as a one-line string.
- For the iPXE string and cloud-init string, replace newline characters with `\n` and escape quotation marks with `\"`.
- Your Tenant ID.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/operating-system" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-ipxe-os",
"description": "Demo tenant operating system",
"tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
"allowOverride": true,
"isCloudInit": true,
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userData": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123\n username: ubuntu\n\n ntp:\n enabled: true\n ntp_client: chrony\n servers:\n - 129.6.15.32\n\n keyboard:\n layout: us\n toggle: null\n variant: \"\"\n locale: en_US\n ssh:\n allow-pw: true\n authorized-keys: []\n install-server: true\n"
}'
```
```json title={"Example Response"}
{
"id": "44d246f3-3075-4daa-9887-0d376bf9dec5",
"name": "demo-ipxe-os",
"description": "Demo tenant operating system",
"infrastructureProviderId": null,
"tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userData": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123\n username: ubuntu\n\n ntp:\n enabled: true\n ntp_client: chrony\n servers:\n - 129.6.15.32\n\n keyboard:\n layout: us\n toggle: null\n variant: \"\"\n locale: en_US\n ssh:\n allow-pw: true\n authorized-keys: []\n install-server: true\n",
"isCloudInit": true,
"allowOverride": true,
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "Operating System is ready for use",
"created": "2023-09-06T18:39:37.607905Z",
"updated": "2023-09-06T18:39:37.607905Z"
}
],
"created": "2023-09-06T18:39:37.607905Z",
"updated": "2023-09-06T18:39:37.607905Z"
}
```
## Managing Subnets and VPC Prefixes
Before managing Subnets, ensure you have at least one IP Block allocated so that you can add a Subnet of the IP Block address space.
Add one or more subnets. The following command sample shows how to add one subnet.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/subnet" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-ipv4-subnet",
"description": "Demo IPv4 Tenant Subnet",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"prefixLength": 28
}'
```
```json title={"Example Response"}
{
"id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
"name": "demo-ipv4-subnet",
"description": "Demo IPv4 Tenant Subnet",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"controllerNetworkSegmentId": null,
"ipv4Prefix": "192.166.128.0",
"ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"ipv4Gateway": "192.166.128.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"mtu": 9000,
"prefixLength": 28,
"routingType": "Public",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "received subnet creation request, pending",
"created": "2023-07-06T16:21:34.916407Z",
"updated": "2023-07-06T16:21:34.916407Z"
}
],
"deprecations": [],
"created": "2023-07-06T16:21:34.916407Z",
"updated": "2023-07-06T16:21:34.916407Z"
}
```
Poll the subnet endpoint to confirm that the status changes to `Ready`:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/subnet/5e1f6c51-a532-437b-b7a5-7dfac214de08" \
-H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
{
"id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
"name": "demo-ipv4-subnet",
"description": "Demo IPv4 Tenant Subnet",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"controllerNetworkSegmentId": "f5634c31-4cd4-453b-8ac5-e81f2a19ab05",
"ipv4Prefix": "192.166.128.0",
"ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"ipv4Gateway": "192.166.128.1",
"ipv6Prefix": null,
"ipv6BlockId": null,
"ipv6Gateway": null,
"mtu": 9000,
"prefixLength": 28,
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "Subnet is ready for use",
"created": "2023-07-06T16:25:20.717794Z",
"updated": "2023-07-06T16:25:20.717794Z"
},
{
"status": "Provisioning",
"message": "Subnet provisioning was successfully initiated on Site",
"created": "2023-07-06T16:21:36.830555Z",
"updated": "2023-07-06T16:21:36.830555Z"
},
{
"status": "Provisioning",
"message": "Provisioning request was sent to the Site",
"created": "2023-07-06T16:21:35.538119Z",
"updated": "2023-07-06T16:21:35.538119Z"
},
{
"status": "Pending",
"message": "received subnet creation request, pending",
"created": "2023-07-06T16:21:34.916407Z",
"updated": "2023-07-06T16:21:34.916407Z"
}
],
"deprecations": [],
"created": "2023-07-06T16:21:34.916407Z",
"updated": "2023-07-06T16:25:20.70757Z"
}
```
The following command sample shows how to add one VPC prefix. You can also add multiple VPC prefixes at once.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc-prefix" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-ipv4-vpc-prefix",
"description": "Demo IPv4 Tenant VPC Prefix",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"ipBlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"prefixLength": 28
}'
```
```json title={"Example Response"}
{
"id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
"name": "demo-ipv4-vpc-prefix",
"description": "Demo IPv4 Tenant VPC Prefix",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"ipBlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"prefix": "10.217.98.208/28",
"prefixLength": 28,
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "Received VPC prefix creation request, ready",
"created": "2023-07-06T16:25:20.717794Z",
"updated": "2023-07-06T16:25:20.717794Z"
}
],
"created": "2023-07-06T16:21:34.916407Z",
"updated": "2023-07-06T16:25:20.70757Z"
}
```
## Managing IP Blocks
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/ipblock" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-ipv4-block",
"description": "Demo IPv4 block",
"prefixLength": 24,
"prefix": "192.166.128.0",
"protocolVersion": "IPv4",
"routingType": "DatacenterOnly",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8"
}'
```
```json title={"Example Response"}
{
"id": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
"name": "demo-ipv4-block",
"description": "Demo IPv4 block",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": null,
"routingType": "DatacenterOnly",
"prefix": "192.166.128.0",
"prefixLength": 24,
"protocolVersion": "IPv4",
"status": "Ready",
"statusHistory": [
{
"status": "Ready",
"message": "IP Block is ready for use",
"created": "2023-07-06T16:17:46.911267Z",
"updated": "2023-07-06T16:17:46.911267Z"
}
],
"deprecations": [],
"created": "2023-07-06T16:17:46.911267Z",
"updated": "2023-07-06T16:17:46.911267Z"
}
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/allocation" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-ipv4-allocation",
"description": "Demo IPv4 allocation",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"allocationConstraints": [
{
"resourceType": "IPBlock",
"resourceTypeId": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
"constraintType": "Reserved",
"constraintValue": 24
}
]
}'
```
```json title={"Example Response"}
{
"id": "98c356e0-0c96-45ef-a65d-319338190955",
"name": "demo-ipv4-allocation",
"description": "Demo IPv4 allocation",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"status": "Registered",
"statusHistory": [
{
"status": "Registered",
"message": "received allocation creation request, registered",
"created": "2023-07-06T16:18:02.513471Z",
"updated": "2023-07-06T16:18:02.513471Z"
}
],
"created": "2023-07-06T16:18:02.513471Z",
"updated": "2023-07-06T16:18:02.513471Z",
"allocationConstraints": [
{
"id": "5eef34d5-8644-4a5c-9604-a4a72b42118e",
"allocationId": "98c356e0-0c96-45ef-a65d-319338190955",
"resourceType": "IPBlock",
"ResourceTypeID": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
"constraintType": "Reserved",
"constraintValue": 24,
"derivedResourceId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
"created": "2023-07-06T16:18:02.513471Z",
"updated": "2023-07-06T16:18:02.513471Z"
}
]
}
```
## Managing Network Security Groups
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{org}/nico/network-security-group" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
[
{
"id": "string",
"name": "string",
"description": "string",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"rules": [
{
"name": "string",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "80-81",
"protocol": "TCP",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "10.5.44.0/24",
"destinationPrefix": "10.5.44.0/24"
}
],
"labels": {},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
]
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{org}/nico/network-security-group" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "string",
"description": "string",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"rules": [
{
"name": "string",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "80-81",
"protocol": "TCP",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "10.5.44.0/24",
"destinationPrefix": "10.5.44.0/24"
}
],
"labels": {}
}'
```
```json title={"Example Response"}
{
"id": "string",
"name": "string",
"description": "string",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"rules": [
{
"name": "string",
"direction": "INGRESS",
"sourcePortRange": "80-81",
"destinationPortRange": "80-81",
"protocol": "TCP",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "10.5.44.0/24",
"destinationPrefix": "10.5.44.0/24"
}
],
"labels": {},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{org}/nico/network-security-group" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "string",
"description": "string",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"rules": [
{
"name": "allow-all-ingress",
"direction": "INGRESS",
"sourcePortRange": "0-65535",
"destinationPortRange": "0-65535",
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "0.0.0.0/0"
},
{
"name": "allow-all-egress",
"direction": "EGRESS",
"sourcePortRange": "0-65535",
"destinationPortRange": "0-65535",
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "0.0.0.0/0"
}
],
"labels": {
"property1": "default",
"property2": "global-allow"
}
}'
```
```json title={"Example Response"}
[
{
"id": "ea9c9eac-0e3d-4c85-b0e0-1e174b214c8f",
"name": "allow-all",
"description": "Allow all L4 traffic in all directions",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "Request received, pending processing",
"created": "2025-05-22T12:00:00Z",
"updated": "2025-05-22T12:00:00Z"
}
],
"rules": [
{
"name": "allow-all-ingress",
"direction": "INGRESS",
"sourcePortRange": null,
"destinationPortRange": null,
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "0.0.0.0/0"
},
{
"name": "allow-all-egress",
"direction": "EGRESS",
"sourcePortRange": null,
"destinationPortRange": null,
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "0.0.0.0/0"
}
],
"labels": {
"property1": "default",
"property2": "global-allow"
},
"created": "2025-05-22T12:00:00Z",
"updated": "2025-05-22T12:00:00Z"
}
]
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X PATCH "https://api.example.com/v2/org/{org}/nico/network-security-group/{nsgId}" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"rules": [
{
"name": "allow-all-ingress",
"direction": "INGRESS",
"sourcePortRange": "0-65535",
"destinationPortRange": "0-65535",
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "192.168.1.0/24",
"destinationPrefix": "0.0.0.0/0"
}
]
}'
```
```json title={"Example Response"}
{
"id": "string",
"name": "string",
"description": "string",
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
"status": "Pending",
"statusHistory": [
{
"status": "Pending",
"message": "Request received, pending processing",
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
],
"rules": [
{
"name": "allow-all-ingress",
"direction": "INGRESS",
"sourcePortRange": "0-65535",
"destinationPortRange": "0-65535",
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "192.168.1.0/24",
"destinationPrefix": "0.0.0.0/0"
},
{
"name": "allow-all-egress",
"direction": "EGRESS",
"sourcePortRange": "0-65535",
"destinationPortRange": "0-65535",
"protocol": "ANY",
"action": "PERMIT",
"priority": 0,
"sourcePrefix": "0.0.0.0/0",
"destinationPrefix": "0.0.0.0/0"
}
],
"labels": {
"property1": "default",
"property2": "global-allow"
},
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
```
## Accessing the Serial Console
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X PATCH "https://api.example.com/v2/org/{provider-org-name}/nico/site/2ae25bd4-7b07-4b39-9514-031e5c335f4f" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"isSerialConsoleEnabled": true,
"serialConsoleHostname": "10.217.126.53",
"serialConsoleIdleTimeout": 7200,
"serialConsoleMaxSessionLength": 86400
}'
```
```json title={"Example Response"}
{
"id": "2ae25bd4-7b07-4b39-9514-031e5c335f4f",
"name": "demo-site-a",
"description": "Demo Site A",
"org": "provider-org-name",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteControllerVersion": null,
"siteAgentVersion": null,
"registrationToken": null,
"registrationTokenExpiration": "2023-11-01T01:47:36.000397Z",
"serialConsoleHostname": "192.168.126.53",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 7200,
"serialConsoleMaxSessionLength": 86400,
"isOnline": true,
"deprecations": [],
"status": "Registered",
"statusHistory": [
{
"status": "Registered",
"message": "Site has been successfully paired",
"created": "2023-10-31T01:49:19.604387Z",
"updated": "2023-10-31T01:49:19.604387Z"
}
],
"created": "2023-06-07T00:56:04.261575Z",
"updated": "2023-11-01T15:02:01.914645Z"
}
```
The SSH key should be in RSA, ECDSA, or ED25519 format. Add the SSH Key Group:
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "demo-team-0-group",
"description": "Demo team group"
}'
```
Note the value of the `version` field — you will need it to update the SSH Key Group.
```json title={"Example Response"}
{
"id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
"name": "demo-team-0-group",
"description": "Demo team group",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"version": "6a5ccd83b5daf693bd14ab32a439d3181635be6f",
"status": "Synced",
"statusHistory": [
{
"status": "Syncing",
"message": "received SSH Key Group creation request, syncing",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
},
{
"status": "Synced",
"message": "SSH Key Group has successfully been synced to all Sites",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
}
],
"sshKeys": [],
"siteAssociations": [],
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.693571Z"
}
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkey" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"name": "customer-0",
"description": "Demo public SSH key",
"publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo-user@nvdia.com"
}'
```
```json title={"Example Response"}
{
"id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
"name": "customer-0",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
"created": "2023-11-01T12:37:30.554055Z",
"updated": "2023-11-01T12:37:30.554055Z"
}
```
Specify the new and existing key IDs to keep in the `sshKeyIds` field.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X PATCH "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup/9ffb8f90-f88f-4420-952d-e911f446d7eb" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"version": "6a5ccd83b5daf693bd14ab32a439d3181635be6f",
"sshKeyIds": [
"b658db7e-f06c-4140-9494-48ea1f3f7769"
]
}'
```
```json title={"Example Response"}
{
"id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
"name": "demo-team-0-group",
"description": "Demo team group",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"version": "23220d11a579258cb810942060e910fb3fac9762",
"status": "Syncing",
"statusHistory": [
{
"status": "Syncing",
"message": "received SSH Key Group update request, syncing",
"created": "2023-11-01T12:37:44.969029Z",
"updated": "2023-11-01T12:37:44.969029Z"
},
{
"status": "Syncing",
"message": "received SSH Key Group creation request, syncing",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
},
{
"status": "Synced",
"message": "SSH Key Group has successfully been synced to all Sites",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
}
],
"sshKeys": [
{
"id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
"name": "customer-0",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
"created": "2023-11-01T12:37:30.554055Z",
"updated": "2023-11-01T12:37:30.554055Z"
}
],
"siteAssociations": [],
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:45.007738Z"
}
```
Specify the new and existing Site IDs to keep in the `siteIds` field. You can combine this step and the preceding step by specifying both the SSH Key IDs and Site IDs in the same request.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X PATCH "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup/9ffb8f90-f88f-4420-952d-e911f446d7eb" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}" \
-d '{
"version": "23220d11a579258cb810942060e910fb3fac9762",
"siteIds": [
"157627d6-d742-440b-ac04-77a618d94459"
]
}'
```
```json title={"Example Response"}
{
"id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
"name": "demo-team-0-group",
"description": "Demo team group",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"version": "7fa801416ce27ec68d9dd531eb6948a9a5f4ed87",
"status": "Syncing",
"statusHistory": [
{
"status": "Syncing",
"message": "received SSH Key Group update request, syncing",
"created": "2023-11-01T12:38:04.208273Z",
"updated": "2023-11-01T12:38:04.208273Z"
},
{
"status": "Syncing",
"message": "received SSH Key Group update request, syncing",
"created": "2023-11-01T12:37:44.969029Z",
"updated": "2023-11-01T12:37:44.969029Z"
},
{
"status": "Syncing",
"message": "received SSH Key Group creation request, syncing",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
},
{
"status": "Synced",
"message": "SSH Key Group has successfully been synced to all Sites",
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:37:22.649619Z"
}
],
"sshKeys": [
{
"id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
"name": "customer-0",
"org": "tenant-org-name",
"tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
"fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
"created": "2023-11-01T12:37:30.554055Z",
"updated": "2023-11-01T12:37:30.554055Z"
}
],
"siteAssociations": [
{
"site": {
"id": "157627d6-d742-440b-ac04-77a618d94459",
"name": "demo-site-a",
"description": "Demo Site",
"org": "provider-org-name",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteControllerVersion": null,
"siteAgentVersion": null,
"registrationToken": null,
"registrationTokenExpiration": null,
"serialConsoleHostname": "192.168.126.6",
"isSerialConsoleEnabled": true,
"serialConsoleIdleTimeout": 300,
"serialConsoleMaxSessionLength": 86400,
"isSerialConsoleSSHKeysEnabled": false,
"isOnline": true,
"deprecations": [],
"status": "Registered",
"statusHistory": [],
"created": "2023-04-21T17:30:08.425798Z",
"updated": "2023-11-01T12:37:53.579769Z"
},
"version": "3af0d2e8136292010bb23afeb8de1c009e343cb2",
"status": "Syncing",
"created": "2023-11-01T12:38:04.208273Z",
"updated": "2023-11-01T12:38:04.256966Z"
}
],
"created": "2023-11-01T12:37:22.649619Z",
"updated": "2023-11-01T12:38:04.251866Z"
}
```
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
curl -X GET "https://api.example.com/v2/org/{tenant-org-name}/nico/instance?vpcId=f466a2d5-5820-4824-a845-3218fdff801b" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-H "Authorization: Bearer ${TOKEN}"
```
```json title={"Example Response"}
[
{
"id": "83ad26bc-4687-4427-b01c-0857599d1b17",
"name": "demo-compute-instance-1",
"controllerInstanceId": "c0da5caa-76d6-4a5a-abf7-992b75fec7ae",
"allocationId": "c4d1b674-d061-4e95-946e-667149a88113",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": "7aa0864b-71b2-4253-af7d-d957e288ff57",
"vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
"machineId": "2ff5f788-7430-424a-86f8-87d371256496",
"operatingSystemId": "7471cecd-88f6-40f0-b1a2-d53f29573bf3",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userdata": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123+\n username: ubuntu\n",
"serialConsoleUrl": "ssh://c0da5caa-76d6-4a5a-abf7-992b75fec7ae@reno.nico.nvidia.com",
"status": "Ready",
"instanceSubnets": [
{
"id": "09142b2f-85c3-4e09-aeb2-34e7db19a36d",
"instanceId": "83ad26bc-4687-4427-b01c-0857599d1b17",
"subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
"isPhysical": true,
"macAddress": null,
"ipAddresses": [
"192.166.128.3"
],
"status": "Ready",
"created": "2023-04-26T19:37:32.445684Z",
"updated": "2023-04-26T19:40:18.427811Z"
}
],
"interfaces": [
{
"id": "09142b2f-85c3-4e09-aeb2-34e7db19a36d",
"instanceId": "83ad26bc-4687-4427-b01c-0857599d1b17",
"subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
"isPhysical": true,
"macAddress": null,
"ipAddresses": [
"192.166.128.3"
],
"status": "Ready",
"created": "2023-04-26T19:37:32.445684Z",
"updated": "2023-04-26T19:40:18.427811Z"
}
],
"statusHistory": [
{
"status": "BootCompleted",
"message": "Instance is ready for use",
"created": "2023-04-26T19:40:18.418073Z",
"updated": "2023-04-26T19:40:18.418073Z"
},
{
"status": "Provisioning",
"message": "Instance provisioning was successfully initiated on Site",
"created": "2023-04-26T19:37:34.405577Z",
"updated": "2023-04-26T19:37:34.405577Z"
},
{
"status": "Provisioning",
"message": "Provisioning request was sent to the Site",
"created": "2023-04-26T19:37:33.599048Z",
"updated": "2023-04-26T19:37:33.599048Z"
},
{
"status": "Pending",
"message": "received instance creation request, pending",
"created": "2023-04-26T19:37:32.445684Z",
"updated": "2023-04-26T19:37:32.445684Z"
}
],
"created": "2023-04-26T19:37:32.445684Z",
"updated": "2023-04-26T19:40:18.40905Z"
},
{
"id": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
"name": "demo-compute-instance-0",
"controllerInstanceId": "16708e55-012c-46b6-a1c6-815d45ba45bc",
"allocationId": "c4d1b674-d061-4e95-946e-667149a88113",
"tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
"infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
"siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
"instanceTypeId": "7aa0864b-71b2-4253-af7d-d957e288ff57",
"vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
"machineId": "e6e1b8b2-5ae5-4093-997e-eecb8baf528a",
"operatingSystemId": "7471cecd-88f6-40f0-b1a2-d53f29573bf3",
"ipxeScript": "#!ipxe\nkernel https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/vmlinuz ip=dhcp fb=false interface=ens5f0 url=https://releases.ubuntu.com/20.04.6/ubuntu-20.04.6-live-server-amd64.iso autoinstall ds=nocloud-net;s=${cloudinit-url} initrd=initrd.magic\ninitrd https://github.com/netbootxyz/ubuntu-squash/releases/download/20.04.6-a1b16d57/initrd\nboot\n",
"userdata": "#cloud-config\nusers:\n - default\n - name: demo-user\n gecos: Demo User\n sudo: ALL=(ALL) NOPASSWD:ALL\n groups: root\n lock_passwd: true\n ssh_authorized_keys:\n - ssh-ed25519 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo@example.com\n\nautoinstall:\n version: 1\n\n identity:\n hostname: demo-host\n password: $6$jCfWFbdxh1lK09sY$pxFnrW/yXewYFmgoaywu3WKhdPQg0e8DR8jvedAV.udXM0.i5M6wr4Up2S7ZCN9kNDmg.s7fmrOaXE6nEyzPb/ # Welcome123+\n username: ubuntu\n",
"serialConsoleUrl": "ssh://16708e55-012c-46b6-a1c6-815d45ba45bc@reno.nico.nvidia.com",
"status": "Ready",
"instanceSubnets": [
{
"id": "10758364-57f9-4429-84a2-5dede1b5045f",
"instanceId": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
"subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
"isPhysical": true,
"macAddress": null,
"ipAddresses": [
"192.166.128.2"
],
"status": "Ready",
"created": "2023-04-26T19:34:40.96039Z",
"updated": "2023-04-26T19:40:18.372682Z"
}
],
"interfaces": [
{
"id": "10758364-57f9-4429-84a2-5dede1b5045f",
"instanceId": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
"subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
"isPhysical": true,
"macAddress": null,
"ipAddresses": [
"192.166.128.2"
],
"status": "Ready",
"created": "2023-04-26T19:34:40.96039Z",
"updated": "2023-04-26T19:40:18.372682Z"
}
],
"statusHistory": [
{
"status": "BootCompleted",
"message": "Instance is ready for use",
"created": "2023-04-26T19:37:18.21838Z",
"updated": "2023-04-26T19:37:18.21838Z"
},
{
"status": "Provisioning",
"message": "Instance provisioning was successfully initiated on Site",
"created": "2023-04-26T19:34:43.651979Z",
"updated": "2023-04-26T19:34:43.651979Z"
},
{
"status": "Provisioning",
"message": "Provisioning request was sent to the Site",
"created": "2023-04-26T19:34:42.278639Z",
"updated": "2023-04-26T19:34:42.278639Z"
},
{
"status": "Pending",
"message": "received instance creation request, pending",
"created": "2023-04-26T19:34:40.96039Z",
"updated": "2023-04-26T19:34:40.96039Z"
}
],
"created": "2023-04-26T19:34:40.96039Z",
"updated": "2023-04-26T19:37:18.191004Z"
}
]
```
Use a command like the following to retrieve the IP Addresses from the response, then access the host or application deployed on the Instance.
```sh title={"Example Call"}
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
jq '[ .[] | {name: .name, ipAddresses: .instanceSubnets[].ipAddresses } ]'
```
```json title={"Example Response"}
[
{
"name": "demo-compute-instance-1",
"ipAddresses": [
"192.166.128.3"
]
},
{
"name": "demo-compute-instance-0",
"ipAddresses": [
"192.166.128.2"
]
}
]
```