---
title: "Firmware update Trays"
method: PATCH
path: "/v2/org/{org}/nico/tray/firmware"
tags: ["Tray"]
---

# Firmware update Trays

`PATCH /v2/org/{org}/nico/tray/firmware`

Update firmware on Trays with optional filters. If no filter is specified, targets all trays in the Site.

**Filter constraints:**
- `rackId` and `rackName` are mutually exclusive
- `rackId`/`rackName` cannot be combined with `ids`/`componentIds` (rack-level vs component-level targeting)
- `componentIds` requires `type` to be specified

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

## Request body

- BatchTrayFirmwareUpdateRequest — Request body for batch tray firmware update operations
  - `siteId` string, uuid, required — ID of the Site
  - `filter` TrayFilter — Filter criteria for selecting trays in batch operations. If omitted or empty, all trays in the site are targeted. Constraints: `rackId` and `rackName` are mutually exclusive. `rackId`/`rackName` cannot be combined with `ids`/`componentIds`. `componentIds` requires `type`. `slotId` requires `rackId` or `rackName`, must be >= 0, and composes with the rest of the filter via AND.
    - `rackId` string, uuid — Filter by Rack ID
    - `rackName` string — Filter by Rack name
    - `type` 'Compute' | 'NVSwitch' | 'PowerShelf' — Filter by tray type
    - `componentIds` string[] — Filter by component ID. Requires 'type'.
    - `ids` string[] — Filter by tray UUID
    - `slotId` integer — Restrict to trays at this rack slot (matches `position.slotId`). Requires `rackId` or `rackName`. Composes with the rest of the filter via AND.
  - `version` string, nullable — Target firmware version.
  - `targets` string[] — Optional subset of firmware targets to update within each matched tray. Names are lowercase and select sub-parts of the tray (BMC, BIOS, etc.). The accepted set per tray type comes from the Flow service's NICo proto bindings (which mirror Core's per-tray-type enums in `NICo-core/crates/rpc/proto/forge.proto`), so the supported values track Core as new sub-parts are added: - switch trays (NvSwitchComponent): currently bmc, cpld, bios, nvos - powershelf trays (PowerShelfComponent): currently pmc, psu - compute trays (ComputeTrayComponent): currently bmc, bios (currently NOT honored end-to-end: the NICo compute-firmware path goes through SetFirmwareUpdateTimeWindow + auto-update, which has no per-target selection; the request is logged and the whole bundle is applied. Will be honored once compute moves to UpdateComponentFirmware.) Omitted or empty means "update everything in the bundle" (the historical default) for compute-tray-internal targets. Unknown names are rejected. Requires `version` to be set. The special target `dpu`, valid only on compute trays, requests DPU reprovisioning on each matched host. Unlike the other targets, `dpu` is NOT covered by the "omitted/empty means everything" default — it must be listed explicitly. `version` is ignored on the `dpu` branch; the target firmware version comes from site configuration.
  - `authenticationData` union — Optional, write-only authentication data for firmware downloads. Exactly one of `shared` or `perComponent` must be present. Empty string values mean no authentication data for the corresponding target. Authentication data is not supported for DPU-only updates or by the legacy NICo compute firmware controller.
    - object
      - `shared` string, required — Authentication data shared by every supported firmware target.
      - `perComponent` PerComponentFirmwareAuthenticationData — Authentication data scoped to supported firmware tray types. An omitted field means that tray type receives no authentication data.
        - `compute` string — Authentication data for compute tray firmware downloads.
        - `nvswitch` string — Authentication data for NVSwitch tray firmware downloads.
        - `powershelf` string — Authentication data for power shelf firmware downloads.
    - object
      - `shared` string — Authentication data shared by every supported firmware target.
      - `perComponent` PerComponentFirmwareAuthenticationData, required — Authentication data scoped to supported firmware tray types. An omitted field means that tray type receives no authentication data.
        - `compute` string — Authentication data for compute tray firmware downloads.
        - `nvswitch` string — Authentication data for NVSwitch tray firmware downloads.
        - `powershelf` string — Authentication data for power shelf firmware downloads.
  - `ruleId` string, uuid — Optional Operation Rule UUID. When set, pins every task spawned by this batch to the named rule and overrides Flow's default rule resolution.
  - `overrideReadinessCheck` boolean — When true, proceed even if one or more target components (or hosts on the owning rack for rack-scoped components) are reported as not ready by their persisted status. Intended for operator-supervised maintenance.

## Response `200`

OK

- FirmwareUpdateResponse — Response for firmware update operations containing task IDs for tracking
  - `taskIds` string[] — List of task IDs created for the firmware update operation

## 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
- `504` — The Site did not return a result within the request budget allocated to Site communication within the request cycle. This can occur if the Site Controller is down or under heavy request load. Operations are in general safe to retry. In rare cases, operations that create or update resources may succeed even if timeout is returned.

## Changes

- **2026-08-21** `e9eeefc0a6ad` — 1 info
  - added the new optional request property `authenticationData`
- **2026-08-20** `652b7687aa81` — 3 breaking, 3 info
  - removed the enum value `compute` of the request property `filter/type`
  - removed the enum value `powershelf` of the request property `filter/type`
  - removed the enum value `switch` of the request property `filter/type`
  - added the new `Compute` enum value to the request property `filter/type`
  - …2 more
- **2026-08-14** `441cfc1afc1c` — 1 info
  - added the non-success response with the status `504`
- **2026-06-13** `931b24f9a0dc` — 1 info
  - added the new `dpu` enum value to the request property `targets/items/`
- **2026-06-12** `268117a96421` — 1 info
  - added the new optional request property `overrideReadinessCheck`

[Full history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/tray/firmware/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-service-production.skmtc.workers.dev/v1/apis/nvidia/nvidia-infra-controller-rest-api/revisions/2096eb1db2c1/schema)