Skip to content
Documentation Prelude Collector 1.0.0

Devices API

Manage the inventory of network elements the Prelude Collector knows about — when to use the Devices API, common pitfalls, and an end-to-end onboarding example.

A device is a network element the Prelude Collector should know about — a router, switch, firewall, or optical platform identified by a hostname and a management address. After this first mention, the rest of this page refers to Prelude Collector as "the collector". The Devices API is the inventory layer: every protocol, subscription, snapshot, and health record hangs off a device record. This page covers when to call the API, common mistakes, and a worked onboarding flow. For the full endpoint schema, see the API reference.

When to use this API

  • Onboarding new equipment. Create a device record before you attach any protocol or subscription to it.
  • Bulk import from a CMDB. Script POST /api/v1/devices to keep your inventory in sync with an external source of truth.
  • Decommissioning. Mark a device inactive (or delete it) when it leaves the network so the collector stops attempting to reach it.
  • Targeted queries. Filter the list endpoint by hostname or active state to drive dashboards or audit scripts.

Common pitfalls

  • Hostname uniqueness. Hostnames must be unique across the collector. A 409 Conflict on create or update almost always means the hostname is already taken.
  • Deleting a managed device. Devices owned by an upstream orchestrator may refuse deletion with 409 Conflict. Delete the upstream binding first, then retry.
  • Confusing active with reachability. The active flag is an intent ("the collector should poll this device"), not a status. For real reachability and collection state, use the Health API.
  • Editing the management address while subscriptions are running. A subscription that was started against the old address will reconnect, but expect a transient gap. Plan changes during a maintenance window.

Worked example: onboard a device end to end

This flow creates a device, attaches a gNMI protocol, and starts a subscription against a built-in model.

# 1. Create the device record.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"router-01","management_address":"192.0.2.10","active":true,"netos":"iosxr"}' \
  https://collector.example.com/api/v1/devices
# 201 Created -> {"id":1, ...}

# 2. Attach a gNMI protocol to the new device.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"device_id":1,"type":"gnmi","port":57400,"username":"prelude","password":"<secret>"}' \
  https://collector.example.com/api/v1/protocols

# 3. Start a subscription against the built-in `interface` model.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"device_id":1,"model_name":"interface","interval":60}' \
  https://collector.example.com/api/v1/subscriptions

Bruno: 02 Devices / Create device, 03 Protocols / Create gNMI protocol, 05 Subscriptions / Create subscription

Once the subscription is running, fetch the latest cached entries with the Snapshots API or watch overall device state through the Health API.

Reference

The full set of query parameters, response shapes, and error codes lives in the Bruno collection. Use it to try the list filters or to copy a ready-to-run curl snippet.

See also

Filtering by: