Example API Workflows

View as Markdown

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:

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.

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.

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}"
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.

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}"
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 selects the VPC’s tenant network resource. FNN VPCs use VPC Prefixes, and their Instance interfaces reference a vpcPrefixId. ETHERNET_VIRTUALIZER VPCs use IPv4 Subnets, and their Instance interfaces reference a subnetId. FLAT VPCs attach the network automatically and use neither resource. FNN is the supported target for production deployments with DPUs.

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 an FNN VPC and specify a name.

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"
   }'
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:

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}"
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. This example requires the pre-existing ETHERNET_VIRTUALIZER VPC and IPv4 Subnet from the Subnet examples below, so the interface specifies a subnetId. The VPC ID is distinct from the FNN VPC created above.

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
# 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": "f466a2d5-5820-4824-a845-3218fdff801b",
      "tenantId": "aaf3cb83-8785-4265-a3bd-61e828f87db8",
      "operatingSystemId": "0865029e-3979-432d-985e-2de396ecce32",
      "userData": null,
      "interfaces": [
         {
            "subnetId": "5e1f6c51-a532-437b-b7a5-7dfac214de08"
         }
      ]
      }'
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": "f466a2d5-5820-4824-a845-3218fdff801b",
   "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=${tenant-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"
}
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
            }
         ]
         }'
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=${tenant-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:

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}"
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": "f466a2d5-5820-4824-a845-3218fdff801b",
   "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=${tenant-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=<provider-id> and siteId=<site-id> parameters.

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

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

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}"
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.

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"
      ]
      }'
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.
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=${tenant-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"
      }'
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=${tenant-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"
}

The imageDisk value identifies the whole disk that NICo overwrites. A /dev/disk/by-id/ selector is stable across enumeration changes but must exist on every eligible machine. Use smallest only when the intended boot disk is consistently the smallest whole disk. See Image-Based Operating Systems for selection, update, and filesystem-identity behavior.

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": "ubuntu-22.04-image",
        "description": "Ubuntu 22.04 image-based installation",
        "tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
        "siteIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
        "imageUrl": "https://cloud-images.ubuntu.com/releases/jammy/release-20260826/ubuntu-22.04-server-cloudimg-amd64.img",
        "imageSha": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "imageDisk": "/dev/disk/by-id/nvme-Dell_BOSS-N1_VNOWW12345V0123451UT",
        "rootFsLabel": "cloudimg-rootfs",
        "phoneHomeEnabled": false,
        "allowOverride": false
      }'
Example Response
{
  "id": "44d246f3-3075-4daa-9887-0d376bf9dec5",
  "name": "ubuntu-22.04-image",
  "description": "Ubuntu 22.04 image-based installation",
  "infrastructureProviderId": null,
  "tenantId": "7306ff7d-f2b4-472f-ba1c-3ec9c24967be",
  "type": "Image",
  "imageUrl": "https://cloud-images.ubuntu.com/releases/jammy/release-20260826/ubuntu-22.04-server-cloudimg-amd64.img",
  "imageSha": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
  "imageAuthType": null,
  "imageAuthToken": null,
  "imageDisk": "/dev/disk/by-id/nvme-Dell_BOSS-N1_VNOWW12345V0123451UT",
  "rootFsId": null,
  "rootFsLabel": "cloudimg-rootfs",
  "ipxeScript": null,
  "userData": null,
  "isCloudInit": false,
  "phoneHomeEnabled": false,
  "allowOverride": false,
  "siteAssociations": [],
  "isActive": true,
  "deactivationNote": null,
  "status": "Pending",
  "statusHistory": [
    {
      "status": "Pending",
      "message": "Request received, pending processing",
      "created": "2026-08-31T17:30:00Z",
      "updated": "2026-08-31T17:30:00Z"
    }
  ],
  "created": "2026-08-31T17:30:00Z",
  "updated": "2026-08-31T17:30:00Z"
}

Managing Subnets and VPC Prefixes

Before managing these resources, ensure you have a tenant IP Block at the VPC’s Site. An IPv4 Subnet requires that block to be Ready. VPC Prefixes configure FNN VPCs. IPv4 Subnets configure ETHERNET_VIRTUALIZER VPCs.

Add an IPv4 Subnet to a Ready ETHERNET_VIRTUALIZER VPC. Before running this example, use the Create VPC endpoint to create that VPC and set networkVirtualizationType to ETHERNET_VIRTUALIZER. Replace the pre-existing sample VPC ID f466a2d5-5820-4824-a845-3218fdff801b with the new VPC’s ID. This VPC is distinct from the FNN VPC used by the VPC Prefix examples. The Subnet’s ipv4BlockId identifies a Ready tenant IPv4 IP Block at the same Site, and prefixLength accepts values from 8 through 30.

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": "f466a2d5-5820-4824-a845-3218fdff801b",
        "ipv4BlockId": "20d7dd4f-ae43-4245-a9d9-d093296009c4",
        "prefixLength": 28
    }'
Example Response
{
    "id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
    "name": "demo-ipv4-subnet",
    "description": "Demo IPv4 Tenant Subnet",
    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
    "vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
    "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:

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}"
Example Response
{
    "id": "5e1f6c51-a532-437b-b7a5-7dfac214de08",
    "name": "demo-ipv4-subnet",
    "description": "Demo IPv4 Tenant Subnet",
    "siteId": "bd4692bd-da95-410e-911a-d492fe2d35f8",
    "vpcId": "f466a2d5-5820-4824-a845-3218fdff801b",
    "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"
}

Add a VPC Prefix to the Ready FNN VPC created above. The source IP Block determines the VPC Prefix’s address family. REST support for creating IPv6 FNN VPC Prefixes is tracked by #5407.

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
      }'
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

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"
      }'
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"
}
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
          }
        ]
      }'
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

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}"
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"
  }
]
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": {}
  }'
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"
}
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"
    }
    }'
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"
  }
]
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"
      }
    ]
  }'
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

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
      }'
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:

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.

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"
}
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"
      }'
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.

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"
      ]
    }'
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.

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"
      ]
      }'
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"
}
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}"
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=${tenant-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=${tenant-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.

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 } ]'
Example Response
[
{
   "name": "demo-compute-instance-1",
   "ipAddresses": [
      "192.166.128.3"
   ]
},
{
   "name": "demo-compute-instance-0",
   "ipAddresses": [
      "192.166.128.2"
   ]
}
]