> 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 NVLink Domains

GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/domain/nvlink

Retrieve NVLink Domains for a Flow-enabled Site. Requires an Infrastructure Provider and the PROVIDER_ADMIN role. Set includeComponents=true to include components.

Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/domain/get-all-nvlink-domain

## Authentication

- `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<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

- `includeComponents` (boolean, optional, default: false) — Include component details in the response.
- `siteId` (string, required) — ID of the Site
- `name` (list of string, optional) — Filter by Domain name. Repeated values are ORed.
- `pageNumber` (integer, optional) — Page number
- `pageSize` (integer, optional, default: 20) — Number of results per page
- `orderBy` (enum, optional, default: NAME_ASC) — Order by name; immutable Rack UUID ascending breaks ties.
  - Allowed values: `NAME_ASC`, `NAME_DESC`

## Response

### 200

OK

- `list of NVLinkDomain`

## 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.

### 412 Precondition Failed 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.

### 504 Gateway Timeout Error

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.

- `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

### NVLinkDomain

NVLink Domain inventory and its components.

- `id` (string, required) — Case-sensitive Domain external ID, equal to its rack group ID.
- `rackGroupId` (string, required) — Rack group ID, identical to id.
- `nmxcClusterId` (string, required, nullable) — NMX-C cluster UUID observed on the group's switches. Null when no valid observation is available. Conflicting observations are logged and preserve the last valid cluster without interrupting inventory sync.
- `name` (string, required) — Domain display name. Empty for newly inventory-created Domains; inventory sync preserves existing names.
- `topology` (string, required, nullable) — Common member-rack profile ID without the qualified vendor and optional _NO_POWERSHELF suffix. Null when unavailable, unrecognized, or inconsistent across member racks.
- `operationStatus` (string, required) — Operability phase aggregated across member racks, not the Core lifecycle state.
- `components` (list of RackComponent, required, nullable) — Components belonging to this Domain. Null when includeComponents is false; an empty array when requested but none are known.

### NiCoApiErrorData

Additional data about the error

### RackComponent

A component within a Rack (e.g. compute node, switch, PDU)

- `health` (AggregateHealth, required, nullable) — Latest Core aggregate health snapshot synchronized by Flow. Null when Core reports no aggregate health, including before the first successful inventory sync.
- `id` (string, optional) — Component ID
- `rackId` (string, optional) — ID of the Rack this component belongs to
- `type` (string, optional) — Type of the component (e.g. Compute, NVSwitch, PowerShelf)
- `name` (string, optional) — Name of the component
- `serialNumber` (string, optional) — Serial number of the component
- `manufacturer` (string, optional) — Manufacturer of the component
- `model` (string, optional) — Model of the component
- `description` (string, optional) — Description of the component (JSON string)
- `firmwareVersion` (string, optional) — Firmware version of the component
- `slotId` (integer, optional) — Slot ID of the component within the rack
- `trayIdx` (integer, optional) — Tray index of the component
- `hostId` (integer, optional) — Host ID of the component
- `bmcs` (list of BMCInfo, optional) — BMC (Baseboard Management Controller) entries for the component
- `powerState` (string, optional) — Current power state of the component
- `operationStatus` (enum, optional) — Flow-derived operability phase of the component
  - Allowed values: `Unknown`, `Initializing`, `Ready`, `InUse`, `Error`, `Deleting`
- `leakStatus` (enum, optional) — Whether the component is considered leaking coolant
  - Allowed values: `Unknown`, `NoLeak`, `Leaking`
- `leakHandlingStatus` (enum, optional) — Flow's leakage-handling status. Unknown means Flow could not determine the status; None means no supported handling task exists; ShuttingDown means a forced-shutdown task is waiting, pending, or running; Down means it completed; and Failed means the latest supported handling task failed or was terminated. Down describes handling progress, not the component's current power state.
  - Allowed values: `Unknown`, `None`, `ShuttingDown`, `Down`, `Failed`

### AggregateHealth

Describes an aggregate hardware health report and its probe results and alerts

- `source` (string, required) — Describes how the health report was generated
- `observedAt` (datetime, required, nullable) — Date/time when health report was generated
- `successes` (list of HealthProbeSuccess, required) — Results from successful health probes for the resource
- `alerts` (list of HealthProbeAlert, required) — Results from failed health probes for the resource

### BMCInfo

BMC (Baseboard Management Controller) information

- `type` (string, optional) — BMC type (e.g. BmcTypeHost, BmcTypeDpu)
- `macAddress` (string, optional) — MAC address of the BMC
- `ipAddress` (string, optional) — IP address of the BMC

### HealthProbeSuccess

Describes a successful health probe result

- `id` (string, required) — Health probe identifier
- `target` (string, required, nullable) — Specific component targeted by health probe

### HealthProbeAlert

Describes a failed health probe result

- `id` (string, required) — Health probe identifier
- `target` (string, required, nullable) — Specific component targeted by health probe
- `inAlertSince` (datetime, required, nullable) — Date/time since the alert has been in effect
- `message` (string, required) — Details of the failed health probe result
- `tenantMessage` (string, required, nullable) — Information provided by Tenant, if any
- `classifications` (list of string, required) — Classifications for this alert, category or impact

## Examples

**Request**

```json
{}
```

**Response**

```json
[
  {
    "id": "group-42",
    "rackGroupId": "group-42",
    "nmxcClusterId": "a3f1c9d2-7b4e-4f8a-9c3d-2e5b7f9a1c6d",
    "name": "NVLink Domain Alpha",
    "topology": "GB300_NVL96R2_C4G8",
    "operationStatus": "Ready",
    "components": [
      {
        "health": {
          "source": "aggregate-host-health",
          "observedAt": "2024-06-10T12:00:00Z",
          "successes": [
            {
              "id": "FanSpeed",
              "target": "System Board Fan1A"
            },
            {
              "id": "PowerSupply",
              "target": "PS1 Status"
            }
          ],
          "alerts": [
            {
              "id": "FailedValidationTest",
              "target": "DcgmFullShort",
              "inAlertSince": "2024-06-09T08:30:00Z",
              "message": "Failed validation test",
              "tenantMessage": null,
              "classifications": [
                "PreventAllocations"
              ]
            }
          ]
        },
        "id": "comp-1001",
        "rackId": "rack-21",
        "type": "NVSwitch",
        "name": "NVSwitch-21A",
        "serialNumber": "SN1234567890",
        "manufacturer": "NVIDIA",
        "model": "NVSwitch-X2",
        "description": "{\"ports\": 36, \"speed\": \"200Gbps\"}",
        "firmwareVersion": "v1.4.3",
        "slotId": 3,
        "trayIdx": 1,
        "hostId": 101,
        "bmcs": [
          {
            "type": "BmcTypeHost",
            "macAddress": "00:1A:2B:3C:4D:5E",
            "ipAddress": "192.168.10.21"
          }
        ],
        "powerState": "On",
        "operationStatus": "Ready",
        "leakStatus": "NoLeak",
        "leakHandlingStatus": "None"
      }
    ]
  }
]
```

**SDK Code**

```python
import requests

url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink"

querystring = {"siteId":"siteId"}

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId';
const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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
require 'uri'
require 'net/http'

url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/domain/nvlink?siteId=siteId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] 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/domain/nvlink?siteId=siteId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
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()
```