REST API - Manage Device Roles, Groups, and Administrative State

Use the Network Model REST API to read devices and update metadata for devices that already exist in NVIDIA Minerva. This page covers only these operations:

• List the devices currently registered in the network model or retrieve one device.

• Assign or change a device role.

• Add a device to an existing group or move it to another existing group.

• Set a device's administrative state to Enabled or Maintenance.

This page does not cover device discovery, device or group creation, interface roles, topology links, arbitrary graph queries, schema retrieval, or NOS field mappings.

For the equivalent UI workflow, see Assign Device Roles and Groups.

Before You Begin

You need:

• The NVIDIA Minerva platform URL.

• An API key, if API authentication is enabled for your deployment.

• The exact device_name of an existing device.

• An existing group before you assign a device to it.

The base endpoint is:

https://<platform-host>/minerva/api/v2/network

Include these headers with each request:

--header "Content-Type: application/json" \
--header "X-Api-Key: <api-key>"

Read Devices from the Current Network Model

List All Registered Devices

Use the device-list endpoint to retrieve the devices currently registered in the network model:

GET /minerva/api/get_model_devices

curl --request GET \
  --url "https://<platform-host>/minerva/api/get_model_devices" \
  --header "X-Api-Key: <api-key>"

The response contains a devices array. The following abbreviated example shows common properties:

{
  "success": true,
  "devices": [
    {
      "device_name": "leaf01",
      "mgmt_ipv4": "10.0.0.11",
      "role": "leaf",
      "deviceAdminState": "ENABLED"
    }
  ]
}

The properties on each device reflect the metadata currently stored in the network model, so additional properties can be present. This endpoint returns the complete registered-device list in one response and does not paginate; plan for response size accordingly in large deployments.

Do not use this endpoint as a complete group-membership inventory. Review group membership on the Devices or Groups tab under Topology > Provision > MetaData.

Retrieve One Device

Use the device name or management IP address to retrieve one device:

GET /minerva/api/v2/network/{device_name-or-management-IP}

curl --request GET \
  --url "https://<platform-host>/minerva/api/v2/network/leaf01" \
  --header "X-Api-Key: <api-key>"

The response uses the same success and devices fields. A matching identifier normally returns one device in the array. If no device matches, the request succeeds with an empty devices array rather than returning HTTP 404.

Assign or Change a Device Role

Send a sparse device update. A device has one role value; assigning a different role replaces the current value.

POST /minerva/api/v2/network

{
  "header": {
    "request_type": "INGESTION",
    "timestamp": "2026-07-22T00:00:00Z",
    "description": "Update device role"
  },
  "topology": [
    {
      "entity_type": "device",
      "device_name": "leaf01",
      "entity": {
        "role": "leaf"
      }
    }
  ]
}

Use the current time for timestamp. Role names are strings; common reference-architecture values include leaf, spine, and super_spine.

Example request:

curl --request POST \
  --url "https://<platform-host>/minerva/api/v2/network" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: <api-key>" \
  --data @role-update.json

Only fields present in the request are updated. Other device properties remain unchanged. This operation is an upsert, however: an unknown or misspelled device_name can create an incomplete device record. Confirm the identifier before sending the request.

Add Devices to a Group

Group membership is a relationship update. The devices and group must already exist.

POST /minerva/api/v2/network

{
  "header": {
    "request_type": "INTENT",
    "timestamp": "2026-07-22T00:00:00Z",
    "description": "Add devices to group"
  },
  "intent": {
    "GROUPDEVICEHIERARCHY": {
      "link": [
        {
          "groupName": "Pod-0",
          "devices": [
            "leaf01",
            "leaf02"
          ]
        }
      ]
    }
  }
}

The devices array accepts one or more existing device names. A link operation adds the supplied relationship; it does not remove other direct group relationships.

Do not use locations.groups to assign membership. That structure creates or updates group data but does not create the group-to-device relationship.

Move a Device to Another Group

To replace a device's direct group membership, unlink it and link it to the target group in the same request:

{
  "header": {
    "request_type": "INTENT",
    "timestamp": "2026-07-22T00:00:00Z",
    "description": "Move device to another group"
  },
  "intent": {
    "GROUPDEVICEHIERARCHY": {
      "unlink": {
        "devices": [
          "leaf01"
        ]
      },
      "link": [
        {
          "groupName": "Pod-1",
          "devices": [
            "leaf01"
          ]
        }
      ]
    }
  }
}

Important: unlink is not scoped to one group. It removes all direct group-to-device relationships for every listed device. Include every intended replacement link in the same request.

Set a Device's Administrative State

The REST request changes the device's administrative state through the status.admin_state field. The supported values are case-sensitive:

Send the update to the device-specific endpoint. The identifier can be the device name or management IP address.

PUT /minerva/api/v2/network/{device_name-or-management-IP}

For example, place leaf01 into maintenance:

{
  "status": {
    "admin_state": "MAINTENANCE"
  }
}

curl --request PUT \
  --url "https://<platform-host>/minerva/api/v2/network/leaf01" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: <api-key>" \
  --data '{"status":{"admin_state":"MAINTENANCE"}}'

The device-specific endpoint changes status only. Use the POST operations above for roles and group membership.

Check the Result

A successful POST or PUT response has this form:

{
  "success": true,
  "code": "0",
  "message": "processed: 1 entities"
}

This response confirms that NVIDIA Minerva accepted the request. Network-model changes can take a short time to appear. For group requests, acceptance does not guarantee that every supplied name matched an existing entity.

After propagation, use the single-device GET described above and review the role and administrative state in the response. Review group membership on the Devices or Groups tab under Topology > Provision > MetaData.

Last updated: October 20, 2026