NVLink REST API - NVIDIA Docs

App REST API

Get Version

Description: Gets a version of NVLink Aggregator
URL: GET /ufmRestV2/plugin/nmxaggr/v1/app/version

Responses:

Status: 200 - OK (Version is successfully returned)

Response Example:

Copy
Copied!

            
             js { "version": "0.2.9" }

Managed Domains REST APIs

Get Managed Domains

Description: Gets a list of managed domains
URL: GET /ufmRestV2/plugin/nmxaggr/v1/managed_domains
Status Code:
- 200 - OK
  Response Example:

Copy
Copied!

            
            js {
  "managed_domains" : [
    {
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "host" : "10.245.16.133",
      "port" : 6901
    },
    ...
  ]
}

Add Managed Domain

Description: Add a new managed domain
URL: POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/add

Request Body:

Copy
Copied!

            
            js[{"host" : "10.245.16.133", "port" : 6901},
   {"host" : "10.245.16.[134-137]", "port" : 6902},
   {"host" : "nvlink-[001-32]-ch[1,2]", "port" : 6901}]

Status Code:
- 200 - OK (A new domain is successfully added to the list of managed domains)

Remove Managed Domain

Description: Removes an existing managed domain
URL: POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/remove

Request Body:

Copy
Copied!

            
             js[{"host" : "10.245.16.133", "port" : 6901},
    {"host" : "10.245.16.[134-137]", "port" : 6902},
    {"host" : "nvlink-[001-32]-ch[1,2]", "port" : 6901}]

Status Code:
- Status: 200 - OK (a domain is successfully removed from the list of managed domains

Inventory REST APIs

Get Domains

Description: Gets a list of domains
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/domains

Parameters:

Parameter	In	Description	Required	Example	Possible Values
`domain_uuid`	query	Return only one domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`	—
`domain_uuids`	query	Return only domains with UUIDs provided in a comma-separated list	false	`?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b`	—
`health`	query	Filter returned domains by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `unhealthy`, `unreachable`

Status Code:

Status: 200 - OK (List of domains is successfully returned)

Example Response:

Copy
Copied!

            
            {
  "domains" : [
    {
      "name" : "locujoko",
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "controller_address" : {"host" : "10.245.16.133", "port" : 6901},
      "counts" : {
        "num_gpus" : 36,
        "num_switches" : 18,
        "num_ports" : 1296,
        "num_links" : 648
      },
      "properties" : {
        "max_compute_nodes" : 9,
        "max_compute_nodes_per_chassis" : 9,
        "max_gpus_per_compute_node" : 4,
        "max_gpu_nvlinks" : 18,
        "max_switch_nodes" : 9,
        "max_switch_nodes_per_chassis" : 9,
        "max_switches_per_switch_node" : 2,
        "max_switch_nvlinks" : 36,
        "max_ports" : 1296,
        "max_partitions" : 36,
        "min_gpus_per_partition" : 0,
        "max_alids" : 2,
        "max_multicast_groups" : 1024,
        "line_rate" : 25000
      },
      "controller" : {
        "app_uuid" : "0eb9b4a7-62fc-4ce7-b51a-50b6fa9f1d50",
        "app_ver" : "1.1.0_2025-05-09_21-04",
        "host_os_details" : "Ubuntu 22.04.5 LTS",
        "components_ver" : {
          "fib" : "1.1.0_2025-05-09_21-04",
          "gfm" : "R570.148",
          "sm" : "2025.03.6"
        },
        "capabilities" : [ "fib", "gfm", "gw-api", "sm" ]
      },
      "health" : "Healthy",
      "state" : "Configured",
      "controller_health" : "Healthy",
      "config_status" : "CONFIG_DONE",
      "last_updated" : "2025-05-21T13:12:11+03:00"
    },
    ...
  ]
}

404 - Not Found (The domain with one of specified UUIDs could not be found)

Example Response:

Copy
Copied!

            
            js {
  "error": "the domain with the uuid '4b47fa0f-7dbc-474b-b521-fc3ffc6dc7da' could not be found"
}

Get GPUs

Description: Gets a list of GPUs
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/gpus

Parameters:

Parameter	In	Description	Required	Example	Possible Values
`domain_uuid`	query	Return only GPUs belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`	—
`domain_uuids`	query	Return only GPUs belonging to domains with UUIDs provided in a comma-separated list	false	`?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b`	—
`health`	query	Filter returned GPUs by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `unhealthy`

Status Codes:

200 - OK (Description: List of GPUs is successfully returned)

Example Response:

Copy
Copied!

            
            {
  "gpus": [
    {
      "domain_name": "locujoko",
      "domain_uuid": "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "domain_controller_address": {
        "host": "10.245.16.133",
        "port": 6901
      },
      "last_updated": "2025-05-21T16:42:14+03:00",
      "name": "locujoko.chas-01.cmp-node-07.gpu-01",
      "location": {
        "chassis_id": 1,
        "slot_id": 16,
        "host_id": 1
      },
      "location_info": {
        "chassis_serial_number": "27XYZ27000001",
        "tray_index": 6
      },
      "description": "GB100 Nvidia Technologies 24",
      "device_uid": "0a48-fc18-c7cb-a43c",
      "system_uid": "0c64-56a8-0d9e-37c7",
      "topology_id": 129,
      "price_id": 10496,
      "num_ports": 18,
      "vendor_id": 713,
      "device_id": 1,
      "partition_ids": [
        32766
      ],
      "health": "Healthy",
      "alids": [
        1048
      ]
    },
    .
    .
    .
  ]
}

404 - Not Found (The domain with one of specified UUIDs could not be found)

Example Response:

Copy
Copied!

            
            js {
  "error": "the domain with the uuid '4b47fa0f-7dbc-474b-b521-fc3ffc6dc7da' could not be found"
}

Get Switches

Description: Gets a list of switches
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/switches

Parameters:

Parameter	In	Description	Required	Example	Possible Values
`domain_uuid`	query	Return only switches belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`	—
`domain_uuids`	query	Return only switches belonging to domains with UUIDs provided in a comma-separated list	false	`?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b`	—
`health`	query	Filter returned switches by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `unhealthy`

Code Status:

200 - OK (List of switches is successfully returned)

Response Example:

Copy
Copied!

            
            {
  "switches" : [
    {
      "domain_name" : "locujoko",
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "domain_controller_address" : {"host" : "10.245.16.133", "port" : 6901},
      "last_updated" : "2025-05-21T16:42:14+03:00",
      "name" : "locujoko.chas-01.swt-node-01.swt-01",
      "location" : {"chassis_id" : 1, "slot_id" : 13, "host_id" : 1},
      "location_info" :
          {"chassis_serial_number" : "27XYZ27000001", "tray_index" : 0},
      "description" : "MF0;mc-gb-nvl-020-001-switch:N5110_LD/U 16",
      "device_uid" : "0000-0002-5133-445a",
      "system_uid" : "0d6d-e7fc-d5da-13b0",
      "topology_id" : 129,
      "price_id" : 54004,
      "num_ports" : 72,
      "vendor_id" : 713,
      "device_id" : 1,
      "partition_ids" : [],
      "hostname" : "mc-gb-nvl-020-001-switch",
      "model" : "N5110_LD",
      "health" : "Healthy"
    },
    ...
  ]
}

404 - Not Found (The domain with one of specified UUIDs could not be found)

Response Example :

Copy
Copied!

            
            js {
  "error": "the domain with the uuid '4b47fa0f-7dbc-474b-b521-fc3ffc6dc7da' could not be found"
}

Get Ports

Description: Gets a list of ports
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/ports

Parameters:

Parameter	In	Description	Required	Example
`domain_uuid`	query	Return only ports belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	query	Return only ports belonging to domains with UUIDs provided in a comma-separated list	false	`?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b`

Status Codes:

200 - OK (Description: List of ports is successfully returned)

Response Example:

Copy
Copied!

            
            {
  "ports" : [
    {
      "domain_name" : "locujoko",
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "domain_controller_address" : {"host" : "10.245.16.133", "port" : 6901},
      "last_updated" : "2025-05-21T17:12:14+03:00",
      "port_uid" : "02e7-7ac6-7738-9e59",
      "device_uid" : "0954-1c38-eb6e-07c0",
      "peer_device_uid" : "0000-0002-2f8a-e90c",
      "system_port_num" : 0,
      "compute_port_num" : 4,
      "subnet_prefix" : "0000-0000-0000-0000",
      "base_lid" : 2123,
      "type" : "GPU",
      "physical_state" : "Link Up",
      "logical_state" : "Active",
      "port_num" : 5,
      "peer_port_num" : 1,
      "cage_num" : 0,
      "cage_split_num" : 0,
      "cage_port_num" : 0,
      "rail" : 0,
      "plane" : 0,
      "link_rate" : 0,
      "partition_ids" : [32766],
      "is_sdn_port" : false,
      "contain_and_drain" : false
    },
    ...
  ]
}

Status: 404 - Not Found (The domain with one of specified UUIDs could not be found)

Response Example:

Copy
Copied!

            
            js {
  "error": "the domain with the uuid '4b47fa0f-7dbc-474b-b521-fc3ffc6dc7da' could not be found"
}

Get Links

Description: Gets a list of links
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/links

Parameters:

Parameter	In	Description	Required	Example
`domain_uuid`	query	Return only links belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	query	Return only links belonging to domains with UUIDs provided in a comma-separated list	false	`?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b`

Status Codes:

200 - OK (List of links is successfully returned)

Response Example:

Copy
Copied!

            
            {
  "links" : [
    {
      "domain_name" : "locujoko",
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "domain_controller_address" : {"host" : "10.245.16.133", "port" : 6901},
      "last_updated" : "2025-05-21T17:12:14+03:00",
      "endpoint_a" : {
        "location" : {"chassis_id" : 1, "slot_id" : 1, "host_id" : 1},
        "device_uid" : "0d32-6108-ad29-dd4c",
        "device_id" : 4,
        "port_num" : 12,
        "cage_num" : 2147483647,
        "cage_split_num" : 2147483647,
        "cage_port_num" : 2147483647
      },
      "endpoint_b" : {
        "location" : {"chassis_id" : 1, "slot_id" : 10, "host_id" : 1},
        "device_uid" : "0000-0002-381b-8cd3",
        "device_id" : 2,
        "port_num" : 1,
        "cage_num" : 2147483647,
        "cage_split_num" : 2147483647,
        "cage_port_num" : 2147483647
      },
      "type" : "GPU",
      "state" : "Active"
    },
    ...
  ]
}

404 - Not Found (The domain with one of specified UUIDs could not be found)

Response Example:

Copy
Copied!

            
            {
  "error": "the domain with the uuid '4b47fa0f-7dbc-474b-b521-fc3ffc6dc7da' could not be found"
}

Get Stats

Description: Get statistics about inventory elements
URL: GET /ufmRestV2/plugin/nmxaggr/v1/stats

Status Code:

Status: 200 - OK (Statistics are successfully returned)

Response Example:

Copy
Copied!

            
            js {
  "stats" : {
    "domains"
        : {"total" : 3, "healthy" : 2, "unhealthy" : 1, "unreachable" : 0},
          "gpus" : {"total" : 108, "healthy" : 106, "unhealthy" : 2},
                   "switches" : {"total" : 54, "healthy" : 49, "unhealthy" : 6},
                                "last_updated" : "2025-05-21T17:12:14+03:00"
  }
}

On This Page