Type: reference
Imported reference — adopted from the clarity backend developer docs (clarity:docs/developer/07-rest-api.md+docs/developer/api/) and spot-verified against the warp routes. Endpoint-level detail lives on the group pages below.
This is the reference for the Pulse Historian backend HTTP API (the clarity engine). All traffic is HTTPS on a single port (default 3030); there is no plaintext listener. Handlers are warp-based.
For interactive docs, the running backend serves Swagger UI at /docs and the spec at /exactapi/openapi.yaml.
This page covers the conventions that apply everywhere — base URL, authentication, the error model, the LoopBack filter syntax, and the endpoint-group map. Read it first, then jump to the page for the endpoints you need.
https://<host>:3030
Because the certificate is self-signed by default, clients must trust it (download it from GET /exactapi/ca-cert) or disable verification for local testing.
Most /exactapi/* routes require a JWT in the Authorization header. The Bearer prefix is optional — both of these are accepted:
Authorization: Bearer eyJhbGciOiJIUzI1NiI...
Authorization: eyJhbGciOiJIUzI1NiI...
Obtain a token from POST /exactapi/login. An empty/invalid token is rejected with an auth error (401-style). See the API server for the auth model, roles, and row-level scoping.
The token's claims include the user's role and hierarchy grants (units_id, sites_id, orgs_id); non-admin callers are restricted to their granted scope on metadata routes.
All timestamps — query start/end, write timestamp/timestamps, and response timestamps — are epoch milliseconds (u64), unless a specific endpoint notes otherwise.
Errors are returned as JSON with an appropriate status code. Common shapes:
{ "error": "<message>" }
{ "status": "error", "message": "<message>" }
| Status | Meaning |
|---|---|
| 400 | Bad request body / query / filter parse error. |
| 401 | Missing or invalid auth token. |
| 403 | Row-level access denied (outside your granted scope). |
| 404 | Not found. |
| 405 | Method not allowed. |
| 409 | Duplicate key on create (e.g. users.email; error prefixed DUPLICATE:). |
| 413 | Payload too large (ingest > 10 MB). |
| 429 | Rate limit exceeded or account locked. |
| 501 | Subsystem disabled (e.g. monitoring failed to init). |
| 503 | Backpressure (write buffer full) or not the HA leader (mutations). |
| 507 | Insufficient storage (disk guard). |
| 500 | Internal error. |
Note: a few write endpoints return HTTP 200 with an error string in the body rather than an error status. This is called out per endpoint (notably
/exactapi/writeand/exactapi/write_buffered).
On a High-Availability cluster, mutating routes (create/update/write) are gated to the leader node and return 503 on a secondary. Read/query routes, shadow_write, seal_now, and write_buffer_stats are always accessible. See HA.
Metadata list/count/findOne endpoints accept a filter (LoopBack 3 compatible), in three encodings:
?filter={"where":{"orgsId":3},"limit":10} (URL-encoded)?filter[where][orgsId]=3&filter[limit]=10where clause; a standalone ?where={...} is also accepted.The filter object fields: where, fields, include, limit, skip, order. The full operator list and examples are in Entity CRUD → Filter operators.
Start here, then open the page for the group you need. Each page gives the full request/response schema and examples.
| Group | Page | Covers |
|---|---|---|
| Auth & users | auth-users.md | register, login, me, admin user delete. |
| Collections & writes | collections-writes.md | create_collection, write, write_fast, write_buffered, write_tag_mapping, blob_write, seal_now, shadow_write, buffer stats. |
| Queries, blobs & sensordata | queries.md | fast_query, fast_query_binary, fast_query_optimised, fast_query_tag_mapping, lastlist, blob reads, /sensordata/*. |
| Ingest | ingest.md | /ingest, /ingest/v2, /ingest/backfill, health. |
| Aggregation pipeline | aggregation.md | Every pipeline operator and its parameters. |
| Metadata entity CRUD | entity-crud.md | The generic /exactapi/<entity> contract, filter operators, nested routes, entities. |
| Special resources | special-resources.md | connections, tag_mappings, collections, attachments, introspection. |
| Monitoring & alarms | monitoring.md | /exactapi/monitor/* — snapshots, events, rules, config. |
| Notifications | notifications.md | /exactapi/notifications/* — send, list, mark-read, unread-count, SSE stream. |
| OSI PI connectors | connectors-pi.md | /exactapi/pi/* — discovery, onboarding, backfill. |
| HA, backup, streaming & platform | ha-backup-platform.md | /exactapi/ha/*, /api/admin/backup/*, WebSockets, ADK proxy, platform utilities. |
Implemented but not currently reachable over HTTP:
POST /exactapi/update_password (admin password reset — defined but not wired).processing_api::elog (/elog/*) and processing_api::ems (/dataflow/ems/*) route modules — the live equivalents are served by the Python services.The wiki also carries a generated OpenAPI 3.0.3 spec and a Swagger UI wrapper: openapi.yaml · swagger-ui.html. Note: these were generated 2026-05-23 and are older than the prose pages above (they still use the retired [mode:] tags) — treat the group pages here + the live /docs endpoint as current. > TODO-VERIFY: regenerate or retire these two static files.
Verified against:
clarity:backend/src-tauri/src/main.rs:4722(/exactapimount),:3799-3847(register/login),:4078-4292(write/query handlers).
Last updated: 2026-07-16 from clarity@bff451d