Skip to content
Documentation Prelude Collector 1.0.0

Protocols API

Configure and test the collection protocols (gNMI, NETCONF, SNMP, CLI) attached to each device managed by Prelude Collector.

A protocol record describes how the Prelude Collector reaches a specific device — which transport (gNMI, NETCONF, SNMP, or CLI), which port, and which credentials. After this first mention, the rest of this page refers to Prelude Collector as "the collector". A device may carry several protocol records when different parts of its data plane are exposed through different transports. This page covers when you'll use the API, the most common mistakes, and a worked example that exercises both CRUD and the test endpoints. For the full endpoint schema, see the API reference.

When to use this API

  • Attaching transport to a device. A freshly created device cannot be polled until it has at least one protocol record.
  • Rotating credentials. Update the username, password, or port in place; the collector encrypts the password at rest and never echoes it back.
  • Validating credentials before subscribing. The test endpoints let you confirm gNMI/SNMP/NETCONF reachability or run safe CLI show commands before you create a subscription.
  • Pausing collection without losing config. Disabling a protocol stops collection but preserves the configuration so you can re-enable it later.

Common pitfalls

  • Empty password on update. Updating a protocol with an empty or omitted password keeps the existing one. To clear a password, you have to delete and recreate the record.
  • Deleting a protocol used by a subscription. The collector refuses with 409 Conflict. Stop or delete the subscription first.
  • Running CLI configuration commands via test-cli. The endpoint blocks configuration-altering verbs (configure, commit, set, delete, reload, reboot, shutdown, and similar) and caps each request at 20 commands. Use it for read-only show commands only.
  • One protocol type per device. You cannot have two gnmi records on the same device — the API returns 409 Conflict.

Worked example: validate before subscribing

This flow creates a gNMI protocol, runs a quick path test to confirm the device responds, and then is ready to feed a subscription.

# 1. Create the protocol.
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

# 2. Run a one-shot path test against a known YANG path.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"device-id":1,"protocol":"gnmi","paths":["/interfaces/interface/state/counters"]}' \
  https://collector.example.com/api/v1/protocols/test-path

# 3. (CLI alternative) Send a safe show command for a quick sanity
#    check on devices without gNMI.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"device-id":1,"commands":["show version"]}' \
  https://collector.example.com/api/v1/protocols/test-cli

Bruno: 03 Protocols / Create gNMI protocol, 03 Protocols / Test path (gNMI), 03 Protocols / Test CLI command

A non-empty raw-updates array (gNMI/SNMP/NETCONF) or a populated command-outputs entry (CLI) means the device responded correctly and the credentials are good. From here you can build a model and a subscription with confidence.

Reference

Field-level schemas, the exact list of test parameters, and live "Try it" requests are in the Bruno collection.

See also

Filtering by: