Skip to content
Documentation Prelude Collector 1.0.0

Subscriptions API

Bind a device to a model and drive continuous telemetry collection in Prelude Collector — when to use the API, common pitfalls, and a worked example.

A subscription binds one device to one model and drives continuous collection on a fixed interval. After this first mention, the rest of this page refers to Prelude Collector as "the collector". A subscription is the "this device is being collected right now" unit — enabling it starts a worker, disabling it stops one. This page covers when to call the API, common mistakes, and a worked example that walks through the lifecycle. For the full endpoint schema, see the API reference.

When to use this API

  • Starting collection on a newly onboarded device. Once a device has a working protocol and a model, a subscription is what actually pulls data.
  • Tuning collection frequency. Update the interval to balance freshness against device CPU and network load.
  • Pausing without losing config. Disable a subscription to stop the worker while keeping the binding intact, then re-enable it later.
  • Auditing what is being collected. The list endpoint, filtered by status, gives you a quick view of every active subscription.

Common pitfalls

  • Duplicate subscriptions. A device can have only one subscription per model — repeats return 409 Conflict. To collect the same model under different settings, use a different model.
  • Missing protocol mapping. A subscription against a model whose mappings do not cover the device's NetOS will report errors. Validate with the test endpoint on the Models API before subscribing.
  • Picking too short an interval. Sub-15-second intervals are technically allowed but stress some platforms. Start at 60 s and reduce only after measuring.
  • Deleting an active subscription. The API may refuse with 409 Conflict if the subscription is currently active — disable it first, then delete.

Worked example: subscribe, observe, retune

# 1. Create a 60-second subscription.
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
# 201 Created -> {"id":42, "status":"stopped", ...}

# 2. List subscriptions filtered to the device, confirm status.
curl -H "Authorization: Bearer <your-api-token>" \
  "https://collector.example.com/api/v1/subscriptions?device_id=1&status=started"

# 3. Increase the interval to reduce device load.
curl -X PUT -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"interval":120}' \
  https://collector.example.com/api/v1/subscriptions/42

Bruno: 05 Subscriptions / Create subscription, 05 Subscriptions / List subscriptions, 05 Subscriptions / Update subscription

To verify data is actually flowing, fetch the latest cached entries with the Snapshots API or watch overall state through the Health API.

Reference

The query filters, every status value, and the precise validation rules are documented in the Bruno collection.

See also

Filtering by: