---
title: "Replace all Expected Machines"
method: PUT
path: "/v2/org/{org}/nico/expected-machine/all"
tags: ["Expected Machine"]
---

# Replace all Expected Machines

`PUT /v2/org/{org}/nico/expected-machine/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-machine/all`
- Auth: HTTP bearer

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

Every entry must use the top-level `siteId`. BMC MAC addresses and chassis serial numbers must be unique within the replacement set. Referenced SKUs must exist at the Site.

Org must have an Infrastructure Provider entity and the caller must have Provider Admin access, or the caller must be a Tenant Admin with effective `TargetedInstanceCreation` access to the Site.

## Request body

- ExpectedMachineList: Complete replacement set of Expected Machines 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 Machines should be replaced
  - `expectedMachines` ExpectedMachineCreateRequest[], required: Full desired Expected Machine set; BMC MAC addresses and chassis serial numbers must be unique
    - `siteId` string, uuid, required: ID of the site the Expected Machine belongs to
    - `bmcMacAddress` string, required: MAC address of the Expected Machine's BMC (Baseboard Management Controller)
    - `defaultBmcUsername` string, nullable: Username for accessing the Expected Machine's BMC
    - `defaultBmcPassword` string, nullable: Password for accessing the Expected Machine's BMC
    - `chassisSerialNumber` string, required: Serial number of the Expected Machine's chassis
    - `fallbackDPUSerialNumbers` string[], nullable: Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
    - `interfaces` ExpectedMachineInterface[], nullable: Optional expected host NIC declarations. Omission or null creates an empty list.
      - `identifier` ExpectedMachineInterfaceIdentifier: Identifies an Expected Machine interface. Exactly one of `macAddress` or `astra` must be set.
        - `macAddress` string, nullable: MAC address of the interface. Accepts six colon- or hyphen-separated octets in either case; stored and returned in uppercase colon-separated form, for example AA:BB:CC:DD:EE:FF. The same MAC may have separate IPv4 and IPv6 declarations.
        - `astra` ExpectedMachineInterfaceAstraIdentifier: Names that Cerebro assigns to an interface on an Astra host.
          - `physicalName` string, required: Physical interface name as recorded in Cerebro, for example `C1-1-L1`. May contain only ASCII letters, digits, `_`, `.`, `:`, and `-`.
          - `logicalName` string, nullable: Optional logical interface name, for example `eth_r0_p0`. May contain only ASCII letters, digits, `_`, `.`, and `-`. Omission or null clears it when replacing the declaration.
      - `macAddress` string, nullable: Deprecated in favor of `identifier.macAddress`. Identifies the interface by MAC address when `identifier` is omitted. When supplied alongside `identifier.macAddress`, both must name the same MAC address. This field may also accompany `identifier.astra` to preserve a MAC address alongside the Astra names. Responses return the interface's MAC address here when it has one, in uppercase colon-separated form.
      - `nicType` string, nullable: Optional NIC type. Use `CX9` for ConnectX-9 interfaces on Astra hosts.
      - `fixedIp` string, nullable: Optional fixed IPv4 or IPv6 address for the interface. It must not be unspecified, multicast, or IPv4 limited broadcast. REST preserves repeated MAC declarations without enforcing uniqueness by MAC and address family; Core applies allocation validation.
      - `fixedMask` string, nullable: Optional legacy mask string, forwarded unchanged. Omission or null clears it when replacing the declaration.
      - `fixedGateway` string, nullable: Optional IPv4 or IPv6 gateway. Omission, null, or an empty string clears it when replacing the declaration.
      - `primary` boolean, nullable: Host boot-interface selection. At most one Host interface per machine may set true. Omission or null clears the declaration. DpuOs and DpuBmc must omit it; HostBmc also accepts false.
      - `networkSegmentType` 'Tenant' | 'Admin' | 'Underlay' | 'HostInband' | 'null', nullable: Optional segment constraint that takes precedence over nicType. Omission or null clears it. For explicit allocation policies and DPU roles it constrains relay-selected or fixed-address segments; legacy Host declarations without an explicit policy use it only for initial DHCP segment selection.
      - `role` 'Unspecified' | 'Host' | 'DpuOs' | 'DpuBmc' | 'HostBmc' | 'null', nullable: Interface owner. On create, omission, null, or Unspecified means Host. On update, omission or null preserves a matching stored role; Unspecified resets it to Host. At most one HostBmc is allowed, with the same MAC as bmcMacAddress.
      - `ipAllocation` 'Unspecified' | 'Dynamic' | 'Fixed' | 'Retained' | 'null', nullable: On create, omission, null, or Unspecified infers Fixed from fixedIp, otherwise Retained for HostBmc and Dynamic for other roles. On update, omission or null preserves a matching stored policy while fixedIp presence is unchanged; Unspecified resets inference. Fixed requires fixedIp; Dynamic and Retained forbid it. Explicit Fixed, inferred DPU Fixed, and inferred HostBmc Fixed with a segment constraint require a containing managed prefix; legacy Host or inferred HostBmc Fixed without a constraint may use static assignments. Retained keeps a DHCP-allocated address for the interface row lifetime.
    - `skuId` string, nullable: Optional ID of an existing SKU at this Expected Machine's Site. Omission or null leaves the SKU association unset. REST rejects an empty string with HTTP 400.
    - `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
    - `serverName` string, nullable: Optional server name advertised to connected switches in LLDP responses and used for cable validation.
    - `slotId` integer, nullable: Slot ID within the rack
    - `trayIdx` integer, nullable: Tray index within the rack
    - `hostId` integer, nullable: Host ID within the tray
    - `isDpfEnabled` boolean, nullable: When true, this host is eligible for DPF-based provisioning. Optional. Omission or null uses an effective default of true. Set false explicitly to disable DPF-based provisioning.
    - `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.
    - `hostLifecycleProfile` HostLifecycleProfile: Per-host lifecycle settings that affect how NICo progresses a host through its state machine.
      - `disableLockdown` boolean, nullable: When true, the server is not locked down during host lifecycle management. When omitted, the existing value is preserved.

## Response `200`

Expected Machines replaced successfully

- ExpectedMachine[]
  - `id` string, uuid: Unique identifier for the Expected Machine
  - `siteId` string, uuid: ID of the site the Expected Machine belongs to
  - `bmcMacAddress` string: MAC address of the Expected Machine's BMC (Baseboard Management Controller)
  - `chassisSerialNumber` string: Serial number of the Expected Machine's chassis
  - `fallbackDPUSerialNumbers` string[]: Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)
  - `interfaces` ExpectedMachineInterface[]: Expected host NIC declarations in their configured order
    - `identifier` ExpectedMachineInterfaceIdentifier: Identifies an Expected Machine interface. Exactly one of `macAddress` or `astra` must be set.
      - `macAddress` string, nullable: MAC address of the interface. Accepts six colon- or hyphen-separated octets in either case; stored and returned in uppercase colon-separated form, for example AA:BB:CC:DD:EE:FF. The same MAC may have separate IPv4 and IPv6 declarations.
      - `astra` ExpectedMachineInterfaceAstraIdentifier: Names that Cerebro assigns to an interface on an Astra host.
        - `physicalName` string, required: Physical interface name as recorded in Cerebro, for example `C1-1-L1`. May contain only ASCII letters, digits, `_`, `.`, `:`, and `-`.
        - `logicalName` string, nullable: Optional logical interface name, for example `eth_r0_p0`. May contain only ASCII letters, digits, `_`, `.`, and `-`. Omission or null clears it when replacing the declaration.
    - `macAddress` string, nullable: Deprecated in favor of `identifier.macAddress`. Identifies the interface by MAC address when `identifier` is omitted. When supplied alongside `identifier.macAddress`, both must name the same MAC address. This field may also accompany `identifier.astra` to preserve a MAC address alongside the Astra names. Responses return the interface's MAC address here when it has one, in uppercase colon-separated form.
    - `nicType` string, nullable: Optional NIC type. Use `CX9` for ConnectX-9 interfaces on Astra hosts.
    - `fixedIp` string, nullable: Optional fixed IPv4 or IPv6 address for the interface. It must not be unspecified, multicast, or IPv4 limited broadcast. REST preserves repeated MAC declarations without enforcing uniqueness by MAC and address family; Core applies allocation validation.
    - `fixedMask` string, nullable: Optional legacy mask string, forwarded unchanged. Omission or null clears it when replacing the declaration.
    - `fixedGateway` string, nullable: Optional IPv4 or IPv6 gateway. Omission, null, or an empty string clears it when replacing the declaration.
    - `primary` boolean, nullable: Host boot-interface selection. At most one Host interface per machine may set true. Omission or null clears the declaration. DpuOs and DpuBmc must omit it; HostBmc also accepts false.
    - `networkSegmentType` 'Tenant' | 'Admin' | 'Underlay' | 'HostInband' | 'null', nullable: Optional segment constraint that takes precedence over nicType. Omission or null clears it. For explicit allocation policies and DPU roles it constrains relay-selected or fixed-address segments; legacy Host declarations without an explicit policy use it only for initial DHCP segment selection.
    - `role` 'Unspecified' | 'Host' | 'DpuOs' | 'DpuBmc' | 'HostBmc' | 'null', nullable: Interface owner. On create, omission, null, or Unspecified means Host. On update, omission or null preserves a matching stored role; Unspecified resets it to Host. At most one HostBmc is allowed, with the same MAC as bmcMacAddress.
    - `ipAllocation` 'Unspecified' | 'Dynamic' | 'Fixed' | 'Retained' | 'null', nullable: On create, omission, null, or Unspecified infers Fixed from fixedIp, otherwise Retained for HostBmc and Dynamic for other roles. On update, omission or null preserves a matching stored policy while fixedIp presence is unchanged; Unspecified resets inference. Fixed requires fixedIp; Dynamic and Retained forbid it. Explicit Fixed, inferred DPU Fixed, and inferred HostBmc Fixed with a segment constraint require a containing managed prefix; legacy Host or inferred HostBmc Fixed without a constraint may use static assignments. Retained keeps a DHCP-allocated address for the interface row lifetime.
  - `skuId` string, nullable: Stored SKU ID for this Expected Machine, or null when no association is stored. The ID can belong to another Site, including when inventory synchronization imports an entry configured directly in Core.
  - `sku` Sku: A SKU (Stock Keeping Unit) represents a unique hardware configuration discovered at a site. SKUs are automatically derived from machine hardware characteristics and used to group similar machines.
    - `id` string: Unique identifier for the SKU
    - `siteId` string, uuid: ID of the Site this SKU belongs to
    - `description` string: Human-readable SKU description
    - `schemaVersion` integer: Core SKU schema version when available
    - `deviceType` string, nullable: Optional device type identifier (e.g. "gpu", "cpu", "storage")
    - `associatedMachineIds` string[]: List of machine IDs associated with this SKU
    - `components` SkuComponents: Hardware components that make up a SKU
      - `cpus` SkuCpu[]: CPU components
        - `vendor` string: Vendor of the CPU
        - `model` string: Model of the CPU
        - `threadCount` integer: Number of threads for the CPU
        - `count` integer: Number of CPUs present
      - `gpus` SkuGpu[]: GPU components
        - `vendor` string: Vendor of the GPU
        - `model` string: Model of the GPU
        - `totalMemory` string: Total memory of the GPU (e.g. "80GB HBM3")
        - `count` integer: Number of GPUs present
      - `memory` SkuMemory[]: Memory components
        - `capacityMb` integer: Capacity in megabytes
        - `memoryType` string: Type of memory (e.g. "DDR4", "DDR5")
        - `count` integer: Number of memory modules present
      - `storage` SkuStorage[]: Storage components
        - `vendor` string: Storage vendor used for schema version 4 matching. Read-only in REST mutation requests and preserved in responses for legacy SKUs. Schema version 5 does not use this field.
        - `model` string: Informational storage model. Starting with the 2.1 release, NICo does not use this field for storage matching or validation.
        - `capacityMb` integer: Storage capacity in megabytes used for schema version 4 matching. Read-only in REST mutation requests and preserved in responses for legacy SKUs. Schema version 5 uses minSizeMiB and maxSizeMiB instead.
        - `count` integer: Number of storage devices present
        - `minSizeMiB` integer, nullable: Inclusive minimum size in MiB for each storage device. Null or omission means no lower bound. Used for SKU schema version 5 and later.
        - `maxSizeMiB` integer, nullable: Inclusive maximum size in MiB for each storage device. Null or omission means no upper bound. Used for SKU schema version 5 and later.
        - `pciPatterns` string[]: Regular expressions matched against each drive's sysfs PCI path. An empty or omitted list disables PCI location matching. Used for SKU schema version 5 and later. The matched path is the NVMe controller's sysfs DEVPATH with its trailing kernel-assigned `nvmeN` node removed, for example `/devices/pci0000:00/0000:64:00.0/0000:65:00.0/nvme`, because that node changes with probe order. Patterns that anchor on the node (such as `nvme0$`) never match; end them at `/nvme` instead.
      - `chassis` SkuChassis: Chassis component in a SKU
        - `vendor` string: Vendor of the chassis
        - `model` string: Model of the chassis
        - `architecture` string: Architecture of the chassis
      - `ethernetDevices` SkuEthernetDevice[]: Read-only Ethernet device components reported by Core. Omit this property from REST mutation requests; null and an empty array are accepted for compatibility, while a non-empty array is rejected with HTTP 400.
        - `vendor` string: Vendor of the ethernet device
        - `model` string: Model of the ethernet device
        - `count` integer: Number of ethernet devices present
        - `isConnected` boolean: Whether the ethernet device is connected
      - `infinibandDevices` SkuInfinibandDevice[]: Infiniband device components
        - `vendor` string: Vendor of the infiniband device
        - `model` string: Model of the infiniband device
        - `count` integer: Number of infiniband devices present
        - `inactiveDevices` integer[]: Zero-based indexes of inactive devices
      - `tpm` SkuTpm: TPM component in a SKU
        - `vendor` string: Vendor of the TPM
        - `version` string: Version of the TPM
    - `created` string, date-time: ISO 8601 datetime when the SKU was created, using the Site-reported timestamp when available
  - `machineId` string, nullable: Stored Machine ID for this Expected Machine, or null when no association is stored. The ID can belong to another Site.
  - `machine` MachineSummary: Describes a subset of core attributes for a Machine
    - `id` string: Unique ID of Machine
    - `controllerMachineId` string: ID of the Machine at Site, now same as the primary ID
    - `controllerMachineType` string, nullable: Denotes architecture (x86 vs ARM) of the Machine
    - `hwSkuDeviceType` string, nullable: SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.
    - `vendor` string, nullable: Name of the vendor of the Machine
    - `productName` string, nullable: Product name of the Machine
    - `maintenanceMessage` string, nullable: If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance
    - `status` 'Initializing' | 'Ready' | 'Reset' | 'Maintenance' | 'InUse' | 'Error' | 'Decommissioning' | 'Decommissioned' | 'Unknown': Machine status combines the observed Core lifecycle with REST Instance assignment. A Ready Machine becomes InUse when REST assigns it, and remains InUse if Core reports Ready while the REST assignment still exists. Error, Maintenance, Initializing, and other non-Ready states retain precedence. When Instance deletion clears the assignment, InUse returns to Ready only if the retained Core snapshot reports Ready; otherwise fresh Machine inventory establishes the next status. Ready is not a reservation and does not guarantee that a subsequent Instance creation will succeed.
  - `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
  - `serverName` string, nullable: Optional server name advertised to connected switches in LLDP responses and used for cable validation.
  - `slotId` integer, nullable: Slot ID within the rack
  - `trayIdx` integer, nullable: Tray index within the rack
  - `hostId` integer, nullable: Host ID within the tray
  - `isDpfEnabled` boolean: When true, this host is eligible for DPF-based provisioning. Returns the effective setting: true when no value is configured. An explicitly configured false value is returned as false.
  - `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.
  - `hostLifecycleProfile` HostLifecycleProfile: Per-host lifecycle settings that affect how NICo progresses a host through its state machine.
    - `disableLockdown` boolean, nullable: When true, the server is not locked down during host lifecycle management. When omitted, the existing value is preserved.
  - `created` string, date-time: ISO 8601 datetime when the Expected Machine was created
  - `updated` string, date-time: ISO 8601 datetime when the Expected Machine 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-20** `9f3097478c07`: 2 breaking, 8 info
  - the response property `items/interfaces/items/macAddress` became nullable for the status `200`
  - the response property `items/interfaces/items/macAddress` became optional for the status `200`
  - added the new optional request property `expectedMachines/items/interfaces/items/identifier`
  - added the new optional request property `expectedMachines/items/serverName`
  - …6 more
- **2026-10-20** `273aadbf1c41`: 2 breaking
  - added `#/components/schemas/SkuTpm, subschema #2` to the `items/sku/components/tpm` response property `oneOf` list for the response status `200`
  - the `items/sku/components/tpm` response's property type changed from `array` to no type for status `200`
- **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** `4cff26a47e4c`: 2 info
  - added the new optional request property `expectedMachines/items/interfaces`
  - added the optional property `items/interfaces` to the response with the `200` status

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