---
title: "Replace all Expected Switches"
method: PUT
path: "/v2/org/{org}/nico/expected-switch/all"
tags: ["Expected Switch"]
---

# Replace all Expected Switches

`PUT /v2/org/{org}/nico/expected-switch/all`

## Request

- Base URL: `https://nico-rest-api.nico.svc.cluster.local`
- URL: `https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/expected-switch/all`
- Auth: HTTP bearer

Replace the complete Expected Switch set for one Site. Entries omitted from the request are deleted, and entries in the request are created with new REST IDs. The `expectedSwitches` array may be empty to clear the Site's set.

Every entry must use the top-level `siteId`. BMC MAC addresses, switch serial numbers, and NVOS MAC addresses must be unique within the replacement set.

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

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

## Request body

- ExpectedSwitchList: Complete replacement set of Expected Switches for one Site. Every entry must use the top-level `siteId`; the array may be empty to clear the set.
  - `siteId` string, uuid, required: ID of the Site whose Expected Switches should be replaced
  - `expectedSwitches` ExpectedSwitchCreateRequest[], required: Full desired Expected Switch set; BMC MAC addresses, serial numbers, and NVOS MAC addresses must be unique
    - `siteId` string, uuid, required: ID of the site the Expected Switch belongs to
    - `bmcMacAddress` string, required: MAC address of the Expected Switch's BMC (Baseboard Management Controller)
    - `defaultBmcUsername` string, nullable: Username for accessing the Expected Switch's BMC (no API length limit; the BMC's username policy still applies)
    - `defaultBmcPassword` string, nullable: Password for accessing the Expected Switch's BMC (up to 255 characters; the BMC's password policy still applies)
    - `switchSerialNumber` string, required: Serial number of the Expected Switch
    - `nvOsUsername` string, nullable: NvOS username for the Expected Switch
    - `nvOsPassword` string, nullable: NvOS password for the Expected Switch
    - `nvosInterfaces` NvosInterface[], required: Required NVOS ethernet ports of the Expected Switch. Mark one entry primary to choose eth0; when none is marked, the first entry on a multi-port switch defaults to primary and a single-port switch is always its own primary. The deprecated `nvosMacAddresses` field is ignored even when both fields are supplied.
      - `macAddress` string, required: MAC address of this NVOS ethernet port.
      - `isPrimary` boolean: Whether this port is the primary (eth0) NVOS port that NICo manages through RMS. At most one port per switch can be primary; when no port is marked, the first port on a multi-port switch defaults to primary and a single-port switch is always its own primary.
    - `nvosMacAddresses` string[]: Deprecated and ignored. This field never configures NVOS ports or primary selection, regardless of its contents. Use `nvosInterfaces`, including in replace-all entries. Supplying both fields is allowed; only `nvosInterfaces` takes effect.
    - `rackId` string, nullable: Optional rack identifier for this component
    - `bmcIpAddress` string, nullable: Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC. It must not be unspecified, multicast, or IPv4 limited broadcast.
    - `name` string, nullable: Display name for this component
    - `manufacturer` string, nullable: Manufacturer of this component
    - `model` string, nullable: Model of this component
    - `description` string, nullable: Description of this component
    - `slotId` integer, nullable: Slot ID within the rack
    - `trayIdx` integer, nullable: Tray index within the rack
    - `hostId` integer, nullable: Host ID within the tray
    - `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 `200`

Expected Switches replaced successfully

- ExpectedSwitch[]
  - `id` string, uuid: Unique identifier for the Expected Switch
  - `siteId` string, uuid: ID of the site the Expected Switch belongs to
  - `bmcMacAddress` string: MAC address of the Expected Switch's BMC (Baseboard Management Controller)
  - `switchSerialNumber` string: Serial number of the Expected Switch
  - `nvosInterfaces` NvosInterface[]: NVOS ethernet ports of the Expected Switch, with the primary (eth0) port flagged. Array order is not stable across inventory synchronization; identify ports by MAC and use isPrimary for selection.
    - `macAddress` string, required: MAC address of this NVOS ethernet port.
    - `isPrimary` boolean: Whether this port is the primary (eth0) NVOS port that NICo manages through RMS. At most one port per switch can be primary; when no port is marked, the first port on a multi-port switch defaults to primary and a single-port switch is always its own primary.
  - `nvosMacAddresses` string[]: Deprecated flat NVOS MAC list retained for v2 compatibility. Use `nvosInterfaces`. Responses emit both fields, and this array contains the same MACs in the same order as `nvosInterfaces`.
  - `rackId` string, nullable: Optional rack identifier for this component
  - `bmcIpAddress` string, nullable: Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.
  - `name` string, nullable: Display name for this component
  - `manufacturer` string, nullable: Manufacturer of this component
  - `model` string, nullable: Model of this component
  - `description` string, nullable: Description of this component
  - `slotId` integer, nullable: Slot ID within the rack
  - `trayIdx` integer, nullable: Tray index within the rack
  - `hostId` integer, nullable: Host ID within the tray
  - `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 Switch was created
  - `updated` string, date-time: ISO 8601 datetime when the Expected Switch 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
- `409`: Error response when the request conflicts with an existing resource or operation

## Changes

- **2026-10-19** `4890ac0cf6ac`: 1 breaking, 3 info
  - added the new required request property `expectedSwitches/items/nvosInterfaces`
  - request property `expectedSwitches/items/nvosMacAddresses` deprecated
  - added the optional property `items/nvosInterfaces` to the response with the `200` status
  - response property `items/nvosMacAddresses` deprecated
- **2026-10-15** `293dc126ab73`: 3 info
  - removed the `nico` enum value from the `source` response property for the response status `400`
  - removed the `nico` enum value from the `source` response property for the response status `403`
  - removed the `nico` enum value from the `source` response property for the response status `409`
- **2026-10-14** `4a2b5e050a2e`: 1 info
  - added the non-success response with the status `409`
- **2026-10-06** `3109a305f618`: 1 info
  - the `expectedSwitches/items/defaultBmcPassword` request property's maxLength was increased from `20` to `255`
- **2026-09-29** `485b50d90226`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/expected-switch/all/put.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/db15b7308121?raw)