HTTP API

Local API served by eelden serve / eelden studio. Base path: /api/v1. Auth is required on /api/*.

Auth

Pass the serve token one of three ways:

Mechanism	Example
Query	?token=…
Header	Authorization: Bearer …
Header	X-Eelden-Token: …

WebSocket tails use the query-string form (browsers cannot set WS auth headers).

Snapshot pin

Optional request header:

Eelden-Snapshot: <snapshot-name>

Pinned reads resolve against that named snapshot. Studio's time-travel slider sets this.

Endpoints

Health

Method	Path	Notes
GET	/api/v1/health	{"ok":true,…}
GET	/api/v1/health/detail	Corruption identities+counts, WAL/checkpoint lag, recovery, fsync histogram
GET	/api/v1/stats	Engine stats for Studio footer

Tenants

Method	Path	Notes
GET	/api/v1/tenants	Catalog list

Per-tenant

All under /api/v1/t/:tenant/…. Touching collections or running a query applies pending lazy migration (Slice A).

Method	Path	Notes
GET	…/collections	Names + row estimates
GET	…/schema	Schema IR / fingerprint status (does not apply migration)
GET	…/snapshots	Named snapshots
GET	…/diff	Version diff (added / removed / changed)
GET	…/tail	CDC: WebSocket upgrade, or HTTP poll with ?after=<lsn>
POST	…/query	One pipeline or one atomic block
POST	…/ops	Tenant catalog operations

Also: GET /api/v1/schema.eel returns the loaded schema source.

POST …/query

Body:

{ "query": "users |> filter active == true |> select { name }" }

Also accepts "text". Raw non-JSON bodies are treated as query text.

Success JSON includes columns, rows, and a plan hint (index vs scan) when applicable. Errors are 400 with {"error":"…","conflict":bool} — conflict is true on atomic first-committer-wins failures.

/query rejects schema decls, named-query decls, and tenant ops — send those via schema files at serve start or /ops.

POST …/ops

{ "op": "create" | "fork" | "snapshot" | "suspend" | "delete" | "compact",
  "name": "…",
  "target": "…" }

op	Fields
create	name (defaults to path tenant)
fork	source name, required target
snapshot	source name, required target
suspend / delete	name
compact	uses path tenant

Response: {"ok":true,"message":"…"}.

CDC tail

• WebSocket: GET /api/v1/t/:tenant/tail?token=… with Upgrade.
• HTTP poll: same path without upgrade; ?after=<lsn> and optional ?collection=.

Events carry advancing write-frame LSNs; resume from any event's lsn.

CORS

Local serve allows Studio origins and exposes Authorization, Content-Type, X-Eelden-Token, Eelden-Snapshot.