NVLink REST API - NVIDIA Docs

The REST API is grouped into the following categories:

App REST APIs: General plugin information
Managed Domains APIs: Managing domain connections
Inventory APIs: Querying hardware and configuration details

App REST API

Get Version

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

Responses:

Status: 200 - OK

Description: Version is successfully returned

Content:

Copy
Copied!

            
            { "version": "0.2.9" }

Managed Domains REST APIs

Get Managed Domains

Description: Get a list of managed domains
URL: GET /ufmRestV2/plugin/nmxaggr/v1/managed_domains

Responses:

200 - OK

Description: List of managed domains is successfully returned

Content:

Copy
Copied!

            
            {
  "managed_domains" : [
    {
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "host" : "nvlink-01",
      "controller_port" : 9370,
      "telemetry_port" : 9351
    },
    ...
  ]
}

Add Managed Domains

Description: Add one or more new managed domains
URL: POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/add

Request Body:

Parameter	Type	Description	Required	Possible values	Default Value
`host`	string	Hostname or IP of the switch running NMX Controller. Both hostname and IP can contain range expressions	true		—
`controller_port`	integer	Port number of NMX Controller gRPC API server	false		9370
`telemetry_port`	integer	Port number of NMX Telemetry gRPC API server	false		9351

Copy
Copied!

            
            [
	{"host" : "10.245.16.133", "controller_port" : 6901, "telemetry_port" : 9351},
   	{"host" : "10.245.[16,17].[134-137]"},
   	{"host" : "nvlink-[001-32]", "telemetry_port" : 9352}
]

Responses:

Status: 200 - OK

Description: Operation is performed. The response body contains a list of operation statuses for each domain in a request

Content:

Parameter	Type	Description
`host`	string	A hostname or an IP of a domain
`success`	boolean	Whether an operation has succeeded for this domain or not
`reason`	string	A reason for an operation failure

Copy
Copied!

            
            [
	{"host" : "nvlink-001", "success" : true, "reason" : ""},
    {"host" : "nvlink-002", "success" : false, "reason" : "already managed"},
    {"host" : "nvlink-003", "success" : false, "reason" : "unreachable"}
]

Remove Managed Domains

Description: Remove one or more existing managed domains
URL:POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/remove

Request Body:

Parameter	Type	Description	Required	Possible values	Default Value
`host`	string	Hostname or IP of the switch running NMX Controller. Both hostname and IP can contain range expressions	true		—

Copy
Copied!

            
            [
	{"host" : "10.245.16.133"},
    {"host" : "10.245.[16,17].[134-137]"},
    {"host" : "nvlink-[001-32]"}
]

Responses:

Status: 200 - OK

Description: Operation is performed. The response body contains a list of operation statuses for each domain in a request

Content:

Parameter	Type	Description
`host`	string	A hostname or an IP of a domain
`success`	boolean	Whether an operation has succeeded for this domain or not
`reason`	string	A reason for an operation failure

Copy
Copied!

            
            [
	{"host" : "nvlink-001", "success" : true, "reason" : ""},
    {"host" : "nvlink-002", "success" : false, "reason" : "isn't managed"}
]

Inventory REST APIs

Get Domains

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

Parameters:

Parameter	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only one domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	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`	string	Filter returned domains by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `degraded` , `unhealthy`, `unreachable`

Responses:

Status: 200 - OK

Description: List of domains is successfully returned

Content:

Copy
Copied!

            
            {
  "domains" : [
    {
      "name" : "locujoko",
      "domain_uuid" : "4b47fa0f-7dbc-474b-b521-fc3ffc6dc7df",
      "controller_address" : {"host" : "10.245.16.133", "port" : 6901},
      "telemetry_address" : {"host" : "10.245.16.133", "port" : 9351},
      "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" ]
      },
      "telemetry_controller": {
        "app_uuid": "0ae2c6c7-6d90-410f-8e54-d9985eee95a0",
        "app_ver": "3.0.4",
        "host_os_details": "Ubuntu 22.04.5 LTS",
        "components_ver": {
          "clusterminder": "1.1.10",
          "envoy": "1.33.0",
          "gnmi-aggregator": "1.15.0",
          "gnmi_plugin": "gnmi_telemetry_1.3.4-0.tar",
          "nmx-connector": "1.15.0",
          "nvl-telemetry": "1.21.4"
        },
        "capabilities": [
          "nvl telemetry",
          "gnmi aggregation",
          "syslog aggregation",
          "redfish_aggregation"
        ]
      },
      "telemetry_config": {
        "enabled": true,
        "update_period": 60,
        "collect": {
          "device": {
            "gpu": true,
            "switch": true
          },
          "down_ports": false
        },
        "otlp": {
          "counter_set": "",
          "field_set": "",
          "target": "",
          "inbound_queue": 10000
        },
        "remote_write": {
          "counter_set": "",
          "field_set": "",
          "target": "",
          "inbound_queue": 10000
        }
      },
      "health" : "Healthy",
      "state" : "Configured",
      "config_status" : "CONFIG_DONE",
      "controller_health" : "Healthy",
      "telemetry_health": "Healthy",
      "last_updated" : "2025-05-21T13:12:11+03:00"
    },
    ...
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

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

Get Compute Nodes

Description: Get a list of compute nodes
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/compute_nodes

Parameters:

Parameter	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only compute nodes belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	Return only compute nodes 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`	string	Filter returned compute nodes by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `degraded`, `unhealthy`
`is_allocated`	boolean	If true, allocated compute nodes will be returned, otherwise free compute nodes will be returned	false	`?is_allocated=true`

Responses:

Status: 200 - OK

Description: List of compute nodes is successfully returned

Content:

Copy
Copied!

            
            {
  "compute_nodes": [
    {
      "domain_name": "haxazeko",
      "domain_uuid": "3bc0511c-6ac2-428b-b546-843d3cad0f3f",
      "name": "haxazeko.chas-01.slot-03",
      "location": {
        "chassis_id": 1,
        "slot_id": 3
      },
      "location_info": {
        "chassis_serial_number": "27XYZ27000001",
        "tray_index": 2
      },
      "partition_ids": [
        "0x7ffe"
      ],
      "last_updated": "2025-10-21T21:09:28+03:00",
      "num_gpus": 4,
      "health": "Healthy"
    },
    .
    .
    .
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

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

Get Switch Nodes

Description: Get a list of switch nodes
URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/switch_nodes

Parameters:

Parameter	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only switch nodes belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	Return only switch nodes 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`	string	Filter returned switch nodes by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `degraded`, `unhealthy`

Responses:

Status: 200 - OK

Description: List of switch nodes is successfully returned

Content:

Copy
Copied!

            
            {
  "switch_nodes": [
    {
      "domain_name": "cymovewe",
      "domain_uuid": "d1d652ea-119e-4ffb-9f22-7023deba5c42",
      "name": "cymovewe.chas-01.slot-08",
      "location": {
        "chassis_id": 1,
        "slot_id": 8
      },
      "location_info": {
        "chassis_serial_number": "27XYZ27000001",
        "tray_index": 0
      },
      "partition_ids": [],
      "last_updated": "2025-10-21T21:13:59+03:00",
      "num_switches": 2,
      "health": "Healthy"
    },
    .
    .
    .
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

            
            {
  "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	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only GPUs belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	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`	string	Filter returned GPUs by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `degraded`, `unhealthy`

Responses:

Status: 200 - OK

Description: List of GPUs is successfully returned

Content:

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
      ]
    },
    .
    .
    .
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

            
            {
  "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	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only switches belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	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`	string	Filter returned switches by a value of the "health" property	false	`?health=unhealthy`	`healthy`, `degraded`, `unhealthy`

Responses:

Status: 200 - OK

Description: List of switches is successfully returned

Content:

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"
    },
    ...
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content

Copy
Copied!

            
            {
  "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	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only ports belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	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`

Responses:

Status: 200 - OK

Description: List of ports is successfully returned

Content:

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

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

            
            {
  "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	Type	Description	Required	Example	Possible Values
`domain_uuid`	string	Return only links belonging to the domain with this UUID	false	`?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb`
`domain_uuids`	list of strings	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`

Responses:

Status: 200 - OK

Description: List of links is successfully returned

Content

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"
    },
    ...
  ]
}

Status: 404 - Not Found

Description: The domain with one of specified UUIDs could not be found

Content:

Copy
Copied!

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

Statistics REST APIs

Get Stats

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

Responses:

Status: 200 - OK

Description: Statistics are successfully returned

Content:

Copy
Copied!

            
            {
  "stats": {
    "domains": {
      "total": 5,
      "healthy": 3,
      "degraded": 2,
      "unhealthy": 0,
      "unreachable": 0
    },
    "compute_nodes": {
      "total": 45,
      "healthy": 43,
      "degraded": 0,
      "unhealthy": 2
    },
    "switch_nodes": {
      "total": 45,
      "healthy": 45,
      "degraded": 0,
      "unhealthy": 0
    },
    "gpus": {
      "total": 180,
      "healthy": 178,
      "degraded": 0,
      "unhealthy": 2
    },
    "switches": {
      "total": 90,
      "healthy": 90,
      "degraded": 0,
      "unhealthy": 0
    },
    "compute_node_allocations": {
      "total": 45,
      "allocated": 38,
      "free": 7
    },
    "gpu_allocations": {
      "total": 180,
      "allocated": 152,
      "free": 28
    },
    "last_updated": "2025-10-24T17:10:53+03:00"
}

On This Page