Type: reference · Imported reference (adopted from the clarity backend developer docs)
The high-level ingestion endpoints. These take a flat JSON payload — an object of tag → numeric value, plus an optional timestamp (epoch ms; defaults to now). Non-numeric values are skipped. A tag_prefix from the ingest config is prepended to tag names when not already present.
Path params {client} and {config} must be valid identifiers (a 24-hex Mongo ObjectId, or ^[A-Za-z0-9_. \-&#()/]{1,50}$); otherwise 400.
These are top-level routes (not under /exactapi). All except /ingest/health require a valid JWT and are rate-limited per client_id. Payloads over clarity.ingest.max_payload_bytes (10 MB) → 413.
See Storage Engine for the storage-path selection and exotic parsers.
/ingest/healthNo auth. Returns ingest + MQTT health.
{ "message": "Healthy", "mqtt_connected": true }
/ingest/{client}/{config} — v1Auth required. Flexible path with exotic-payload parsers (energy-meter gateways, byte-field expansion, device-specific formats).
Request body
{ "temperature": 23.5, "pressure": 1.01, "timestamp": 1700000000000 }
Response
| Status | Body |
|---|---|
| 200 | { "status": "received" } |
| 400 | { "error": "Invalid parameters. arguments must be valid identifier." } |
| 413 | { "error": "Payload too large" } |
| 429 | { "error": "<rate-limit message>" } |
| 503 | { "error": "ingest failed: <e>" } (historian backpressure) |
/ingest/v2/{client}/{config} — indexed fast pathAuth required. Same wire payload and responses as v1, optimized for high-rate steady streams (a per-session cache of tag → storage location). It does not apply the v1 exotic parsers; a payload that needs them (energy-meter markers, device ids) is detected and re-dispatched to v1 automatically. Unknown keys still flow through the full v1 path so nothing is dropped.
Response: 200 { "status": "received" } (plus the same 400/413/429/503 shapes as v1).
/ingest/backfill/{client}/{config}Auth required. Functionally identical to v1 (same payload, parsers, and responses), intended for historical loads.
clarity.ingest.write.method (fast | buffered | http) — see Capacity planning → Configuration knobs.clarity.ingest.mqtt.publish=ON.Adopted from clarity backend developer docs (
docs/developer/api/ingest.md), imported reference.
Primary handlers:clarity:backend/src-tauri/src/processing_api/ingest.rs,clarity:backend/src-tauri/src/processing_api/ingest_v2.rs.
Last updated: 2026-07-17 from commit 6800acc