HTTP API
One listener (default :7123) serves both subsystems. Bodies may be JSON or YAML per Content-Type; responses are JSON by default, YAML via Accept or ?format.
Configuration
Section titled “Configuration”| Method | Path | Purpose |
|---|---|---|
| GET | /hives | List hives + registry version |
| GET / HEAD | /hives/:hive/*path | Resolved snapshot at path. ETag = version |
| PUT | /hives/:hive/*path | Replace value → 200/201; 409 on If-Match mismatch; 422 on CUE failure |
| PATCH | /hives/:hive/*path | Deep-merge a partial document |
| DELETE | /hives/:hive/*path | Delete → 204 |
| GET | /hives/:hive/*path/_meta/schema | The hive’s CUE schema (text) |
| GET | /hives/:hive/*path/_meta/example | Canonical example document |
| GET | /sources | Declared sources per hive |
| GET | /subscribers | Connected SSE subscribers (admin) |
Read modifiers:
?raw=<source>— the unresolved contribution of one source.?tree=true[&depth=N]— list the subtree under a path.If-None-Match— conditional read → 304.If-Min-Version— block briefly until the snapshot reaches a version (read-after-write).
Write headers:
If-Match— optimistic concurrency (mismatch → 409).X-Reason— audit annotation.X-Schedule-Revert-At— break-glass auto-revert: the write is applied now and an audited revert is enqueued for the given time.?source=<name>— disambiguate when more than one writable source owns the path.
Writes under /_meta return 405. Paths that violate a predefined level (e.g. an unknown environment) fail structurally with 400 invalid_path before any source I/O.
Configuration stream (SSE)
Section titled “Configuration stream (SSE)”| Method | Path | Purpose |
|---|---|---|
| GET | /stream/config | Snapshot push. Query: ?hives=…, &label.<k>=<v>. Resume with Last-Event-Id |
| POST | /stream/config/drift | Subscriber drift report → 202 (feeds metrics) |
Event types: snapshot (upsert), delete, full_resync (drop your view and re-read), heartbeat. At connect, backfill carries hive roots only — clients REST-read their own node first, then follow the stream. Per-connection buffer is 256 events; overflow disconnects the subscriber, which resumes by cursor.
Git webhooks
Section titled “Git webhooks”| Method | Path | Purpose |
|---|---|---|
| POST | /webhooks/git/<source-name> | Nudge a git source to pull now instead of waiting for the poll interval |
Signatures validated: X-Hub-Signature-256 (GitHub), X-Gitlab-Token, X-Gitea-Signature.
Service discovery
Section titled “Service discovery”| Method | Path | Purpose |
|---|---|---|
| POST | /register | Upsert an instance by instance_id; ttl_secs 5–600 |
| PUT | /heartbeat/:id | Renew the lease |
| DELETE | /deregister/:id | Revoke the lease |
| GET | /services | Service names with registrations |
| GET | /services/:name/instances | Instances; filters ?dc=, ?cluster=, ?tag=k:v |
| GET | /stream/discovery | SSE membership stream (?services=…); events instance_up, instance_down, instance_expired, heartbeat |
An instance that stops heartbeating drops out when its lease expires — crash-safe by construction.
Health
Section titled “Health”GET /health (liveness, no dependency checks), GET /ready (200 only after the first reconcile pass), GET /version. All unauthenticated.
Any one of, in order: X-Api-Key (file-backed), Authorization: Bearer (JWKS-validated JWT), or an mTLS client certificate. Authorization is per-hive expression policy evaluated over (subject, action, hive, path).