Skip to content
Documentation Prelude Collector 1.0.0

Health API

Inspect the health of the Prelude Collector itself, the devices it manages, and the subscriptions it runs — when to use the API, common pitfalls, and a worked example.

The Health API surfaces real-time and historical state for the Prelude Collector, every device it manages, and every subscription it runs. After this first mention, the rest of this page refers to Prelude Collector as "the collector". The endpoints are read-only; they are the right way to power dashboards, alerting probes, and on-call diagnostics. This page covers when to call which endpoint, common mistakes, and a worked example. For the full endpoint schema, see the API reference.

When to use this API

  • Status dashboards. A small loop over GET /api/v1/health feeds an at-a-glance view of the collector and everything it is collecting.
  • Targeted alerting. Use the per-device or per-subscription endpoints to alert only on the specific objects you care about.
  • Post-incident review. The history endpoint exposes up to 100 recent snapshots and can be filtered by device for retrospective analysis.
  • Distinguishing "not configured" from "broken". Health responds with 503 Service Unavailable when the engine has no data at all — useful as a probe-of-probes.

Common pitfalls

  • Treating Health as the source of truth for inventory. The Health API only reports objects the collector knows about. For inventory, see the Devices API and Subscriptions API.
  • Swallowing 503. A 503 from a Health endpoint means the health engine is not yet ready — usually right after startup, or if no data has been collected yet. Retry with backoff before alerting.
  • Treating Health as a metrics store. Health is a state view, not a TSDB. For numeric metrics over time, use the output backend of your choice (InfluxDB, Prometheus, etc.).
  • Polling at high frequency. The endpoints aggregate state on every call — a 5- to 15-second interval is plenty for dashboards.

Worked example: dashboard plus targeted alert

# 1. System-wide health for a top-level dashboard.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/health

# 2. All-device health to drive a per-device row.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/health/devices

# 3. Drill into a single device that looked unhealthy above.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/health/devices/1

# 4. Pull recent history for that device for incident review.
curl -H "Authorization: Bearer <your-api-token>" \
  "https://collector.example.com/api/v1/health/history?device_id=1"

Bruno: 11 Health / System health, 11 Health / All devices health, 11 Health / Device health, 11 Health / Health history

If a single subscription is the culprit, the GET /api/v1/health/subscriptions/{subscriptionId} endpoint pinpoints the problem and surfaces the timestamp of the last successful collection.

Reference

Status enums, the exact subscription health shape, and the history response variants are exercised in the Bruno collection.

See also

Filtering by: