> This page is for NVIDIA Infra Controller. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/infra-controller/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/infra-controller/_mcp/server. # Update Machine Spectrum-X multiplane maintenance PATCH https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/machine/{machineId}/spectrumx-multiplane Content-Type: application/json Atomically update the Cartesian product of the selected rails and planes. Supply exactly one of rail, allRails, or railRange and exactly one of plane, allPlanes, or planeRange. Ranges are inclusive and ascending. All selected interfaces must be declared on the Machine; an undeclared selection rejects the complete update. Unselected interfaces are unchanged. maintenanceMode true disables links; false enables them. An omitted or null reference preserves the saved reference; an empty string clears it. For Infrastructure Providers: Org must have an Infrastructure Provider entity and own the Site that the Machine belongs to. User must have authorization role with `PROVIDER_ADMIN` suffix. When the Machine has a Tenant Instance attached, `acknowledgeAttachedInstance` must be set to `true` in order to acknowledge the risk. A `200` response confirms that the desired configuration was saved, but not completion of the hardware operation. User should fetch Machine details in order to detect whether DPU observations have the desired interface revision and the requested maintenance mode or if it has an error. The returned API data are separate per DPU and may be absent or describe an earlier revision while operation is in progress. Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/machine/update-machine-spectrumx-multiplane ## Authentication - `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="" # Example org name: "acme-inc export ORG_NAME= # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ``` ## Request ### Path parameters - `org` (string, required) — Name of the Org - `machineId` (string, required) — ID of the Machine ### Body (application/json) This endpoint expects a MachineSpectrumXMultiplaneUpdateRequest. - `maintenanceMode` (boolean, required) — True disables the selected links; false enables them. - `rail` (integer, optional) — Single rail to update, from 0 through 3. Supply exactly one of rail, allRails, or railRange. - `allRails` (boolean, optional) — Select all four rails. If supplied, must be true. Supply exactly one of rail, allRails, or railRange. - `railRange` (SpectrumXMultiplaneRange, optional) — Inclusive ascending range of rails to update. Both endpoints must be from 0 through 3. Supply exactly one of rail, allRails, or railRange. - `plane` (integer, optional) — Single plane to update on each selected rail, from 0 through 7. Supply exactly one of plane, allPlanes, or planeRange. - `allPlanes` (boolean, optional) — Select all eight planes on each selected rail. If supplied, must be true. Supply exactly one of plane, allPlanes, or planeRange. - `planeRange` (SpectrumXMultiplaneRange, optional) — Inclusive ascending range of planes to update on each selected rail. Both endpoints must be from 0 through 7. Supply exactly one of plane, allPlanes, or planeRange. - `reference` (string, optional, nullable) — Omit or send null to preserve it; send an empty string to clear it. - `acknowledgeAttachedInstance` (boolean, optional) — Must be true when an Instance is attached to the Machine. Acknowledges that maintenance changes may disrupt the Instance's Tenant workload. ## Response ### 200 Saved desired configuration with the latest available per-DPU observations - `machineId` (string, required) — ID of the Machine whose maintenance configuration and DPU observations are returned. - `interfaces` (list of MachineSpectrumXMultiplaneInterface, required) — Declared interfaces ordered by rail and plane. - `dpuStatuses` (list of MachineSpectrumXMultiplaneDPUStatus, required) — One entry per associated BlueField-4 DPU, ordered by DPU ID. Empty when none are present. ## Errors ### 400 Bad Request Error Error response when request data cannot be validated - `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide` - `message` (string, optional) — Message describing the error - `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error - `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified. ### 403 Forbidden Error Error response when user is not authorized to call an endpoint or retrieve/modify objects - `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide` - `message` (string, optional) — Message describing the error - `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error - `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified. ### 404 Not Found Error Error response when requested object is not found - `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide` - `message` (string, optional) — Message describing the error - `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error - `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified. ### 412 Precondition Failed Error Machine has no declared CX9 logical interfaces for multiplane maintenance - `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide` - `message` (string, optional) — Message describing the error - `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error - `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified. ### 500 Internal Server Error Response when the API handler encounters an unexpected error - `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide` - `message` (string, optional) — Message describing the error - `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error - `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified. ### 503 Service Unavailable Error Site service unavailable - `any` ### 504 Gateway Timeout Error Site request timed out; its outcome may still be pending - `any` ## Types ### SpectrumXMultiplaneRange Inclusive ascending bounds. Rail bounds are 0 through 3; plane bounds are 0 through 7. - `start` (integer, required) — First value in the inclusive range. - `end` (integer, required) — Last value in the inclusive range. Must be greater than or equal to start. ### MachineSpectrumXMultiplaneInterface Desired configuration for one declared rail/plane interface. - `logicalName` (string, required) — Logical interface name in the form eth\_r\\_p\, identifying the declared rail and plane. - `rail` (integer, required) — Rail number of this interface, from 0 through 3. - `plane` (integer, required) — Plane number of this interface, from 0 through 7. - `configuredMaintenanceMode` (boolean, required, nullable) — Null until an operator requests a mode. True disables links; false enables them. - `reference` (string, required, nullable) — Reference recorded with the maintenance configuration, such as a ticket URL. Null if no reference is stored. - `revision` (string, required) — Version of this interface's desired maintenance configuration. Compare it with each DPU observation's revision to determine whether the observation describes the current request. ### MachineSpectrumXMultiplaneDPUStatus Independent maintenance observations from one associated BlueField-4 DPU. - `dpuMachineId` (string, required) — ID of the associated BlueField-4 DPU whose interface observations are returned. - `interfaces` (list of MachineSpectrumXMultiplaneObservation, required) — One entry per declared interface, including those without readback. ### NiCoApiErrorData Additional data about the error ### MachineSpectrumXMultiplaneObservation The last attempted interface revision and observed state. A revision may lag the desired configuration. - `logicalName` (string, required) — Logical interface name in the form eth\_r\\_p\, matching the corresponding desired interface configuration. - `maintenanceMode` (boolean, required, nullable) — Null when readback is unavailable; false means maintenance is off. - `revision` (string, required) — Desired configuration revision last attempted by this DPU. May be older than the current desired revision. Empty if the DPU has not reported an observation. - `netdev` (string, required, nullable) — Linux network device name resolved by the DPU for this logical interface. Null if no device was resolved. - `error` (string, required, nullable) — Error from the DPU's attempt to apply or observe this interface. Null when no error has been reported. - `observed` (datetime, required, nullable) — Timestamp when the DPU attempted to apply or observe this interface, in RFC 3339 format. Null if the DPU has not reported an observation. ## Examples ### Example 1 **Request** ```json { "maintenanceMode": true, "railRange": { "start": 0, "end": 3 }, "allPlanes": true, "reference": "CHG-12345", "acknowledgeAttachedInstance": true } ``` **Response** ```json { "machineId": "fm100psbtmb15tgh6q5duqb8ke5grng7ksd96hetbeie9nc5pvcca6eol80", "interfaces": [ { "logicalName": "eth_r0_p0", "rail": 0, "plane": 0, "configuredMaintenanceMode": false, "reference": "CHG-12345", "revision": "V1-T1748645613333257" } ], "dpuStatuses": [] } ``` **SDK Code** ```python Example 1 import requests url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane" payload = { "maintenanceMode": True, "railRange": { "start": 0, "end": 3 }, "allPlanes": True, "reference": "CHG-12345", "acknowledgeAttachedInstance": True } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example 1 const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"maintenanceMode":true,"railRange":{"start":0,"end":3},"allPlanes":true,"reference":"CHG-12345","acknowledgeAttachedInstance":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 1 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane" payload := strings.NewReader("{\n \"maintenanceMode\": true,\n \"railRange\": {\n \"start\": 0,\n \"end\": 3\n },\n \"allPlanes\": true,\n \"reference\": \"CHG-12345\",\n \"acknowledgeAttachedInstance\": true\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example 1 require 'uri' require 'net/http' url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"maintenanceMode\": true,\n \"railRange\": {\n \"start\": 0,\n \"end\": 3\n },\n \"allPlanes\": true,\n \"reference\": \"CHG-12345\",\n \"acknowledgeAttachedInstance\": true\n}" response = http.request(request) puts response.read_body ``` ```java Example 1 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"maintenanceMode\": true,\n \"railRange\": {\n \"start\": 0,\n \"end\": 3\n },\n \"allPlanes\": true,\n \"reference\": \"CHG-12345\",\n \"acknowledgeAttachedInstance\": true\n}") .asString(); ``` ```php Example 1 request('PATCH', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane', [ 'body' => '{ "maintenanceMode": true, "railRange": { "start": 0, "end": 3 }, "allPlanes": true, "reference": "CHG-12345", "acknowledgeAttachedInstance": true }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Example 1 using RestSharp; var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"maintenanceMode\": true,\n \"railRange\": {\n \"start\": 0,\n \"end\": 3\n },\n \"allPlanes\": true,\n \"reference\": \"CHG-12345\",\n \"acknowledgeAttachedInstance\": true\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example 1 import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "maintenanceMode": true, "railRange": [ "start": 0, "end": 3 ], "allPlanes": true, "reference": "CHG-12345", "acknowledgeAttachedInstance": true ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Example 2 **Request** ```json { "maintenanceMode": false, "rail": 0, "planeRange": { "start": 2, "end": 5 } } ``` **Response** ```json { "machineId": "fm100psbtmb15tgh6q5duqb8ke5grng7ksd96hetbeie9nc5pvcca6eol80", "interfaces": [ { "logicalName": "eth_r0_p0", "rail": 0, "plane": 0, "configuredMaintenanceMode": false, "reference": "CHG-12345", "revision": "V1-T1748645613333257" } ], "dpuStatuses": [] } ``` **SDK Code** ```python Example 2 import requests url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane" payload = { "maintenanceMode": False, "rail": 0, "planeRange": { "start": 2, "end": 5 } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example 2 const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"maintenanceMode":false,"rail":0,"planeRange":{"start":2,"end":5}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 2 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane" payload := strings.NewReader("{\n \"maintenanceMode\": false,\n \"rail\": 0,\n \"planeRange\": {\n \"start\": 2,\n \"end\": 5\n }\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example 2 require 'uri' require 'net/http' url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"maintenanceMode\": false,\n \"rail\": 0,\n \"planeRange\": {\n \"start\": 2,\n \"end\": 5\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example 2 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"maintenanceMode\": false,\n \"rail\": 0,\n \"planeRange\": {\n \"start\": 2,\n \"end\": 5\n }\n}") .asString(); ``` ```php Example 2 request('PATCH', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane', [ 'body' => '{ "maintenanceMode": false, "rail": 0, "planeRange": { "start": 2, "end": 5 } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Example 2 using RestSharp; var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"maintenanceMode\": false,\n \"rail\": 0,\n \"planeRange\": {\n \"start\": 2,\n \"end\": 5\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example 2 import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "maintenanceMode": false, "rail": 0, "planeRange": [ "start": 2, "end": 5 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```