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

App REST API

Get Version

• Description: Get a version of NVLink Aggregator

• URL: GET /ufmRestV2/plugin/nmxaggr/v1/app/version

• Responses:
  Status: 200 - OKDescription: Version is successfully returnedContent:  { "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 - OKDescription: List of managed domains is successfully returnedContent:  { "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: ParameterTypeDescriptionRequiredPossible valuesDefault ValuehoststringHostname or IP of the switch running NMX Controller. Both hostname and IP can contain range expressionstrue—controller_portintegerPort number of NMX Controller gRPC API serverfalse9370telemetry_portintegerPort number of NMX Telemetry gRPC API serverfalse9351

  [
  	{"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 - OKDescription: Operation is performed. The response body contains a list of operation statuses for each domain in a requestContent:ParameterTypeDescriptionhoststringA hostname or an IP of a domainsuccessbooleanWhether an operation has succeeded for this domain or notreasonstringA reason for an operation failure [ {"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:ParameterTypeDescriptionRequiredPossible valuesDefault ValuehoststringHostname or IP of the switch running NMX Controller. Both hostname and IP can contain range expressionstrue—

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

   

• Responses:Status: 200 - OKDescription: Operation is performed. The response body contains a list of operation statuses for each domain in a requestContent:ParameterTypeDescriptionhoststringA hostname or an IP of a domainsuccessbooleanWhether an operation has succeeded for this domain or notreasonstringA reason for an operation failure [ {"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: 
  ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only one domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuidslist of stringsReturn only domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38bhealthstringFilter returned domains by a value of the "health" propertyfalse?health=unhealthyhealthy, degraded , unhealthy, unreachable 

• Responses:

  • Status: 200 - OKDescription: List of domains is successfully returnedContent: { "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 FoundDescription: The domain with one of specified UUIDs could not be foundContent: { "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:
  ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only compute nodes belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only compute nodes belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38bhealthstringFilter returned compute nodes by a value of the "health" propertyfalse?health=unhealthyhealthy, degraded, unhealthyis_allocatedbooleanIf true, allocated compute nodes will be returned, otherwise free compute nodes will be returnedfalse?is_allocated=true

• Responses:

  • Status: 200 - OKDescription: List of compute nodes is successfully returnedContent: { "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 FoundDescription: The domain with one of specified UUIDs could not be foundContent: { "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:
  ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only switch nodes belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only switch nodes belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38bhealthstringFilter returned switch nodes by a value of the "health" propertyfalse?health=unhealthyhealthy, degraded, unhealthy

• Responses:

  • Status: 200 - OKDescription: List of switch nodes is successfully returnedContent: { "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 FoundDescription: The domain with one of specified UUIDs could not be foundContent: { "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:
  ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only GPUs belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only GPUs belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38bhealthstringFilter returned GPUs by a value of the "health" propertyfalse?health=unhealthyhealthy, degraded, unhealthy

• Responses:

  • Status: 200 - OKDescription: List of GPUs is successfully returnedContent: { "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 FoundDescription: The domain with one of specified UUIDs could not be foundContent: { "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:ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only switches belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only switches belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38bhealthstringFilter returned switches by a value of the "health" propertyfalse?health=unhealthyhealthy, degraded, unhealthy

• Responses:Status: 200 - OKDescription: List of switches is successfully returnedContent: { "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/ports

• Parameters: ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only ports belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only ports belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b

• Responses:

  • Status: 200 - OKDescription: List of ports is successfully returnedContent: { "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/links

• Parameters: ParameterTypeDescriptionRequiredExamplePossible Valuesdomain_uuidstringReturn only links belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuids list of stringsReturn only links belonging to domains with UUIDs provided in a comma separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b

• Responses:

  • Status: 200 - OKDescription: List of links is successfully returnedContent { "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"
      }

Statistics REST APIs

Get Stats

• Description: Get statistics about inventory elements

• URL: GET /ufmRestV2/plugin/nmxaggr/v1/stats

• Responses:

  • Status: 200 - OKDescription: Statistics are successfully returnedContent: {   "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" }

  
  

Last updated: January 05, 2026