Outputs API

Outputs are the backends that receive collected telemetry once it has been parsed and transformed. After this first mention, the rest of this page refers to Prelude Collector as "the collector". The collector ships with six built-in output backends — NATS, InfluxDB, Kafka, Prometheus, Webhook, and File — and the Outputs API lets you configure, validate, and monitor each one. This page covers when to call which endpoint, common mistakes, and a worked example that configures, probes, and tests an output end to end. For the full endpoint schema, see the API reference.

When to use this API

• Wiring a new destination. Update the configuration and flip enabled to true. Changes hot-reload, no restart required.
• Validating a configuration before saving. The detect endpoint runs reachability and authentication checks against an explicit config in the request body, so you can fail fast. Omit the body to probe the saved config instead — useful when you want to ask "is the running output still healthy?" without re-supplying secrets.
• Smoke-testing the pipeline. The test-output endpoint injects synthetic ParsedData so you can confirm that downstream consumers receive what you expect — no live device required.
• Diagnosing drops. The metrics endpoint exposes per-backend success and failure counts plus the timestamp of the last failure.

Common pitfalls

• Re-sending masked secrets. GET responses mask secrets with ********. If you copy a config and PUT it back, leave the masked field as ******** (or omit it) — the collector will preserve the existing secret. Sending the literal string ******** as a real token is the most common foot-gun.
• Forgetting required fields per backend. influxdb needs url, org, and bucket; kafka needs brokers; webhook needs url; file needs output-dir. Probing before saving catches this early.
• Confusing enabled with configured. A backend can be configured but disabled (paused) — both flags are reported on the GET response.
• Treating prometheus like a push backend. Prometheus is scraped, not written. Configure it and point your Prometheus server at the exposed endpoint.

Worked example: probe, save, and inject

This flow validates an InfluxDB configuration with the detect endpoint, saves it, and then injects synthetic data to confirm the pipeline is wired correctly.

# 1. Probe the proposed configuration without saving.
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"config":{"url":"http://192.0.2.20:8086","org":"prelude","bucket":"telemetry","token":"<your-influxdb-token>"}}' \
  https://collector.example.com/api/v1/outputs/influxdb/detect
# Expect "all-passed": true before continuing.

# 2. Save the configuration (output is hot-reloaded).
curl -X PUT -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"config":{"url":"http://192.0.2.20:8086","org":"prelude","bucket":"telemetry","token":"<your-influxdb-token>"}}' \
  https://collector.example.com/api/v1/outputs/influxdb

# 3. Inject a synthetic ParsedData entry to verify end-to-end flow.
#    Field names are kebab-case (model-name, device-id, data-hash).
curl -X POST -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '[{
    "device": "router-01",
    "device-id": 1,
    "model-name": "interface",
    "path": "test",
    "key": "test",
    "timestamp": "2024-01-01T12:00:00Z",
    "data-hash": "sha256:test",
    "data": {"in-octets": 100}
  }]' \
  https://collector.example.com/api/v1/outputs/test-output

# 4. Spot-check delivery counters.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/outputs/metrics

Bruno: 08 Outputs / Detect output, 08 Outputs / Update output config, 08 Outputs / Inject test entry, 08 Outputs / Output metrics

If failures keep climbing in step 4, run the detect endpoint against the saved config (omit the request body) to surface the specific check that is failing.

Reference

Per-backend config fields, the full list of probe checks, and the exact metrics shape are in the Bruno collection.

See also

• Outputs overview
• NATS, InfluxDB, Kafka, Prometheus, Webhook, File
• Tutorial: Send data to Grafana
• Concepts: Data flow