The Semurg HTTP API.

GET /v1/status

Instance identity, licence, writability, auth state, and store counts. An anonymous caller on an open box gets a reduced, non-identifying view (a store basename hint, no absolute path, no licensee name); once auth is on, the authenticated caller sees the full operator detail.

{"ok":true,
 "api":"semurg /v1 data api",
 "writable":false,
 "auth_required":false,
 "licence":{"state":"unlicensed build (read-only)"},
 "store":{"state":"open","name":"user.bin","shards":null}}

Response captured live on the public box (read-only). A licensed instance reports "writable":true and its licence id, expiry and caps.

POST /v1/ingest write cap required

Append one batch of packed uniform containers. Body is JSON with containers_b64, the base64 of the packed containers. One call, one append, one crossing, no fsync in the path.

{"ok":true,"containers":65536,"bytes":4194304,"elapsed_us":<elapsed>,"containers_per_s":<measured on your box>}

On the public read-only box this returns 403 {"error":"this instance is read-only", ...}. Errors: 422 for a missing or non-base64 body or a wrong-length body, 413 for a batch over 65,536 containers, 500 if the append itself fails.

POST /v1/query

Batch read. The op field selects one of four read primitives. It is a POST only because it carries a JSON body; it is a read, so it is never licence-gated.

{"ok":true,"op":"fetch",
 "result":{"encoding":"base64","bytes":192,"containers":3,"data":"AAAA...AAAA"},
 "params":{"requested":3},"elapsed_us":<elapsed>}

{"ok":true,"op":"histogram","result":[0,0,0,0],"params":{"field_offset":8,"buckets":4},"elapsed_us":<elapsed>}

Responses captured live on the public box (its /v1 store is intentionally empty, so counts read as zero). A missing op or an unsupported one returns 422 with a hint; an empty ids list is 422; over 100,000 ids is 413.

POST /v1/fetch_batch binary

The binary twin of /v1/query op=fetch: same primitive, same single crossing, but no JSON or base64 wrap on the container bytes. Request body is application/octet-stream, a packed array of little-endian u64 ids (8 bytes each). Response is application/octet-stream, exactly one fixed-size container per id in request order, an all-zero container for an absent id. Cap is 1,048,576 ids (8 MiB) per request; a body that is not a whole number of ids is rejected 400 (plain text, since the route otherwise returns raw bytes).

Verified live: one id in returns exactly one container out.

GET /api/health

Liveness, which datasets are ready, the live engine state, and the local model-serving status. The engine block asserts the native engine is the engaged read path (not the OS page cache).

{"ok":true,"service":"semurg benchmark api",
 "engine":{"mode":"native","arms":{"shard":"engaged","chain":"engaged","snn":"engaged"}},
 "datasets":{"binance":"warming","btc-chain":"warming"},
 "intelligence":{"backend":"local_e4b","model":"gemma4:e4b","serving":false,"detail":"native_module_absent"}}

Captured live. The datasets map and the intelligence block are instance-dependent and reflect what is staged and warmed on the box at the moment of the call.

GET /api/benchmarks

The catalog: every runnable benchmark key, what it measures, which datasets it accepts, and its params.

GET POST /api/bench/:key

Run one benchmark. Read-only keys only on the public box; the write keys (writes and friends) are refused 403 under the public policy. An unknown key returns 404 with the available list; a warming or absent dataset returns 503 (retry shortly); malformed params return 422.

{"benchmark":"saops",
 "result":{"saops":<measured on your box>,"synops":1638400000,"saops_human":"<your figure>"},
 "params":{"iters":50000},
 "elapsed_s":<elapsed>,
 "provenance":{"native_engaged":true,"honesty_band":"(c) measured on native silicon"}}

Response captured live. graph_teps takes dataset, hops (1..8), seed and span; it returns 503 while its dataset is warming.

GET /api/dashboard heavy

One-call headline snapshot: it re-runs the full heavy battery (multi-million-container writes plus BFS traversals) and is memoized for 5 seconds so a burst cannot re-run it per request. Classed heavy, so it is shed under load on the public policy.

{"measured_live_on":"<hostname>",
 "writes":{"result":{"containers":1000000,"writes_per_s":<measured on your box>}, ...},
 "writes_16shard":{...},"reads":{...},"traversals":{...},"scans":{...},
 "saops":{"result":{"saops":<measured on your box>,"saops_human":"<your figure>"}, ...}}

Captured live; keys whose dataset is still warming report a {"status":"warming"} stanza rather than a number, which is the honest state on a freshly booted box.