Example REST API Workflows | NVIDIA Infra Controller

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

View Your Sites

Use the value of id from the output of the preceding example as the value for the infrastructureProviderId URL parameter:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/site" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}"

The Site ID in the response is a required input for many configuration requests.

Example Response

1 [
2     {
3       "id": "bd4692bd-da95-410e-911a-d492fe2d35f8",
4       "name": "demo-site",
5       "description": "nico site",
6       "org": "wdksahew1rqv",
7       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
8       "siteControllerVersion": null,
9       "siteAgentVersion": null,
10       "registrationToken": null,
11       "registrationTokenExpiration": "2023-05-03T22:18:45.23286Z",
12       "serialConsoleHostname": "example.console.com",
13       "isSerialConsoleEnabled": true,
14       "serialConsoleIdleTimeout": null,
15       "serialConsoleMaxSessionLength": null,
16       "deprecations": [],
17       "status": "Registered",
18       "statusHistory": [
19         {
20           "status": "Registered",
21           "message": "Site has been successfully paired",
22           "created": "2023-05-02T22:20:04.627469Z",
23           "updated": "2023-05-02T22:20:04.627469Z"
24         },
25         {
26           "status": "Pending",
27           "message": "registration token renewed, pending pairing",
28           "created": "2023-05-02T22:18:45.262934Z",
29           "updated": "2023-05-02T22:18:45.262934Z"
30         }
31       ],
32       "created": "2023-01-20T21:36:41.339466Z",
33       "updated": "2023-07-06T16:19:20.104353Z"
34     }
35   ]

View Your Machines

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.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/machine?siteId=157627d6-d742-440b-ac04-77a618d94459&hasInstanceType=false&status=Ready" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}"

Example Response

1 [
2     {
3       "id": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
4       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
5       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6       "instanceTypeId": null,
7       "controllerMachineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
8       "controllerMachineType": "PowerEdge R750",
9       "hostname": "sad-uniform",
10       "machineCapabilities": [
11         {
12           "type": "CPU",
13           "name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
14           "cores": 18,
15           "threads": 36,
16           "count": 2
17         },
18         {
19           "type": "Storage",
20           "name": "Dell Ent NVMe CM6 RI 1.92TB",
21           "count": 3
22         },
23         {
24           "type": "Network",
25           "name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
26           "count": 2
27         },
28         {
29           "type": "Network",
30           "name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
31           "count": 2
32         },
33         {
34           "type": "Network",
35           "name": "BCM57414 NetXtreme-E 10Gb/25Gb RDMA Ethernet Controller",
36           "count": 2
37         }
38       ],
39       "machineInterfaces": [
40         {
41           "id": "6dd628a3-cc5b-4b12-8a5b-acad0160c7c3",
42           "machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
43           "controllerInterfaceId": "029a9fdf-c232-4e8d-9327-4c271ad7ea01",
44           "controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
45           "subnetId": null,
46           "hostname": "sad-uniform",
47           "isPrimary": true,
48           "macAddress": "B8:3F:D2:90:97:04",
49           "ipAddresses": [
50             "10.180.90.10/32"
51           ],
52           "created": "2023-05-04T14:22:17.121178Z",
53           "updated": "2023-07-06T16:16:22.777176Z"
54         }
55       ],
56       "status": "Ready",
57       "statusHistory": [],
58       "created": "2023-04-13T19:37:17.954195Z",
59       "updated": "2023-07-06T16:16:22.75737Z"
60     },
61     {
62       "id": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
63       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
64       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
65       "instanceTypeId": null,
66       "controllerMachineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
67       "controllerMachineType": "PowerEdge R750",
68       "hostname": "social-whiskey",
69       "machineCapabilities": [
70         {
71           "type": "Network",
72           "name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
73           "count": 2
74         },
75         {
76           "type": "Network",
77           "name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
78           "count": 2
79         },
80         {
81           "type": "Storage",
82           "name": "Dell Ent NVMe v2 AGN RI U.2 1.92TB",
83           "count": 2
84         },
85         {
86           "type": "CPU",
87           "name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
88           "cores": 18,
89           "threads": 36,
90           "count": 2
91         }
92       ],
93       "machineInterfaces": [
94         {
95           "id": "41847749-03af-4c8c-94b6-6722e32a603e",
96           "machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
97           "controllerInterfaceId": "8b7ea73b-76d1-46be-8194-4c183c816a8f",
98           "controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
99           "subnetId": null,
100           "hostname": "social-whiskey",
101           "isPrimary": true,
102           "macAddress": "B8:3F:D2:90:99:B4",
103           "ipAddresses": [
104             "10.180.90.15/32"
105           ],
106           "created": "2023-05-04T14:58:20.087651Z",
107           "updated": "2023-07-06T16:16:22.861989Z"
108         }
109       ],
110       "status": "Ready",
111       "statusHistory": [],
112       "created": "2023-04-25T14:19:20.895831Z",
113       "updated": "2023-07-06T16:16:22.82906Z"
114     }
115   ]

View Existing IP Blocks

Use the value of id from the output of the preceding example as the value for the infrastructureProviderId and siteId URL parameters.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/ipblock?siteId=157627d6-d742-440b-ac04-77a618d94459" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}"

Example Response

1 [
2     {
3       "id": "06c3d1a5-ed84-489a-96cc-4d644dc57ebb",
4       "name": "test-megan",
5       "description": null,
6       "siteId": "157627d6-d742-440b-ac04-77a618d94459",
7       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
8       "tenantId": null,
9       "routingType": "Public",
10       "prefix": "100.100.0.0",
11       "prefixLength": 19,
12       "protocolVersion": "IPv4",
13       "status": "Ready",
14       "statusHistory": [
15         {
16           "status": "Ready",
17           "message": "IP Block is ready for use",
18           "created": "2023-10-18T19:44:38.921567Z",
19           "updated": "2023-10-18T19:44:38.921567Z"
20         }
21       ],
22       "deprecations": [],
23       "created": "2023-10-18T19:44:38.921567Z",
24       "updated": "2023-10-18T19:44:38.921567Z"
25     },
26     {
27       "id": "b88be53c-ba35-4b55-844b-fa581921f6f3",
28       "name": "demo-ipv4-block",
29       "description": "Demonstration IPv4 block",
30       "siteId": "157627d6-d742-440b-ac04-77a618d94459",
31       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
32       "tenantId": null,
33       "routingType": "Public",
34       "prefix": "192.168.20.0",
35       "prefixLength": 24,
36       "protocolVersion": "IPv4",
37       "status": "Ready",
38       "statusHistory": [
39         {
40           "status": "Ready",
41           "message": "IP Block is ready for use",
42           "created": "2023-10-16T17:20:21.214662Z",
43           "updated": "2023-10-16T17:20:21.214662Z"
44         }
45       ],
46       "deprecations": [],
47       "created": "2023-10-16T17:20:21.214662Z",
48       "updated": "2023-10-16T17:20:21.214662Z"
49     },
50     {
51       "id": "a65e537e-ba93-4d69-ac5c-b7d177344890",
52       "name": "demo-ipv4-network-gold",
53       "description": "Demo IPv4 - Gold",
54       "siteId": "157627d6-d742-440b-ac04-77a618d94459",
55       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
56       "tenantId": null,
57       "routingType": "Public",
58       "prefix": "192.168.4.128",
59       "prefixLength": 26,
60       "protocolVersion": "IPv4",
61       "status": "Ready",
62       "statusHistory": [
63         {
64           "status": "Ready",
65           "message": "IP Block is ready for use",
66           "created": "2023-04-25T13:49:15.699358Z",
67           "updated": "2023-04-25T13:49:15.699358Z"
68         }
69       ],
70       "deprecations": [],
71       "created": "2023-04-25T13:49:15.699358Z",
72       "updated": "2023-04-25T13:49:15.699358Z"
73     }
74   ]

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 a VPC

Create the VPC and specify a name.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8    "name": "demo-vpc",
9    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
10    "description": "Demo tenant VPC",
11    "networkVirtualizationType": "FNN"
12    }'

Example Response

1 {
2    "id": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
3    "name": "demo-vpc",
4    "description": "Demo tenant VPC",
5    "org": "tenant-org-name",
6    "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
7    "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
9    "controllerVpcId": null,
10    "networkVirtualizationType": "FNN",
11    "status": "Pending",
12    "statusHistory": [
13       {
14       "status": "Pending",
15       "message": "received vpc creation request, pending pairing",
16       "created": "2023-07-06T16:20:43.335989Z",
17       "updated": "2023-07-06T16:20:43.335989Z"
18       }
19    ],
20    "created": "2023-07-06T16:20:43.335989Z",
21    "updated": "2023-07-06T16:20:43.335989Z"
22 }

(Optional) Confirm the VPC Status

Poll the VPC endpoint to confirm the status changes to Ready:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc/0b1c53a0-a27e-4714-98d7-0cd3bc579db2" \
5 -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"

Example Response

1 {
2    "id": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
3    "name": "demo-vpc",
4    "description": "Demo tenant VPC",
5    "org": "tenant-org-name",
6    "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
7    "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
9    "controllerVpcId": "b1e32ce0-49d4-48c7-bdc9-ecc1623c02f4",
10    "networkVirtualizationType": "FNN",
11    "status": "Ready",
12    "statusHistory": [
13       {
14          "status": "Ready",
15          "message": "VPC successfully provisioned on Site",
16          "created": "2023-07-06T16:20:44.490895Z",
17          "updated": "2023-07-06T16:20:44.490895Z"
18       },
19       {
20          "status": "Provisioning",
21          "message": "initiated VPC provisioning via Site Agent",
22          "created": "2023-07-06T16:20:43.63647Z",
23          "updated": "2023-07-06T16:20:43.63647Z"
24       },
25       {
26          "status": "Pending",
27          "message": "received vpc creation request, pending pairing",
28          "created": "2023-07-06T16:20:43.335989Z",
29          "updated": "2023-07-06T16:20:43.335989Z"
30       }
31    ],
32    "created": "2023-07-06T16:20:43.335989Z",
33    "updated": "2023-07-06T16:20:44.497876Z"
34 }

Add an Instance with a Single Interface

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.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/instance" \
5    -H "Content-Type: application/json" -H "Accept: application/json" \
6    -H "Authorization: Bearer ${TOKEN}" \
7    -d '{
8       "name": "demo-compute-instance-0",
9       "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
10       "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11       "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
12       "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
13       "userData": null,
14       "interfaces": [
15          {
16             "subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08"
17          }
18       ]
19       }'

Example Response

1 {
2    "id": "a4a1895b-d696-4d90-a670-357c2f3485b6",
3    "name": "demo-compute-instance-0",
4    "controllerInstanceId": "",
5    "allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
6    "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
7    "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
8    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
9    "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
10    "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11    "machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
12    "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
13    "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",
14    "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",
15    "serialConsoleUrl": null,
16    "status": "Pending",
17    "interfaces": [
18       {
19          "id": "752bf819-a740-4e19-9f0e-b99ee9162392",
20          "instanceId": "a4a1895b-d696-4d90-a670-357c2f3485b6",
21          "subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
22          "isPhysical": true,
23          "macAddress": null,
24          "ipAddresses": null,
25          "status": "Pending",
26          "created": "2023-07-06T17:04:00.338968Z",
27          "updated": "2023-07-06T17:04:00.338968Z"
28       }
29    ],
30    "statusHistory": [
31       {
32          "status": "Pending",
33          "message": "received instance creation request, pending",
34          "created": "2023-07-06T17:04:00.338968Z",
35          "updated": "2023-07-06T17:04:00.338968Z"
36       }
37    ],
38    "deprecations": [],
39    "created": "2023-07-06T17:04:00.338968Z",
40    "updated": "2023-07-06T17:04:00.338968Z"
41 }

Add an Instance with Multiple Interfaces

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/instance" \
5    -H "Content-Type: application/json" -H "Accept: application/json" \
6    -H "Authorization: Bearer ${TOKEN}" \
7    -d '{
8          "name": "demo-compute-instance-multiple-interfaces",
9          "instanceTypeId": "364dd639-5122-420c-a663-fa56e290e187",
10          "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11          "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
12          "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
13          "userData": null,
14          "interfaces": [
15             {
16                "vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
17                "isPhysical": true,
18                "device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
19                "deviceInstance": 0
20             },
21             {
22                "vpcPrefixId": "8988dbd3-f038-4338-b961-8e5cbf89a77e",
23                "isPhysical": true,
24                "device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
25                "deviceInstance": 1
26             }
27          ]
28          }'

Example Response

1 {
2    "id": "9db49890-d015-464d-95d9-26e6714dbf8a",
3    "name": "demo-compute-instance-1",
4    "controllerInstanceId": "",
5    "allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
6    "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
7    "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
8    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
9    "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
10    "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11    "machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
12    "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
13    "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",
14    "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",
15    "serialConsoleUrl": null,
16    "status": "Pending",
17    "interfaces": [
18          {
19          "id": "277fec57-abbc-43e1-8d81-1ae7b960b22f",
20          "instanceId": "9db49890-d015-464d-95d9-26e6714dbf8a",
21          "vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
22          "device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
23          "deviceInstance": 0,
24          "isPhysical": true,
25          "macAddress": null,
26          "ipAddresses": null,
27          "status": "Pending",
28          "created": "2023-07-06T17:07:36.268362Z",
29          "updated": "2023-07-06T17:07:36.268362Z"
30          },
31          {
32          "id": "62220366-4453-4f25-ae7c-d0109285c06f",
33          "instanceId": "9db49890-d015-464d-95d9-26e6714dbf8a",
34          "vpcPrefixId": "8c7422d7-abf5-41ae-8b6d-9d62442a8b31",
35          "device": "MT43244 BlueField-3 integrated ConnectX-7 network controller",
36          "deviceInstance": 1,
37          "isPhysical": true,
38          "macAddress": null,
39          "ipAddresses": null,
40          "status": "Pending",
41          "created": "2023-07-06T17:07:36.268362Z",
42          "updated": "2023-07-06T17:07:36.268362Z"
43          }
44    ],
45    "statusHistory": [
46       {
47          "status": "Pending",
48          "message": "received instance creation request, pending",
49          "created": "2023-07-06T17:07:36.268362Z",
50          "updated": "2023-07-06T17:07:36.268362Z"
51       }
52    ],
53    "deprecations": [],
54    "created": "2023-07-06T17:07:36.268362Z",
55    "updated": "2023-07-06T17:07:36.268362Z"
56 }

(Optional) Confirm the Instance Status

Poll the Instance to confirm the status changes to Ready:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/instance/a4a1895b-d696-4d90-a670-357c2f3485b6" \
5    -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"

Example Response

1 {
2    "id": "a4a1895b-d696-4d90-a670-357c2f3485b6",
3    "name": "demo-compute-instance-0",
4    "controllerInstanceId": "53ecddf2-fbaf-432f-9231-dc2f6bb8cf28",
5    "allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
6    "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
7    "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
8    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
9    "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
10    "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11    "machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
12    "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
13    "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",
14    "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",
15    "serialConsoleUrl": "ssh://53ecddf2-fbaf-432f-9231-dc2f6bb8cf28@demo-site.example.com",
16    "status": "Ready",
17    "interfaces": [
18       {
19          "id": "752bf819-a740-4e19-9f0e-b99ee9162392",
20          "instanceId": "a4a1895b-d696-4d90-a670-357c2f3485b6",
21          "subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
22          "isPhysical": true,
23          "macAddress": null,
24          "ipAddresses": [
25          "192.166.128.2"
26          ],
27          "status": "Ready",
28          "created": "2023-07-06T17:04:00.338968Z",
29          "updated": "2023-07-06T17:07:23.628998Z"
30       }
31    ],
32    "statusHistory": [
33       {
34          "status": "BootCompleted",
35          "message": "Instance is ready for use",
36          "created": "2023-07-06T17:07:23.618478Z",
37          "updated": "2023-07-06T17:07:23.618478Z"
38       },
39       {
40          "status": "Provisioning",
41          "message": "Instance provisioning was successfully initiated on Site",
42          "created": "2023-07-06T17:04:03.277049Z",
43          "updated": "2023-07-06T17:04:03.277049Z"
44       },
45       {
46          "status": "Provisioning",
47          "message": "Provisioning request was sent to the Site",
48          "created": "2023-07-06T17:04:02.269136Z",
49          "updated": "2023-07-06T17:04:02.269136Z"
50       },
51       {
52          "status": "Pending",
53          "message": "received instance creation request, pending",
54          "created": "2023-07-06T17:04:00.338968Z",
55          "updated": "2023-07-06T17:04:00.338968Z"
56       }
57    ],
58    "deprecations": [],
59    "created": "2023-07-06T17:04:00.338968Z",
60    "updated": "2023-07-06T17:07:23.608281Z"
61 }

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=<provider-id> and siteId=<site-id> parameters.

Allocate Compute Instances

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/allocation" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "name": "demo-compute-allocation",
9         "description": "Demo compute instance allocation",
10         "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
11         "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
12         "allocationConstraints": [
13           {
14             "resourceType": "InstanceType",
15             "resourceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
16             "constraintType": "Reserved",
17             "constraintValue": 2
18           }
19         ]
20       }'

Example Response

1 {
2   "id": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
3   "name": "demo-compute-allocation",
4   "description": "Demo compute instance allocation",
5   "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
6   "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
7   "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
8   "status": "Registered",
9   "statusHistory": [
10     {
11       "status": "Registered",
12       "message": "received allocation creation request, registered",
13       "created": "2023-07-06T16:18:59.35228Z",
14       "updated": "2023-07-06T16:18:59.35228Z"
15     }
16   ],
17   "created": "2023-07-06T16:18:59.35228Z",
18   "updated": "2023-07-06T16:18:59.35228Z",
19   "allocationConstraints": [
20     {
21       "id": "13eab768-4e65-4582-84de-d524be8a7830",
22       "allocationId": "9b06c02f-f46d-4dfc-9033-71f42e72cc7d",
23       "resourceType": "InstanceType",
24       "ResourceTypeID": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
25       "constraintType": "Reserved",
26       "constraintValue": 2,
27       "derivedResourceId": null,
28       "created": "2023-07-06T16:18:59.35228Z",
29       "updated": "2023-07-06T16:18:59.35228Z"
30     }
31   ]
32 }

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=<site-id> parameter.

Get Machines Without an Instance Type

Get the machines that do not have an instance type assigned and that report a status of Ready:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{provider-org-name}/nico/machine?siteId=157627d6-d742-440b-ac04-77a618d94459&hasInstanceType=false&status=Ready" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}"

Example Response

1 [
2    {
3       "id": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
4       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
5       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6       "instanceTypeId": null,
7       "controllerMachineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
8       "controllerMachineType": "PowerEdge R750",
9       "hostname": "sad-uniform",
10       "machineCapabilities": [
11          {
12          "type": "CPU",
13          "name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
14          "cores": 18,
15          "threads": 36,
16          "count": 2
17          },
18          {
19          "type": "Storage",
20          "name": "Dell Ent NVMe CM6 RI 1.92TB",
21          "count": 3
22          },
23          {
24          "type": "Network",
25          "name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
26          "count": 2
27          },
28          {
29          "type": "Network",
30          "name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
31          "count": 2
32          },
33          {
34          "type": "Network",
35          "name": "BCM57414 NetXtreme-E 10Gb/25Gb RDMA Ethernet Controller",
36          "count": 2
37          }
38       ],
39       "machineInterfaces": [
40          {
41          "id": "6dd628a3-cc5b-4b12-8a5b-acad0160c7c3",
42          "machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
43          "controllerInterfaceId": "029a9fdf-c232-4e8d-9327-4c271ad7ea01",
44          "controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
45          "subnetId": null,
46          "hostname": "sad-uniform",
47          "isPrimary": true,
48          "macAddress": "B8:3F:D2:90:97:04",
49          "ipAddresses": [
50             "10.180.90.10/32"
51          ],
52          "created": "2023-05-04T14:22:17.121178Z",
53          "updated": "2023-07-06T16:16:22.777176Z"
54          }
55       ],
56       "status": "Ready",
57       "statusHistory": [],
58       "created": "2023-04-13T19:37:17.954195Z",
59       "updated": "2023-07-06T16:16:22.75737Z"
60    },
61    {
62       "id": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
63       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
64       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
65       "instanceTypeId": null,
66       "controllerMachineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
67       "controllerMachineType": "PowerEdge R750",
68       "hostname": "social-whiskey",
69       "machineCapabilities": [
70          {
71          "type": "Network",
72          "name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
73          "count": 2
74          },
75          {
76          "type": "Network",
77          "name": "NetXtreme BCM5720 2-port Gigabit Ethernet PCIe (PowerEdge Rx5xx LOM Board)",
78          "count": 2
79          },
80          {
81          "type": "Storage",
82          "name": "Dell Ent NVMe v2 AGN RI U.2 1.92TB",
83          "count": 2
84          },
85          {
86          "type": "CPU",
87          "name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
88          "cores": 18,
89          "threads": 36,
90          "count": 2
91          }
92       ],
93       "machineInterfaces": [
94          {
95          "id": "41847749-03af-4c8c-94b6-6722e32a603e",
96          "machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
97          "controllerInterfaceId": "8b7ea73b-76d1-46be-8194-4c183c816a8f",
98          "controllerSegmentId": "82e53d43-72ee-468f-bf19-bdebf3877d62",
99          "subnetId": null,
100          "hostname": "social-whiskey",
101          "isPrimary": true,
102          "macAddress": "B8:3F:D2:90:99:B4",
103          "ipAddresses": [
104             "10.180.90.15/32"
105          ],
106          "created": "2023-05-04T14:58:20.087651Z",
107          "updated": "2023-07-06T16:16:22.861989Z"
108          }
109       ],
110       "status": "Ready",
111       "statusHistory": [],
112       "created": "2023-04-25T14:19:20.895831Z",
113       "updated": "2023-07-06T16:16:22.82906Z"
114    }
115 ]

Associate Machines with an Instance Type

You can specify one or more machine IDs in the machineIds parameter.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/instance/type/9c4aaa6a-3934-4274-b0a9-5143b253039e/machine" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8       "machineIds": [
9          "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
10          "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g"
11       ]
12       }'

Example Response

1 [
2    {
3       "id": "5e782d7f-78f6-47bf-a540-13b7e56897e7",
4       "machineId": "fm100hthvos96dbmmai84gsok0dn967v9fap8ublgp34kaknd9tq7pddim0",
5       "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
6       "created": "2023-07-06T16:18:26.611048Z",
7       "updated": "2023-07-06T16:18:26.611048Z"
8    },
9    {
10       "id": "335fc255-fd3b-4602-bd2e-86b5b444a178",
11       "machineId": "fm100httuapjc6t4o629o5d3uu5616gimvn0smunp199mmmp1f2134nt92g",
12       "instanceTypeId": "9c4aaa6a-3934-4274-b0a9-5143b253039e",
13       "created": "2023-07-06T16:18:26.611048Z",
14       "updated": "2023-07-06T16:18:26.611048Z"
15    }
16 ]

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.

Add an Operating System Image

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/operating-system" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "name": "demo-ipxe-os",
9         "description": "Demo tenant operating system",
10         "tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
11         "allowOverride": true,
12         "isCloudInit": true,
13         "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",
14         "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"
15       }'

Example Response

1 {
2   "id": "44d246f3-3075-4daa-9887-0d376bf9dec5",
3   "name": "demo-ipxe-os",
4   "description": "Demo tenant operating system",
5   "infrastructureProviderId": null,
6   "tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
7   "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",
8   "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",
9   "isCloudInit": true,
10   "allowOverride": true,
11   "status": "Ready",
12   "statusHistory": [
13     {
14       "status": "Ready",
15       "message": "Operating System is ready for use",
16       "created": "2023-09-06T18:39:37.607905Z",
17       "updated": "2023-09-06T18:39:37.607905Z"
18     }
19   ],
20   "created": "2023-09-06T18:39:37.607905Z",
21   "updated": "2023-09-06T18:39:37.607905Z"
22 }

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 a Subnet

Add one or more subnets. The following command sample shows how to add one subnet.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/subnet" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8         "name": "demo-ipv4-subnet",
9         "description": "Demo IPv4 Tenant Subnet",
10         "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11         "ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
12         "prefixLength": 28
13     }'

Example Response

1 {
2     "id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
3     "name": "demo-ipv4-subnet",
4     "description": "Demo IPv4 Tenant Subnet",
5     "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6     "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
7     "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8     "controllerNetworkSegmentId": null,
9     "ipv4Prefix": "192.166.128.0",
10     "ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
11     "ipv4Gateway": "192.166.128.1",
12     "ipv6Prefix": null,
13     "ipv6BlockId": null,
14     "ipv6Gateway": null,
15     "mtu": 9000,
16     "prefixLength": 28,
17     "routingType": "Public",
18     "status": "Pending",
19     "statusHistory": [
20         {
21         "status": "Pending",
22         "message": "received subnet creation request, pending",
23         "created": "2023-07-06T16:21:34.916407Z",
24         "updated": "2023-07-06T16:21:34.916407Z"
25         }
26     ],
27     "deprecations": [],
28     "created": "2023-07-06T16:21:34.916407Z",
29     "updated": "2023-07-06T16:21:34.916407Z"
30 }

(Optional) Confirm the Subnet Status

Poll the subnet endpoint to confirm that the status changes to Ready:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl GET "https://api.example.com/v2/org/{tenant-org-name}/nico/subnet/5e1f6c51-a532-437b-b7a5-7dfac214de08" \
5 -H "Accept: application/json" -H "Authorization: Bearer ${TOKEN}"

Example Response

1 {
2     "id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
3     "name": "demo-ipv4-subnet",
4     "description": "Demo IPv4 Tenant Subnet",
5     "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6     "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
7     "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8     "controllerNetworkSegmentId": "f5634c31-4cd4-453b-8ac5-e81f2a19ab05",
9     "ipv4Prefix": "192.166.128.0",
10     "ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
11     "ipv4Gateway": "192.166.128.1",
12     "ipv6Prefix": null,
13     "ipv6BlockId": null,
14     "ipv6Gateway": null,
15     "mtu": 9000,
16     "prefixLength": 28,
17     "status": "Ready",
18     "statusHistory": [
19         {
20         "status": "Ready",
21         "message": "Subnet is ready for use",
22         "created": "2023-07-06T16:25:20.717794Z",
23         "updated": "2023-07-06T16:25:20.717794Z"
24         },
25         {
26         "status": "Provisioning",
27         "message": "Subnet provisioning was successfully initiated on Site",
28         "created": "2023-07-06T16:21:36.830555Z",
29         "updated": "2023-07-06T16:21:36.830555Z"
30         },
31         {
32         "status": "Provisioning",
33         "message": "Provisioning request was sent to the Site",
34         "created": "2023-07-06T16:21:35.538119Z",
35         "updated": "2023-07-06T16:21:35.538119Z"
36         },
37         {
38         "status": "Pending",
39         "message": "received subnet creation request, pending",
40         "created": "2023-07-06T16:21:34.916407Z",
41         "updated": "2023-07-06T16:21:34.916407Z"
42         }
43     ],
44     "deprecations": [],
45     "created": "2023-07-06T16:21:34.916407Z",
46     "updated": "2023-07-06T16:25:20.70757Z"
47 }

Add a VPC Prefix

The following command sample shows how to add one VPC prefix. You can also add multiple VPC prefixes at once.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/vpc-prefix" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "name": "demo-ipv4-vpc-prefix",
9         "description": "Demo IPv4 Tenant VPC Prefix",
10         "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
11         "ipBlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
12         "prefixLength": 28
13       }'

Example Response

1 {
2   "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
3   "name": "demo-ipv4-vpc-prefix",
4   "description": "Demo IPv4 Tenant VPC Prefix",
5   "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6   "vpcId": "0b1c53a0-a27e-4714-98d7-0cd3bc579db2",
7   "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8   "ipBlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
9   "prefix": "10.217.98.208/28",
10   "prefixLength": 28,
11   "status": "Ready",
12   "statusHistory": [
13     {
14       "status": "Ready",
15       "message": "Received VPC prefix creation request, ready",
16       "created": "2023-07-06T16:25:20.717794Z",
17       "updated": "2023-07-06T16:25:20.717794Z"
18     }
19   ],
20   "created": "2023-07-06T16:21:34.916407Z",
21   "updated": "2023-07-06T16:25:20.70757Z"
22 }

Managing IP Blocks

Add an IP Block

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/ipblock" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "name": "demo-ipv4-block",
9         "description": "Demo IPv4 block",
10         "prefixLength": 24,
11         "prefix": "192.166.128.0",
12         "protocolVersion": "IPv4",
13         "routingType": "DatacenterOnly",
14         "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8"
15       }'

Example Response

1 {
2   "id": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
3   "name": "demo-ipv4-block",
4   "description": "Demo IPv4 block",
5   "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
6   "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
7   "tenantId": null,
8   "routingType": "DatacenterOnly",
9   "prefix": "192.166.128.0",
10   "prefixLength": 24,
11   "protocolVersion": "IPv4",
12   "status": "Ready",
13   "statusHistory": [
14     {
15       "status": "Ready",
16       "message": "IP Block is ready for use",
17       "created": "2023-07-06T16:17:46.911267Z",
18       "updated": "2023-07-06T16:17:46.911267Z"
19     }
20   ],
21   "deprecations": [],
22   "created": "2023-07-06T16:17:46.911267Z",
23   "updated": "2023-07-06T16:17:46.911267Z"
24 }

Allocate an IP Block

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{provider-org-name}/nico/allocation" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "name": "demo-ipv4-allocation",
9         "description": "Demo IPv4 allocation",
10         "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
11         "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
12         "allocationConstraints": [
13           {
14             "resourceType": "IPBlock",
15             "resourceTypeId": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
16             "constraintType": "Reserved",
17             "constraintValue": 24
18           }
19         ]
20       }'

Example Response

1 {
2   "id": "98c356e0-0c96-45ef-a65d-319338190955",
3   "name": "demo-ipv4-allocation",
4   "description": "Demo IPv4 allocation",
5   "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
6   "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
7   "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
8   "status": "Registered",
9   "statusHistory": [
10     {
11       "status": "Registered",
12       "message": "received allocation creation request, registered",
13       "created": "2023-07-06T16:18:02.513471Z",
14       "updated": "2023-07-06T16:18:02.513471Z"
15     }
16   ],
17   "created": "2023-07-06T16:18:02.513471Z",
18   "updated": "2023-07-06T16:18:02.513471Z",
19   "allocationConstraints": [
20     {
21       "id": "5eef34d5-8644-4a5c-9604-a4a72b42118e",
22       "allocationId": "98c356e0-0c96-45ef-a65d-319338190955",
23       "resourceType": "IPBlock",
24       "ResourceTypeID": "ff920227-e2a1-43aa-99bd-7e39653e4f9f",
25       "constraintType": "Reserved",
26       "constraintValue": 24,
27       "derivedResourceId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
28       "created": "2023-07-06T16:18:02.513471Z",
29       "updated": "2023-07-06T16:18:02.513471Z"
30     }
31   ]
32 }

Managing Network Security Groups

Retrieve All Network Security Groups

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{org}/nico/network-security-group" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}"

Example Response

1 [
2   {
3     "id": "string",
4     "name": "string",
5     "description": "string",
6     "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
7     "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
8     "status": "Pending",
9     "statusHistory": [
10       {
11         "status": "Pending",
12         "message": "Request received, pending processing",
13         "created": "2019-08-24T14:15:22Z",
14         "updated": "2019-08-24T14:15:22Z"
15       }
16     ],
17     "rules": [
18       {
19         "name": "string",
20         "direction": "INGRESS",
21         "sourcePortRange": "80-81",
22         "destinationPortRange": "80-81",
23         "protocol": "TCP",
24         "action": "PERMIT",
25         "priority": 0,
26         "sourcePrefix": "10.5.44.0/24",
27         "destinationPrefix": "10.5.44.0/24"
28       }
29     ],
30     "labels": {},
31     "created": "2019-08-24T14:15:22Z",
32     "updated": "2019-08-24T14:15:22Z"
33   }
34 ]

Create a Network Security Group that Limits Traffic

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{org}/nico/network-security-group" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8     "name": "string",
9     "description": "string",
10     "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
11     "rules": [
12         {
13           "name": "string",
14           "direction": "INGRESS",
15           "sourcePortRange": "80-81",
16           "destinationPortRange": "80-81",
17           "protocol": "TCP",
18           "action": "PERMIT",
19           "priority": 0,
20           "sourcePrefix": "10.5.44.0/24",
21           "destinationPrefix": "10.5.44.0/24"
22         }
23       ],
24     "labels": {}
25   }'

Example Response

1 {
2   "id": "string",
3   "name": "string",
4   "description": "string",
5   "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
6   "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
7   "status": "Pending",
8   "statusHistory": [
9     {
10       "status": "Pending",
11       "message": "Request received, pending processing",
12       "created": "2019-08-24T14:15:22Z",
13       "updated": "2019-08-24T14:15:22Z"
14     }
15   ],
16   "rules": [
17     {
18       "name": "string",
19       "direction": "INGRESS",
20       "sourcePortRange": "80-81",
21       "destinationPortRange": "80-81",
22       "protocol": "TCP",
23       "action": "PERMIT",
24       "priority": 0,
25       "sourcePrefix": "10.5.44.0/24",
26       "destinationPrefix": "10.5.44.0/24"
27     }
28   ],
29   "labels": {},
30   "created": "2019-08-24T14:15:22Z",
31   "updated": "2019-08-24T14:15:22Z"
32 }

Create a Network Security Group that Permits All Traffic

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{org}/nico/network-security-group" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8     "name": "string",
9     "description": "string",
10     "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
11     "rules": [
12       {
13         "name": "allow-all-ingress",
14         "direction": "INGRESS",
15         "sourcePortRange": "0-65535",
16         "destinationPortRange": "0-65535",
17         "protocol": "ANY",
18         "action": "PERMIT",
19         "priority": 0,
20         "sourcePrefix": "0.0.0.0/0",
21         "destinationPrefix": "0.0.0.0/0"
22       },
23       {
24         "name": "allow-all-egress",
25         "direction": "EGRESS",
26         "sourcePortRange": "0-65535",
27         "destinationPortRange": "0-65535",
28         "protocol": "ANY",
29         "action": "PERMIT",
30         "priority": 0,
31         "sourcePrefix": "0.0.0.0/0",
32         "destinationPrefix": "0.0.0.0/0"
33       }
34     ],
35     "labels": {
36       "property1": "default",
37       "property2": "global-allow"
38     }
39     }'

Example Response

1 [
2   {
3     "id": "ea9c9eac-0e3d-4c85-b0e0-1e174b214c8f",
4     "name": "allow-all",
5     "description": "Allow all L4 traffic in all directions",
6     "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
7     "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
8     "status": "Pending",
9     "statusHistory": [
10       {
11         "status": "Pending",
12         "message": "Request received, pending processing",
13         "created": "2025-05-22T12:00:00Z",
14         "updated": "2025-05-22T12:00:00Z"
15       }
16     ],
17     "rules": [
18       {
19         "name": "allow-all-ingress",
20         "direction": "INGRESS",
21         "sourcePortRange": null,
22         "destinationPortRange": null,
23         "protocol": "ANY",
24         "action": "PERMIT",
25         "priority": 0,
26         "sourcePrefix": "0.0.0.0/0",
27         "destinationPrefix": "0.0.0.0/0"
28       },
29       {
30         "name": "allow-all-egress",
31         "direction": "EGRESS",
32         "sourcePortRange": null,
33         "destinationPortRange": null,
34         "protocol": "ANY",
35         "action": "PERMIT",
36         "priority": 0,
37         "sourcePrefix": "0.0.0.0/0",
38         "destinationPrefix": "0.0.0.0/0"
39       }
40     ],
41     "labels": {
42       "property1": "default",
43       "property2": "global-allow"
44     },
45     "created": "2025-05-22T12:00:00Z",
46     "updated": "2025-05-22T12:00:00Z"
47   }
48 ]

Modify the Rules for a Network Security Group

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X PATCH "https://api.example.com/v2/org/{org}/nico/network-security-group/{nsgId}" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8     "rules": [
9       {
10         "name": "allow-all-ingress",
11         "direction": "INGRESS",
12         "sourcePortRange": "0-65535",
13         "destinationPortRange": "0-65535",
14         "protocol": "ANY",
15         "action": "PERMIT",
16         "priority": 0,
17         "sourcePrefix": "192.168.1.0/24",
18         "destinationPrefix": "0.0.0.0/0"
19       }
20     ]
21   }'

Example Response

1 {
2   "id": "string",
3   "name": "string",
4   "description": "string",
5   "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
6   "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
7   "status": "Pending",
8   "statusHistory": [
9     {
10       "status": "Pending",
11       "message": "Request received, pending processing",
12       "created": "2019-08-24T14:15:22Z",
13       "updated": "2019-08-24T14:15:22Z"
14     }
15   ],
16   "rules": [
17     {
18       "name": "allow-all-ingress",
19       "direction": "INGRESS",
20       "sourcePortRange": "0-65535",
21       "destinationPortRange": "0-65535",
22       "protocol": "ANY",
23       "action": "PERMIT",
24       "priority": 0,
25       "sourcePrefix": "192.168.1.0/24",
26       "destinationPrefix": "0.0.0.0/0"
27     },
28     {
29       "name": "allow-all-egress",
30       "direction": "EGRESS",
31       "sourcePortRange": "0-65535",
32       "destinationPortRange": "0-65535",
33       "protocol": "ANY",
34       "action": "PERMIT",
35       "priority": 0,
36       "sourcePrefix": "0.0.0.0/0",
37       "destinationPrefix": "0.0.0.0/0"
38     }
39   ],
40   "labels": {
41     "property1": "default",
42     "property2": "global-allow"
43   },
44   "created": "2019-08-24T14:15:22Z",
45   "updated": "2019-08-24T14:15:22Z"
46 }

Accessing the Serial Console

Enable the Serial Console on a Compute Instance

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X PATCH "https://api.example.com/v2/org/{provider-org-name}/nico/site/2ae25bd4-7b07-4b39-9514-031e5c335f4f" \
5   -H "Content-Type: application/json" -H "Accept: application/json" \
6   -H "Authorization: Bearer ${TOKEN}" \
7   -d '{
8         "isSerialConsoleEnabled": true,
9         "serialConsoleHostname": "10.217.126.53",
10         "serialConsoleIdleTimeout": 7200,
11         "serialConsoleMaxSessionLength": 86400
12       }'

Example Response

1 {
2   "id": "2ae25bd4-7b07-4b39-9514-031e5c335f4f",
3   "name": "demo-site-a",
4   "description": "Demo Site A",
5   "org": "provider-org-name",
6   "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
7   "siteControllerVersion": null,
8   "siteAgentVersion": null,
9   "registrationToken": null,
10   "registrationTokenExpiration": "2023-11-01T01:47:36.000397Z",
11   "serialConsoleHostname": "192.168.126.53",
12   "isSerialConsoleEnabled": true,
13   "serialConsoleIdleTimeout": 7200,
14   "serialConsoleMaxSessionLength": 86400,
15   "isOnline": true,
16   "deprecations": [],
17   "status": "Registered",
18   "statusHistory": [
19     {
20       "status": "Registered",
21       "message": "Site has been successfully paired",
22       "created": "2023-10-31T01:49:19.604387Z",
23       "updated": "2023-10-31T01:49:19.604387Z"
24     }
25   ],
26   "created": "2023-06-07T00:56:04.261575Z",
27   "updated": "2023-11-01T15:02:01.914645Z"
28 }

Add an SSH Key Group

The SSH key should be in RSA, ECDSA, or ED25519 format. Add the SSH Key Group:

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8       "name": "demo-team-0-group",
9       "description": "Demo team group"
10    }'

Note the value of the version field — you will need it to update the SSH Key Group.

Example Response

1 {
2    "id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
3    "name": "demo-team-0-group",
4    "description": "Demo team group",
5    "org": "tenant-org-name",
6    "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
7    "version": "6a5ccd83b5daf693bd14ab32a439d3181635be6f",
8    "status": "Synced",
9    "statusHistory": [
10       {
11          "status": "Syncing",
12          "message": "received SSH Key Group creation request, syncing",
13          "created": "2023-11-01T12:37:22.649619Z",
14          "updated": "2023-11-01T12:37:22.649619Z"
15       },
16       {
17          "status": "Synced",
18          "message": "SSH Key Group has successfully been synced to all Sites",
19          "created": "2023-11-01T12:37:22.649619Z",
20          "updated": "2023-11-01T12:37:22.649619Z"
21       }
22    ],
23    "sshKeys": [],
24    "siteAssociations": [],
25    "created": "2023-11-01T12:37:22.649619Z",
26    "updated": "2023-11-01T12:37:22.693571Z"
27 }

Add a Public SSH Key

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X POST "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkey" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8       "name": "customer-0",
9       "description": "Demo public SSH key",
10       "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAcV/3oxRllEji0wl9F6icRk+Kme0H2MMAPFizKB5yv8 demo-user@nvdia.com"
11       }'

Example Response

1 {
2    "id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
3    "name": "customer-0",
4    "org": "tenant-org-name",
5    "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
6    "fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
7    "created": "2023-11-01T12:37:30.554055Z",
8    "updated": "2023-11-01T12:37:30.554055Z"
9 }

Add the Public SSH Key to the Key Group

Specify the new and existing key IDs to keep in the sshKeyIds field.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X PATCH "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup/9ffb8f90-f88f-4420-952d-e911f446d7eb" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8       "version": "6a5ccd83b5daf693bd14ab32a439d3181635be6f",
9       "sshKeyIds": [
10         "b658db7e-f06c-4140-9494-48ea1f3f7769"
11       ]
12     }'

Example Response

1 {
2    "id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
3    "name": "demo-team-0-group",
4    "description": "Demo team group",
5    "org": "tenant-org-name",
6    "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
7    "version": "23220d11a579258cb810942060e910fb3fac9762",
8    "status": "Syncing",
9    "statusHistory": [
10       {
11          "status": "Syncing",
12          "message": "received SSH Key Group update request, syncing",
13          "created": "2023-11-01T12:37:44.969029Z",
14          "updated": "2023-11-01T12:37:44.969029Z"
15       },
16       {
17          "status": "Syncing",
18          "message": "received SSH Key Group creation request, syncing",
19          "created": "2023-11-01T12:37:22.649619Z",
20          "updated": "2023-11-01T12:37:22.649619Z"
21       },
22       {
23          "status": "Synced",
24          "message": "SSH Key Group has successfully been synced to all Sites",
25          "created": "2023-11-01T12:37:22.649619Z",
26          "updated": "2023-11-01T12:37:22.649619Z"
27       }
28    ],
29    "sshKeys": [
30       {
31          "id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
32          "name": "customer-0",
33          "org": "tenant-org-name",
34          "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
35          "fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
36          "created": "2023-11-01T12:37:30.554055Z",
37          "updated": "2023-11-01T12:37:30.554055Z"
38       }
39    ],
40    "siteAssociations": [],
41    "created": "2023-11-01T12:37:22.649619Z",
42    "updated": "2023-11-01T12:37:45.007738Z"
43 }

Add Sites to the Key Group

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.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X PATCH "https://api.example.com/v2/org/{tenant-org-name}/nico/sshkeygroup/9ffb8f90-f88f-4420-952d-e911f446d7eb" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}" \
7 -d '{
8       "version": "23220d11a579258cb810942060e910fb3fac9762",
9       "siteIds": [
10          "157627d6-d742-440b-ac04-77a618d94459"
11       ]
12       }'

Example Response

1 {
2    "id": "9ffb8f90-f88f-4420-952d-e911f446d7eb",
3    "name": "demo-team-0-group",
4    "description": "Demo team group",
5    "org": "tenant-org-name",
6    "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
7    "version": "7fa801416ce27ec68d9dd531eb6948a9a5f4ed87",
8    "status": "Syncing",
9    "statusHistory": [
10       {
11          "status": "Syncing",
12          "message": "received SSH Key Group update request, syncing",
13          "created": "2023-11-01T12:38:04.208273Z",
14          "updated": "2023-11-01T12:38:04.208273Z"
15       },
16       {
17          "status": "Syncing",
18          "message": "received SSH Key Group update request, syncing",
19          "created": "2023-11-01T12:37:44.969029Z",
20          "updated": "2023-11-01T12:37:44.969029Z"
21       },
22       {
23          "status": "Syncing",
24          "message": "received SSH Key Group creation request, syncing",
25          "created": "2023-11-01T12:37:22.649619Z",
26          "updated": "2023-11-01T12:37:22.649619Z"
27       },
28       {
29          "status": "Synced",
30          "message": "SSH Key Group has successfully been synced to all Sites",
31          "created": "2023-11-01T12:37:22.649619Z",
32          "updated": "2023-11-01T12:37:22.649619Z"
33       }
34    ],
35    "sshKeys": [
36       {
37          "id": "b658db7e-f06c-4140-9494-48ea1f3f7769",
38          "name": "customer-0",
39          "org": "tenant-org-name",
40          "tenantId": "778086ad-35b8-46ff-a796-69b2e4c93975",
41          "fingerprint": "LfniSSO1iwx1nbAXyP6swmwmkrW3GnW1j9v+t/Ou9Vw",
42          "created": "2023-11-01T12:37:30.554055Z",
43          "updated": "2023-11-01T12:37:30.554055Z"
44       }
45    ],
46    "siteAssociations": [
47       {
48          "site": {
49          "id": "157627d6-d742-440b-ac04-77a618d94459",
50          "name": "demo-site-a",
51          "description": "Demo Site",
52          "org": "provider-org-name",
53          "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
54          "siteControllerVersion": null,
55          "siteAgentVersion": null,
56          "registrationToken": null,
57          "registrationTokenExpiration": null,
58          "serialConsoleHostname": "192.168.126.6",
59          "isSerialConsoleEnabled": true,
60          "serialConsoleIdleTimeout": 300,
61          "serialConsoleMaxSessionLength": 86400,
62          "isSerialConsoleSSHKeysEnabled": false,
63          "isOnline": true,
64          "deprecations": [],
65          "status": "Registered",
66          "statusHistory": [],
67          "created": "2023-04-21T17:30:08.425798Z",
68          "updated": "2023-11-01T12:37:53.579769Z"
69          },
70          "version": "3af0d2e8136292010bb23afeb8de1c009e343cb2",
71          "status": "Syncing",
72          "created": "2023-11-01T12:38:04.208273Z",
73          "updated": "2023-11-01T12:38:04.256966Z"
74       }
75    ],
76    "created": "2023-11-01T12:37:22.649619Z",
77    "updated": "2023-11-01T12:38:04.251866Z"
78 }

View Instances That Belong to the VPC

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 curl -X GET "https://api.example.com/v2/org/{tenant-org-name}/nico/instance?vpcId=f466a2d5-5820-4824-a845-3218fdff801b" \
5 -H "Content-Type: application/json" -H "Accept: application/json" \
6 -H "Authorization: Bearer ${TOKEN}"

Example Response

1 [
2    {
3       "id": "83ad26bc-4687-4427-b01c-0857599d1b17",
4       "name": "demo-compute-instance-1",
5       "controllerInstanceId": "c0da5caa-76d6-4a5a-abf7-992b75fec7ae",
6       "allocationId": "c4d1b674-d061-4e95-946e-667149a88113",
7       "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
8       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
9       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
10       "instanceTypeId": "7aa0864b-71b2-4253-af7d-d957e288ff57",
11       "vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
12       "machineId": "2ff5f788-7430-424a-86f8-87d371256496",
13       "operatingSystemId": "7471cecd-88f6-40f0-b1a2-d53f29573bf3",
14       "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",
15       "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",
16       "serialConsoleUrl": "ssh://c0da5caa-76d6-4a5a-abf7-992b75fec7ae@reno.nico.nvidia.com",
17       "status": "Ready",
18       "instanceSubnets": [
19          {
20          "id": "09142b2f-85c3-4e09-aeb2-34e7db19a36d",
21          "instanceId": "83ad26bc-4687-4427-b01c-0857599d1b17",
22          "subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
23          "isPhysical": true,
24          "macAddress": null,
25          "ipAddresses": [
26             "192.166.128.3"
27          ],
28          "status": "Ready",
29          "created": "2023-04-26T19:37:32.445684Z",
30          "updated": "2023-04-26T19:40:18.427811Z"
31          }
32       ],
33       "interfaces": [
34          {
35          "id": "09142b2f-85c3-4e09-aeb2-34e7db19a36d",
36          "instanceId": "83ad26bc-4687-4427-b01c-0857599d1b17",
37          "subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
38          "isPhysical": true,
39          "macAddress": null,
40          "ipAddresses": [
41             "192.166.128.3"
42          ],
43          "status": "Ready",
44          "created": "2023-04-26T19:37:32.445684Z",
45          "updated": "2023-04-26T19:40:18.427811Z"
46          }
47       ],
48       "statusHistory": [
49          {
50          "status": "BootCompleted",
51          "message": "Instance is ready for use",
52          "created": "2023-04-26T19:40:18.418073Z",
53          "updated": "2023-04-26T19:40:18.418073Z"
54          },
55          {
56          "status": "Provisioning",
57          "message": "Instance provisioning was successfully initiated on Site",
58          "created": "2023-04-26T19:37:34.405577Z",
59          "updated": "2023-04-26T19:37:34.405577Z"
60          },
61          {
62          "status": "Provisioning",
63          "message": "Provisioning request was sent to the Site",
64          "created": "2023-04-26T19:37:33.599048Z",
65          "updated": "2023-04-26T19:37:33.599048Z"
66          },
67          {
68          "status": "Pending",
69          "message": "received instance creation request, pending",
70          "created": "2023-04-26T19:37:32.445684Z",
71          "updated": "2023-04-26T19:37:32.445684Z"
72          }
73       ],
74       "created": "2023-04-26T19:37:32.445684Z",
75       "updated": "2023-04-26T19:40:18.40905Z"
76    },
77    {
78       "id": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
79       "name": "demo-compute-instance-0",
80       "controllerInstanceId": "16708e55-012c-46b6-a1c6-815d45ba45bc",
81       "allocationId": "c4d1b674-d061-4e95-946e-667149a88113",
82       "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
83       "infrastructureProviderId": "16060041-f146-43fe-8c82-be48460b5583",
84       "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
85       "instanceTypeId": "7aa0864b-71b2-4253-af7d-d957e288ff57",
86       "vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
87       "machineId": "e6e1b8b2-5ae5-4093-997e-eecb8baf528a",
88       "operatingSystemId": "7471cecd-88f6-40f0-b1a2-d53f29573bf3",
89       "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",
90       "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",
91       "serialConsoleUrl": "ssh://16708e55-012c-46b6-a1c6-815d45ba45bc@reno.nico.nvidia.com",
92       "status": "Ready",
93       "instanceSubnets": [
94          {
95          "id": "10758364-57f9-4429-84a2-5dede1b5045f",
96          "instanceId": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
97          "subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
98          "isPhysical": true,
99          "macAddress": null,
100          "ipAddresses": [
101             "192.166.128.2"
102          ],
103          "status": "Ready",
104          "created": "2023-04-26T19:34:40.96039Z",
105          "updated": "2023-04-26T19:40:18.372682Z"
106          }
107       ],
108       "interfaces": [
109          {
110          "id": "10758364-57f9-4429-84a2-5dede1b5045f",
111          "instanceId": "01e9969c-9a84-4c2d-82fb-973dff30cfc1",
112          "subnetId": "548e925c-fb5f-449f-9ec1-2dc3d89c8e9d",
113          "isPhysical": true,
114          "macAddress": null,
115          "ipAddresses": [
116             "192.166.128.2"
117          ],
118          "status": "Ready",
119          "created": "2023-04-26T19:34:40.96039Z",
120          "updated": "2023-04-26T19:40:18.372682Z"
121          }
122       ],
123       "statusHistory": [
124          {
125          "status": "BootCompleted",
126          "message": "Instance is ready for use",
127          "created": "2023-04-26T19:37:18.21838Z",
128          "updated": "2023-04-26T19:37:18.21838Z"
129          },
130          {
131          "status": "Provisioning",
132          "message": "Instance provisioning was successfully initiated on Site",
133          "created": "2023-04-26T19:34:43.651979Z",
134          "updated": "2023-04-26T19:34:43.651979Z"
135          },
136          {
137          "status": "Provisioning",
138          "message": "Provisioning request was sent to the Site",
139          "created": "2023-04-26T19:34:42.278639Z",
140          "updated": "2023-04-26T19:34:42.278639Z"
141          },
142          {
143          "status": "Pending",
144          "message": "received instance creation request, pending",
145          "created": "2023-04-26T19:34:40.96039Z",
146          "updated": "2023-04-26T19:34:40.96039Z"
147          }
148       ],
149       "created": "2023-04-26T19:34:40.96039Z",
150       "updated": "2023-04-26T19:37:18.191004Z"
151    }
152 ]

Parse IP Addresses from the Response

Use a command like the following to retrieve the IP Addresses from the response, then access the host or application deployed on the Instance.

Example Call

1 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 jq '[ .[] | {name: .name, ipAddresses: .instanceSubnets[].ipAddresses } ]'

Example Response

1 [
2 {
3    "name": "demo-compute-instance-1",
4    "ipAddresses": [
5       "192.166.128.3"
6    ]
7 },
8 {
9    "name": "demo-compute-instance-0",
10    "ipAddresses": [
11       "192.166.128.2"
12    ]
13 }
14 ]