> 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. # Retrieve all DPU Machines GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/dpu Retrieve all DPU Machines for a Site in deterministic DPU Machine ID order. DPU network configuration is not included when listing DPU Machines, please fetch the DPU Machine by ID to get the network configuration. User must have authorization role with `PROVIDER_ADMIN` suffix on the org that owns the Site. Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/dpu-machine/get-all-dpu-machines ## 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 ### Query parameters - `siteId` (string, required) — ID of the Site - `pageNumber` (integer, optional) — Page number for pagination query - `pageSize` (integer, optional) — Page size for pagination query - `orderBy` (enum, optional, default: ID_ASC) — DPU Machine ID ordering - Allowed values: `ID_ASC`, `ID_DESC` ## Response ### 200 OK - `list of DpuMachineSummary` ## 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. ## Types ### DpuMachineSummary A DPU Machine returned by a site-scoped DPU lookup. Network configuration is null unless the endpoint supports and receives an explicit request for it. - `id` (string, required) — ID of the DPU Machine - `infrastructureProviderId` (string, required) — ID of the Infrastructure Provider that owns the host Machine - `siteId` (string, required) — ID of the Site that the host Machine belongs to - `hostMachineId` (string, required) — ID of the host Machine that this DPU is attached to - `dpuAgentVersion` (string, required) — Version of the DPU agent running on the DPU - `bmcInfo` (MachineBMCInfo, required, nullable) — BMC (Baseboard Management Controller) information for the DPU - `dmiData` (MachineDMIData, required, nullable) — DMI (Desktop Management Interface) data reported for the DPU - `interfaces` (list of DpuMachineInterface, required, nullable) — Interfaces reported on the DPU - `softwareComponents` (list of DpuMachineSoftwareComponent, required, nullable) — Software components reported on the DPU - `health` (MachineHealth, required, nullable) — Health information for the DPU - `labels` (map from string to string, required, nullable) — Labels associated with the DPU - `state` (string, required) — Lifecycle state of the DPU - `dpuNetworkConfig` (DpuNetworkConfig, required, nullable) — Network configuration fields exposed by the REST API, or null when not requested or unavailable - `lastRebooted` (datetime, required, nullable) — Last reboot timestamp - `placementInRack` (PlacementInRack, required, nullable) — Physical placement of the DPU Machine within its Rack, when known - `lldpNeighbors` (list of MachineLldpNeighbor, required) — LLDP neighbors observed on the DPU ports, as last reported by the DPU agent. Empty when the DPU has not reported any neighbors. ### NiCoApiErrorData Additional data about the error ### MachineBMCInfo Describes BMC information of a Machine - `ip` (string, optional, nullable) — IPv4 or IPv6 address of the Machine BMC - `mac` (string, optional, nullable) — MAC address of the Machine BMC - `version` (string, optional, nullable) — Version reported by the Machine BMC - `firmwareRevision` (string, optional, nullable) — Firmware revision reported by the Machine BMC ### MachineDMIData Describes DMI data of a Machine - `boardName` (string, optional, nullable) — DMI board name reported by the Machine - `boardSerial` (string, optional, nullable) — DMI board serial number reported by the Machine - `boardVersion` (string, optional, nullable) — DMI board version reported by the Machine - `biosDate` (string, optional, nullable) — DMI BIOS release date reported by the Machine - `biosVersion` (string, optional, nullable) — DMI BIOS version reported by the Machine - `productName` (string, optional, nullable) — DMI product name reported by the Machine - `productSerial` (string, optional, nullable) — DMI product serial number reported by the Machine - `chassisSerial` (string, optional, nullable) — DMI chassis serial number reported by the Machine - `sysVendor` (string, optional, nullable) — DMI system vendor reported by the Machine ### DpuMachineInterface An interface reported on a DPU Machine - `id` (string, optional) — Interface ID - `machineId` (string, optional) — ID of the Machine the interface belongs to - `segmentId` (string, optional) — Network segment ID - `hostname` (string, optional) — Hostname of the interface - `primaryInterface` (boolean, optional) — Whether this is the primary interface - `macAddress` (string, optional) — MAC address of the interface - `address` (list of string, optional) — IP addresses assigned to the interface - `vendor` (string, optional, nullable) — Vendor of the interface - `created` (datetime, optional, nullable) — Timestamp when the interface was first observed - `lastDhcp` (datetime, optional, nullable) — Timestamp of the last DHCP lease for the interface - `isBmc` (boolean, optional) — Whether this interface is a BMC interface ### DpuMachineSoftwareComponent A software component reported on a DPU Machine - `name` (string, optional) — Name of the software component - `version` (string, optional) — Version of the software component - `url` (string, optional) — URL where the software component can be obtained ### MachineHealth Describes results of various Machine health probes and alerts - `source` (string, optional) — Describes how the health report was generated - `observedAt` (string, optional, nullable) — Date/time when health report was generated - `successes` (list of MachineHealthProbeSuccess, optional) — Results from successful health probes for the Machine - `alerts` (list of MachineHealthProbeAlert, optional) — Results from failed health probes for the Machine ### DpuNetworkConfig Network configuration fields exposed for a DPU Machine. Internal-only and sensitive fields from the Core configuration are omitted. - `asn` (uint, required) — Autonomous System Number for BGP routing - `vniDevice` (string, required) — VNI device name - `managedHostConfigVersion` (string, required) — Version of the managed host configuration - `useAdminNetwork` (boolean, required) — Whether to use the admin network - `remoteId` (string, required) — Remote identifier for the managed host - `vpcIsolationBehavior` (string, required) — VPC isolation behavior setting - `statefulAclsEnabled` (boolean, required) — Whether stateful ACLs are enabled - `enableDhcp` (boolean, required) — Whether DHCP is enabled - `isPrimaryDpu` (boolean, required) — Whether this is the primary DPU - `datacenterAsn` (uint, required) — Datacenter Autonomous System Number - `dhcpServers` (list of string, optional) — List of DHCP server IP addresses - `managedHostConfig` (ManagedHostNetworkConfig, optional) — Network configuration applied to the managed host - `adminInterface` (DpuInterfaceConfig, optional) — Admin network interface configuration for the DPU - `tenantInterfaces` (list of DpuInterfaceConfig, optional) — List of tenant interface configurations - `instanceNetworkConfigVersion` (string, optional, nullable) — Version of the instance network configuration - `instanceId` (string, optional, nullable) — ID of the associated instance - `networkVirtualizationType` (string, optional, nullable) — Type of network virtualization - `vpcVni` (uint, optional, nullable) — VPC VNI identifier - `routeServers` (list of string, optional) — List of route server IP addresses - `deprecatedDenyPrefixes` (list of string, optional) — Deprecated list of denied IP prefixes - `dpuNetworkPingerType` (string, optional, nullable) — Type of network pinger to use - `denyPrefixes` (list of string, optional) — List of denied IP prefixes - `siteFabricPrefixes` (list of string, optional) — List of site fabric IP prefixes - `hostInterfaceId` (string, optional, nullable) — ID of the host interface - `minDpuFunctioningLinks` (uint, optional, nullable) — Minimum number of functioning DPU links required - `internetL3Vni` (uint, optional, nullable) — Layer 3 VNI used for internet access - `anycastSitePrefixes` (list of string, optional) — List of anycast site IP prefixes - `tenantHostAsn` (uint, optional, nullable) — Autonomous System Number for the tenant host - `siteGlobalVpcVni` (uint, optional, nullable) — Site-global VPC VNI identifier ### PlacementInRack Physical placement of a Machine within its Rack - `slotNumber` (integer, optional, nullable) — Rack slot the Machine occupies - `trayIndex` (integer, optional, nullable) — Index of the Machine's tray within its slot ### MachineLldpNeighbor Describes an LLDP neighbor observed on one of the Machine NICs - `medInventory` (MachineLldpMedInventory, required, nullable) — LLDP-MED inventory advertised by the neighbor. Always present; null when the neighbor does not advertise one. - `macAddress` (string, optional) — MAC address of the Machine NIC on which the neighbor was observed - `localPort` (string, optional) — Name of the Machine local interface on which the neighbor was observed - `name` (string, optional) — System name advertised by the neighbor - `description` (string, optional) — System description advertised by the neighbor - `ipAddresses` (list of string, optional) — Management addresses advertised by the neighbor - `chassisIdType` (string, optional) — LLDP chassis id subtype advertised by the neighbor (e.g. mac, local) - `chassisIdValue` (string, optional) — LLDP chassis id value advertised by the neighbor - `remotePortType` (string, optional) — LLDP port id subtype advertised by the neighbor (e.g. ifname, mac) - `remotePortValue` (string, optional) — LLDP port id value advertised by the neighbor ### MachineHealthProbeSuccess Describes results of successful Machine health probe - `id` (string, required) — Health probe identifier - `target` (string, optional, nullable) — Specific component targeted by health probe ### MachineHealthProbeAlert Describes results of a failed Machine health probe - `id` (string, required) — Health probe identifier - `message` (string, required) — Details of the failed health probe result - `target` (string, optional, nullable) — Specific component targeted by health probe - `inAlertSince` (datetime, optional, nullable) — Date/time since the alert has been in effect - `tenantMessage` (string, optional, nullable) — Information provided by Tenant, if any - `classifications` (list of string, optional) — Classifications for this alert, category or impact ### ManagedHostNetworkConfig Network configuration for the managed host - `loopbackIp` (string, required) — Loopback IP address - `quarantineState` (ManagedHostQuarantineState, optional) — Quarantine state for the managed host ### DpuInterfaceConfig Interface configuration for DPU networking - `functionType` (string, required) — Function type (e.g. PHYSICAL_FUNCTION, VIRTUAL_FUNCTION) - `vlanId` (uint, required) — VLAN ID - `vni` (uint, required) — VXLAN Network Identifier - `gateway` (string, required) — Gateway IP address - `ip` (string, required) — Interface IP address - `interfacePrefix` (string, required) — Interface name prefix - `prefix` (string, required) — IP prefix for the interface - `fqdn` (string, required) — Fully qualified domain name - `vpcVni` (uint, required) — VPC VXLAN Network Identifier - `isL2Segment` (boolean, required) — Whether the interface is an L2 segment - `virtualFunctionId` (uint, optional, nullable) — Virtual function ID if applicable - `vpcPrefixes` (list of string, optional) — List of VPC IP prefixes - `bootUrl` (string, optional, nullable) — Boot URL for PXE/iPXE boot - `sviIp` (string, optional, nullable) — Switch virtual interface (SVI) IP address - `tenantVrfLoopbackIp` (string, optional, nullable) — Tenant VRF loopback IP address - `vpcPeerPrefixes` (list of string, optional) — List of peered VPC IP prefixes - `vpcPeerVnis` (list of uint, optional) — List of peered VPC VNIs - `mtu` (uint, optional, nullable) — Maximum transmission unit (MTU) for the interface - `networkSecurityGroup` (InterfaceNetworkSecurityGroupConfig, optional) — Network security group configuration resolved on the interface ### MachineLldpMedInventory LLDP-MED inventory advertised by an LLDP neighbor (e.g. a BlueField DPU) - `serial` (string, optional, nullable) — Serial number advertised by the neighbor - `manufacturer` (string, optional, nullable) — Manufacturer advertised by the neighbor - `model` (string, optional, nullable) — Model advertised by the neighbor ### ManagedHostQuarantineState Quarantine state for the managed host - `mode` (string, required) — Quarantine mode - `reason` (string, optional, nullable) — Reason for quarantine ### InterfaceNetworkSecurityGroupConfig Network security group configuration resolved on a DPU interface - `id` (string, required) — ID of the Network Security Group - `version` (string, required) — Version of the Network Security Group - `source` (string, required) — Source of the Network Security Group configuration - `rules` (list of ResolvedNetworkSecurityGroupRule, optional) — Resolved rules for the Network Security Group ### ResolvedNetworkSecurityGroupRule A network security group rule with its source and destination prefixes resolved - `rule` (NetworkSecurityGroupRule, optional) — The underlying Network Security Group rule - `srcPrefixes` (list of string, optional) — Resolved source IP prefixes for the rule - `dstPrefixes` (list of string, optional) — Resolved destination IP prefixes for the rule ### NetworkSecurityGroupRule A Network Security Group rule matching either IPv4 or IPv6 traffic. Each rule must use the same IP version for its source and destination prefixes. A group can contain both IPv4 and IPv6 rules. - `direction` (enum, required) — Traffic direction the rule applies to - Allowed values: `INGRESS`, `EGRESS` - `protocol` (enum, required) — Network protocol matched by the rule. ICMP requires IPv4 prefixes; ICMP6 requires IPv6 prefixes. TCP, UDP, and ANY support either IP version. - Allowed values: `TCP`, `UDP`, `ICMP`, `ICMP6`, `ANY` - `action` (enum, required) — Action applied when traffic matches the rule - Allowed values: `PERMIT`, `DENY` - `sourcePrefix` (string, required) — Source IPv4 or IPv6 CIDR prefix matched by the rule. Must use the same IP version as destinationPrefix. - `destinationPrefix` (string, required) — Destination IPv4 or IPv6 CIDR prefix matched by the rule. Must use the same IP version as sourcePrefix. - `name` (string, optional, nullable) — Name of the Network Security Group rule - `sourcePortRange` (string, optional, nullable) — Source port or port range matched by the rule - `destinationPortRange` (string, optional, nullable) — Destination port or port range matched by the rule - `priority` (integer, optional) — Rule priority used to order evaluation ## Examples **Response** ```json [ { "id": "string", "infrastructureProviderId": "string", "siteId": "string", "hostMachineId": "string", "dpuAgentVersion": "string", "bmcInfo": { "ip": "2001:db8::5", "mac": "C8:4B:D6:7A:C9:8A", "version": "1", "firmwareRevision": "6.00" }, "dmiData": { "boardName": "7Z23CTOLWB", "boardSerial": ".C1KS2CS002G.", "boardVersion": "06", "biosDate": "03/30/2023", "biosVersion": "U8E122J-1.51", "productSerial": "J1050ACR", "chassisSerial": "J1050ACR" }, "interfaces": [ { "id": "string", "machineId": "string", "segmentId": "string", "hostname": "string", "primaryInterface": true, "macAddress": "string", "address": [ "string" ], "vendor": "string", "created": "2024-01-15T09:30:00Z", "lastDhcp": "2024-01-15T09:30:00Z", "isBmc": true } ], "softwareComponents": [ { "name": "string", "version": "string", "url": "string" } ], "health": { "source": "aggregate-host-health", "observedAt": null, "successes": [ { "id": "BgpDaemonEnabled", "target": null }, { "id": "BgpStats", "target": null }, { "id": "DhcpServer", "target": null }, { "id": "DpuDiskUtilizationCheck", "target": null }, { "id": "FanSpeed", "target": "System Board Fan1A" }, { "id": "PowerSupply", "target": "PS1 Status" }, { "id": "Temperature", "target": "CPU1 Temp" }, { "id": "Temperature", "target": "System Board Exhaust Temp" }, { "id": "Voltage", "target": "CPU1 1P8 PG" } ], "alerts": [ { "id": "FailedValidationTest", "message": "Failed validation test:\nName:DcgmFullShort\nCommand:dcgmi\nArgs:diag -r 2", "target": "DcgmFullShort", "inAlertSince": null, "tenantMessage": null, "classifications": [ "PreventAllocations" ] } ] }, "labels": {}, "state": "string", "dpuNetworkConfig": { "asn": 1, "vniDevice": "string", "managedHostConfigVersion": "string", "useAdminNetwork": true, "remoteId": "string", "vpcIsolationBehavior": "string", "statefulAclsEnabled": true, "enableDhcp": true, "isPrimaryDpu": true, "datacenterAsn": 1, "dhcpServers": [ "string" ], "managedHostConfig": { "loopbackIp": "string", "quarantineState": { "mode": "string", "reason": "string" } }, "adminInterface": { "functionType": "string", "vlanId": 1, "vni": 1, "gateway": "string", "ip": "string", "interfacePrefix": "string", "prefix": "string", "fqdn": "string", "vpcVni": 1, "isL2Segment": true, "virtualFunctionId": 1, "vpcPrefixes": [ "string" ], "bootUrl": "string", "sviIp": "string", "tenantVrfLoopbackIp": "string", "vpcPeerPrefixes": [ "string" ], "vpcPeerVnis": [ 1 ], "mtu": 1, "networkSecurityGroup": { "id": "string", "version": "string", "source": "string", "rules": [ { "rule": { "direction": "INGRESS", "protocol": "TCP", "action": "PERMIT", "sourcePrefix": "10.5.44.0/24", "destinationPrefix": "10.5.44.0/24", "name": "string", "sourcePortRange": "80-81", "destinationPortRange": "80-81", "priority": 1 }, "srcPrefixes": [ "string" ], "dstPrefixes": [ "string" ] } ] } }, "tenantInterfaces": [ { "functionType": "string", "vlanId": 1, "vni": 1, "gateway": "string", "ip": "string", "interfacePrefix": "string", "prefix": "string", "fqdn": "string", "vpcVni": 1, "isL2Segment": true, "virtualFunctionId": 1, "vpcPrefixes": [ "string" ], "bootUrl": "string", "sviIp": "string", "tenantVrfLoopbackIp": "string", "vpcPeerPrefixes": [ "string" ], "vpcPeerVnis": [ 1 ], "mtu": 1, "networkSecurityGroup": { "id": "string", "version": "string", "source": "string", "rules": [ { "rule": { "direction": "INGRESS", "protocol": "TCP", "action": "PERMIT", "sourcePrefix": "10.5.44.0/24", "destinationPrefix": "10.5.44.0/24", "name": "string", "sourcePortRange": "80-81", "destinationPortRange": "80-81", "priority": 1 }, "srcPrefixes": [ "string" ], "dstPrefixes": [ "string" ] } ] } } ], "instanceNetworkConfigVersion": "string", "instanceId": "string", "networkVirtualizationType": "string", "vpcVni": 1, "routeServers": [ "string" ], "deprecatedDenyPrefixes": [ "string" ], "dpuNetworkPingerType": "string", "denyPrefixes": [ "string" ], "siteFabricPrefixes": [ "string" ], "hostInterfaceId": "string", "minDpuFunctioningLinks": 1, "internetL3Vni": 1, "anycastSitePrefixes": [ "string" ], "tenantHostAsn": 1, "siteGlobalVpcVni": 1 }, "lastRebooted": "2024-01-15T09:30:00Z", "placementInRack": { "slotNumber": 1, "trayIndex": 0 }, "lldpNeighbors": [ { "medInventory": { "serial": "SN0000000002", "manufacturer": "https://www.mellanox.com", "model": "BlueField-3 DPU" }, "macAddress": "string", "localPort": "string", "name": "string", "description": "string", "ipAddresses": [ "string" ], "chassisIdType": "string", "chassisIdValue": "string", "remotePortType": "string", "remotePortValue": "string" } ] } ] ``` **SDK Code** ```python import requests url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu" querystring = {"pageSize":"20","siteId":"siteId"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/dpu?pageSize=20&siteId=siteId")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```