--- title: "Update Expected Rack Group" method: PATCH path: "/v2/org/{org}/nico/expected-rack-group/{id}" tags: ["Expected Rack Group"] --- # Update Expected Rack Group `PATCH /v2/org/{org}/nico/expected-rack-group/{id}` Update an existing Expected Rack Group identified by its `id`. Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix. Infrastructure Provider must own the Expected Rack Group. Alternatively, Tenant Admins with `TargetedInstanceCreation` capability can also update Expected Rack Groups if they have an account with the Site's Infrastructure Provider. `rackGroupId` is immutable: an update that changes it is rejected with `400` before any database mutation. ## Request body - ExpectedRackGroupUpdateRequest — Request data to update an existing Expected Rack Group. For updates (`PATCH /expected-rack-group/{id}`), omit `id` or set it to `null` to use the ID from the URL path. A supplied string must match the URL path UUID in lowercase, hyphenated form. Empty strings, invalid UUIDs, and mismatched IDs are rejected with HTTP 400. Provide a non-null value for at least one of `rackGroupId`, `topology`, `racks`, `name`, `description`, or `labels`. An empty object, a body containing only `id`, or a body with all six fields omitted or set to `null` returns HTTP 400. Empty arrays for `racks`, empty objects for `labels`, and empty strings for `name` or `description` count as updates and clear those values. The `rackGroupId` field is immutable on update. Providing its existing value alone satisfies the update requirement and still updates the modification time and sends the group to Core. Changing it returns HTTP 400. 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, nullable — Unique identifier (UUID) of the Expected Rack Group to update. Can be omitted or set to `null`. A supplied string must match the URL path UUID in lowercase, hyphenated form. Empty strings, invalid UUIDs, and mismatched IDs are rejected with HTTP 400. - `rackGroupId` string, nullable — Operator-supplied rack group identifier. Immutable on update: omit this field, send `null`, or provide the existing value without changing the identity. A changed value is rejected because Core uses rackGroupId as the identity key. - `topology` string, nullable — Optional replacement 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` object, nullable — 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 `200` OK - 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 - `404` — Error response when requested object is not found ## Changes > 163 revisions in range; 1 not diffed. - **2026-09-29** `78f3b35615a5` — 3 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 - added the optional property `retryable` to the response with the `404` status - **2026-09-23** `e8a756ae2577` — 3 breaking, 1 info - added 'else' subschema to the request body - added 'if' subschema to the request body - the `labels` request property type changed from `object` to no type - added `#/components/schemas/Labels, subschema #2` to the `labels` request property `oneOf` list - **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/:id/patch.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)