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:
{ "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:
{ "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 - OK
-
Description: Operation is performed. The response body contains a list of operation statuses for each domain in a request
-
Content: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 - OK
-
Description: Operation is performed. The response body contains a list of operation statuses for each domain in a request
-
Content: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 - 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 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 - OK
-
Description: List of compute nodes is successfully returned
-
Content:
{ "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:
{ "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 - OK
-
Description: List of switch nodes is successfully returned
-
Content:
{ "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:
{ "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 - 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/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 - 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/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 - 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/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 - 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" }
-
-
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:
{ "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: