Networking NVIDIA UFM Enterprise REST API Guide
Networking 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 - OK

      • Description: Version is successfully returned

      • Content: 

        { "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 - OK

      • Description: List of managed domains is successfully returned

      • Content:

        {
  "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 - 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/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 - OK

      • Description: 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 - 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},
      "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 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:
    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 - 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: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 - 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: 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 - 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"
}

  • 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 - 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/stats

  • Responses:

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


Last updated: