NVIDIA UFM Enterprise REST API Guide
NVIDIA UFM Enterprise REST API Guide
Breadcrumbs

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: Gets 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: Gets 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" : "10.245.16.133", "port" : 6901 }, ... ] }

Add Managed Domains

  • Description: Add one or more new managed domains

  • URL: POST /ufmRestV2/plugin/nmxaggr/v1/managed_domains/add

  • Request Body: 

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

  • Responses:Status: 200 - OKDescription: 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/remove

  • Request Body:

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

  • Responses:Status: 200 - OKDescription: Domains are 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: 
    ParameterInDescriptionRequiredExamplePossible Valuesdomain_uuidqueryReturn only one domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—domain_uuidsqueryReturn only domains with UUIDs provided in a comma-separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b—healthqueryFilter returned domains by a value of the "health" propertyfalse?health=unhealthyhealthy, 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}, "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" }, ... ] }

    • 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:
    ParameterInDescriptionRequiredExamplePossible Valuesdomain_uuidqueryReturn only GPUs belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—domain_uuidsqueryReturn only GPUs belonging to domains with UUIDs provided in a comma-separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b—healthqueryFilter returned GPUs by a value of the "health" propertyfalse?health=unhealthyhealthy, 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:ParameterInDescriptionRequiredExamplePossible Valuesdomain_uuidqueryReturn only switches belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bb—domain_uuidsqueryReturn only switches belonging to domains with UUIDs provided in a comma-separated listfalse?domain_uuids=2e469d41-3102-485c-aa8b-58ba3c97f6bb,d7c35619-fa03-4bb7-bce2-e4e37614b38b—healthqueryFilter returned switches by a value of the "health" propertyfalse?health=unhealthyhealthy, 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: ParameterInDescriptionRequiredExampledomain_uuidqueryReturn only ports belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuidsqueryReturn 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"
}

  • Description: Gets a list of links

  • URL: GET /ufmRestV2/plugin/nmxaggr/v1/inventory/links

  • Parameters: ParameterInDescriptionRequiredExampledomain_uuidqueryReturn only links belonging to the domain with this UUIDfalse?domain_uuid=2e469d41-3102-485c-aa8b-58ba3c97f6bbdomain_uuidsqueryReturn 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"
}

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" : 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" } }


Last updated: