NVLink REST API
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
Get Version
Description: Gets a version of NVLink Aggregator
URL:
GET /ufmRestV2/plugin/nmxaggr/v1/app/versionResponses:
Status: 200 - OK
Description: Version is successfully returned
Content:
{
"version":"0.2.9"}
Get Managed Domains
Description: Gets a list of managed domains
URL:
GET /ufmRestV2/plugin/nmxaggr/v1/managed_domainsResponses:
200 - OK
Description: List of managed domains is successfully returned
Content:
{
"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/addRequest Body:
[ {
"host":"10.245.16.133","controller_port":6901,"telemetry_port":9351}, {"host":"10.245.16.[134-137]"}, {"host":"nvlink-[001-32]-ch[1,2]","telemetry_port":9352} ]Responses:
Status: 200 - OK
Description: New domains are successfully added to the list of managed domains
Remove Managed Domains
Description: Remove one or more existing managed domains
URL:
POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/removeRequest Body:
[ {
"host":"10.245.16.133"}, {"host":"10.245.16.[134-137]"}, {"host":"nvlink-[001-32]-ch[1,2]"} ]
Responses:
Status: 200 - OK
Description: Domains are successfully removed from the list of managed domains
Get Domains
Description: Gets a list of domains
URL:
GET /ufmRestV2/plugin/nmxaggr/v1/inventory/domainsParameters:
Parameter
In
Description
Required
Example
Possible Values
domain_uuidquery
Return only one domain with this UUID
false
?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—
domain_uuidsquery
Return only domains with UUIDs provided in a comma-separated list
false
?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b—
healthquery
Filter returned domains by a value of the "health" property
false
?health=unhealthyhealthy,unhealthy,unreachableResponses:
Status: 200 - OK
Description: List of domains is successfully returned
Content:
{
"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:
{
"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/gpusParameters:
Parameter
In
Description
Required
Example
Possible Values
domain_uuidquery
Return only GPUs belonging to the domain with this UUID
false
?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—
domain_uuidsquery
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—
healthquery
Filter returned GPUs by a value of the "health" property
false
?health=unhealthyhealthy,unhealthyResponses:
Status: 200 - OK
Description: List of GPUs is successfully returned
Content:
{
"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:
{
"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/switchesParameters:
Parameter
In
Description
Required
Example
Possible Values
domain_uuidquery
Return only switches belonging to the domain with this UUID
false
?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—
domain_uuidsquery
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—
healthquery
Filter returned switches by a value of the "health" property
false
?health=unhealthyhealthy,unhealthyResponses:
Status: 200 - OK
Description: List of switches is successfully returned
Content:
{
"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
{
"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/portsParameters:
Parameter
In
Description
Required
Example
domain_uuidquery
Return only ports belonging to the domain with this UUID
false
?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuidsquery
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-e4e37614b38bResponses:
Status: 200 - OK
Description: List of ports is successfully returned
Content:
{
"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:
{
"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/linksParameters:
Parameter
In
Description
Required
Example
domain_uuidquery
Return only links belonging to the domain with this UUID
false
?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuidsquery
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-e4e37614b38bResponses:
Status: 200 - OK
Description: List of links is successfully returned
Content
{
"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:
{
"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/statsResponses:
Status: 200 - OK
Description: Statistics are successfully returned
Content:
{
"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"} }