---
title: "Create Expected Rack Group"
method: POST
path: "/v2/org/{org}/nico/expected-rack-group"
tags: ["Expected Rack Group"]
---

# Create Expected Rack Group

`POST /v2/org/{org}/nico/expected-rack-group`

Create an Expected Rack Group to declare racks and devices at a Site. The `rackGroupId` is an opaque operator-supplied string identifier (UUID syntax is not required) that uniquely identifies the group within the Site.

Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix.

Alternatively, Tenant Admins with `TargetedInstanceCreation` capability can also create Expected Rack Groups if they have an account with the Site's Infrastructure Provider.

Chassis identity and physical location information are conveyed via well-known label keys in `labels`:
- `chassis.manufacturer`, `chassis.serial-number`, `chassis.model`
- `location.region`, `location.datacenter`, `location.room`, `location.position`

## Request body

- ExpectedRackGroupCreateRequest — Request data to create a new Expected Rack Group. The `rackGroupId` is an operator-supplied string identifier (UUID syntax is not required) that must be unique within the Site. Chassis identity and physical location information are conveyed via well-known label keys in `labels`: - `chassis.manufacturer`, `chassis.serial-number`, `chassis.model` - `location.region`, `location.datacenter`, `location.room`, `location.position`
  - `siteId` string, uuid, required — ID of the Site the Expected Rack Group belongs to
  - `rackGroupId` string, required — Operator-supplied identifier for the rack group (opaque string; UUID syntax is not required). Must be non-empty and unique within the Site.
  - `topology` string, required — External group-level NVLink topology identifier, non-blank and at most 128 characters.
  - `racks` ExpectedRackGroupRack[], nullable — Ordered racks and their devices. Rack IDs and device identity tuples must be unique across the group, with case-sensitive comparison. A provided array replaces the complete list; on PATCH, omission or null preserves it and [] clears it. On create, omission or null supplies an empty list.
    - `rackId` string, required — Non-blank, case-sensitive external rack identifier, unique within the group.
    - `members` ExpectedRackGroupMember[], nullable — Ordered devices in this rack. Device identities are unique across all racks in the group.
      - `type` 'Compute' | 'NVSwitch' | 'PowerShelf', required — Case-sensitive REST rack component type. NVSwitch maps to Switch in Core.
      - `manufacturer` string, required — Non-blank manufacturer name.
      - `id` string, required — Non-blank opaque external device inventory identifier.
  - `name` string, nullable — ASCII human-readable name, at most 256 characters. An empty string is allowed.
  - `description` string, nullable — Human-readable description, at most 1024 UTF-8 bytes. An empty string is allowed.
  - `labels` Labels — Label keys must not be empty or whitespace-only. Keys and values may contain at most 255 characters and must not contain the Unicode NUL character (U+0000). Empty values are allowed.

## Response `201`

Created

- ExpectedRackGroup — An Expected Rack Group declares a group-level NVLink topology, racks, and expected device members. The `rackGroupId` is an operator-supplied string identifier (UUID syntax is not required) that uniquely identifies the group within the Site. Topology is supplied by the external inventory system. Chassis identity and physical location information are conveyed via well-known label keys in `labels`: - `chassis.manufacturer`, `chassis.serial-number`, `chassis.model` - `location.region`, `location.datacenter`, `location.room`, `location.position`
  - `id` string, uuid — Unique identifier (UUID) for the Expected Rack Group
  - `rackGroupId` string — Operator-supplied identifier for the rack group (opaque string; UUID syntax is not required). Unique within a Site.
  - `siteId` string, uuid — ID of the Site the Expected Rack Group belongs to
  - `site` Site — Site is a datacenter that is running NVIDIA Infra Controller (NICo) services
    - `id` string, uuid — Unique UUID v4 identifier for the Site in NICo Cloud
    - `name` string — Name of the Site
    - `description` string, nullable — Optional description for the Site
    - `org` string — NGC organization ID of the Infrastructure Provider that owns the Site
    - `infrastructureProviderId` string, uuid — ID of the Infrastructure Provider that owns the Site
    - `siteControllerVersion` string, nullable — Version of the Site Controller software
    - `siteAgentVersion` string, nullable — Version of the Site Agent software
    - `registrationToken` string, nullable — Token that can be used to register a Site. Value only exposed to Provider
    - `registrationTokenExpiration` string, date-time, nullable — Date/time when registration token expires. Value only exposed to Provider
    - `serialConsoleHostname` string, hostname, nullable — Serial console hostname of the site controller
    - `isSerialConsoleEnabled` boolean — Indicates if Serial Console is enabled for the Site by the Provider
    - `serialConsoleIdleTimeout` integer, nullable — Maximum idle time in seconds before Serial Console is disconnected
    - `serialConsoleMaxSessionLength` integer, nullable — Maximum length of Serial Console session in seconds
    - `isSerialConsoleSSHKeysEnabled` boolean — Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant
    - `isOnline` boolean — Indicates if the Site is currently reachable from Cloud
    - `status` 'Pending' | 'Registered' | 'Error' — Status values for Site objects
    - `statusHistory` StatusDetail[] — Chronological status history for the Site
      - `status` string — State of the associated entity at a particular time
      - `message` string, nullable — Description of the state and cause/remedy in case of error
      - `created` string, date-time — Date/time when the associated entity assumed the status
      - `updated` string, date-time — Date/time when the associated entity was last observed with this status
    - `created` string, date-time — Date/time when the Site was created
    - `updated` string, date-time — Date/time when the Site was last updated
    - `location` SiteLocation — Location of the Site
      - `city` string — City where the site is located
      - `state` string — State where the site is located
      - `country` string — Country where the site is located
    - `contact` SiteContact — Contact for the Site
      - `email` string — Email address of the Site contact
    - `capabilities` SiteCapabilities — Boolean flags to indicate features supported by a Site
      - `nativeNetworking` boolean — Whether the Site supports native networking
      - `networkSecurityGroup` boolean — Whether the Site supports Network Security Groups
      - `nvLinkPartition` boolean — Whether the Site supports NVLink partitioning
      - `flow` boolean — Whether the Site supports Flow-based operations
      - `imageBasedOperatingSystem` boolean — Whether the Site supports image-based operating system provisioning
      - `vpcSlaac` boolean — Whether the latest successfully stored Site configuration inventory reports that Core supports VPCs with SLAAC enabled. False also represents a missing Site configuration or an inventory report that omits the capability. This value is managed by Site configuration inventory and cannot be updated through the Site API.
      - `dpsPowerManagement` boolean — Whether this Site accepts non-empty power resource groups and power profiles for DPS power management. When false, omission and explicit clearing remain allowed.
    - `machineStats` SiteMachineStats — Machine stats for a Site
      - `total` integer — Total number of Machines at the Site
      - `totalByStatus` SiteMachineStatsByStatus — Machine stats for a Site by status
        - `Decommissioned` integer — Number of Machines in Decommissioned status
        - `Decommissioning` integer — Number of Machines in Decommissioning status
        - `Error` integer — Number of Machines in Error status
        - `Initializing` integer — Number of Machines in Initializing status
        - `InUse` integer — Number of Machines in InUse status
        - `Maintenance` integer — Number of Machines in Maintenance status
        - `Ready` integer — Number of Machines in Ready status
        - `Reset` integer — Number of Machines in Reset status
        - `Unknown` integer — Number of Machines in Unknown status
      - `totalByHealth` SiteMachineStatsByHealth — Machine stats for a Site by health
        - `healthy` integer — Number of healthy Machines
        - `unhealthy` integer — Number of unhealthy Machines
      - `totalByStatusAndHealth` SiteMachineStatsByStatusAndHealth — Machine stats for a Site by status and health
        - `Decommissioned` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Decommissioning` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Error` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Initializing` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `InUse` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Maintenance` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Ready` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Reset` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
        - `Unknown` SiteMachineStatsByHealth — Machine stats for a Site by health
          - `healthy` integer — Number of healthy Machines
          - `unhealthy` integer — Number of unhealthy Machines
      - `totalByAllocation` SiteMachineStatsByAllocation — Machine stats for a Site by allocation
        - `allocatedInUse` integer — Number of allocated Machines currently in use
        - `allocatedNotInUse` integer — Number of allocated Machines not currently in use
        - `unallocated` integer — Number of Machines not currently allocated
    - `gpuStats` MachineGPUStats[] — GPU counts grouped by GPU type for the Site. Populated when includeGpuStats is set
      - `name` string — GPU name from the MachineCapability record
      - `gpus` integer — Total number of GPUs (summation of all Machine GPU capability counts)
      - `machines` integer — Number of machines that have this GPU capability
  - `topology` string — External group-level NVLink topology identifier.
  - `racks` ExpectedRackGroupRack[] — Ordered racks and their devices. Arrays are always present, including empty lists. Rack IDs and device identity tuples are unique across the group, with case-sensitive comparison.
    - `rackId` string, required — Non-blank, case-sensitive external rack identifier, unique within the group.
    - `members` ExpectedRackGroupMember[], nullable — Ordered devices in this rack. Device identities are unique across all racks in the group.
      - `type` 'Compute' | 'NVSwitch' | 'PowerShelf', required — Case-sensitive REST rack component type. NVSwitch maps to Switch in Core.
      - `manufacturer` string, required — Non-blank manufacturer name.
      - `id` string, required — Non-blank opaque external device inventory identifier.
  - `name` string — Human-readable name of the Expected Rack Group
  - `description` string — Human-readable description of the Expected Rack Group
  - `labels` Labels — Label keys must not be empty or whitespace-only. Keys and values may contain at most 255 characters and must not contain the Unicode NUL character (U+0000). Empty values are allowed.
  - `created` string, date-time — ISO 8601 datetime when the Expected Rack Group was created
  - `updated` string, date-time — ISO 8601 datetime when the Expected Rack Group was last updated

## Other responses

- `400` — Error response when request data cannot be validated
- `403` — Error response when user is not authorized to call an endpoint or retrieve/modify objects

## Changes

> 163 revisions in range; 1 not diffed.

- **2026-09-29** `78f3b35615a5` — 2 info
  - added the optional property `retryable` to the response with the `400` status
  - added the optional property `retryable` to the response with the `403` status
- **2026-09-23** `cf1b2b20dc45` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/expected-rack-group/post.md)

---

[API](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api.md) · [All operations](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/revisions/dc3e44191b0d?raw)