Query plane REST API /v1/
A read-only JSON API over minisign-signed artifacts. The server holds no truth of its own: every record, endpoint list, and index it serves first passes signature verification against a pinned public key — if verification fails, you get a 503 refusal, never stale or partial data.
Stability promise — additive-only
The /v1/ surface is additive-only: no existing field, endpoint, operation, response, or path is ever removed or renamed. Compatibility changes arrive as additions only. The machine-readable contract is the OpenAPI 3.1 document at/api/v1/openapi.json, served by every query-plane deployment — the document describes itself. For a live instance right now,boot one in a single command →
GET /api/v1/models/{slug}
One verified model record, served from its shard (seg_ + first two hex of sha256(slug) — O(shard) at any catalogue size). The response headerx-queryplane-source: chunk:seg_xx names the shard, so you can recompute the assignment yourself.
200— the record (21 required fields, the signed bytes)400— slug violates the grammar[A-Za-z0-9][A-Za-z0-9_.-]*[A-Za-z0-9]; the body never echoes what you sent404— no such slug on the plane503{"error":"unverified artifact"}— the artifact failed verification or the origin is unreachable
curl http://127.0.0.1:<port>/api/v1/models/Qwen_Qwen3-0.6B
# → 200 {"id":"Qwen/Qwen3-0.6B","slug":"Qwen_Qwen3-0.6B",...}
# x-queryplane-source: chunk:seg_3fGET /api/v1/search?q=…
Deterministic ranking over the verified index. The same query over the same index returns byte-identical ordering — no clock, no randomness, no personalization. Hits are always records that exist on the plane, schema-valid, signature-covered.
200—{"query":…,"results":[…]}; zero hits is a valid empty result, not an error400— missing or emptyq503— the index failed verification
curl "http://127.0.0.1:<port>/api/v1/search?q=gguf"Caching, CORS, limits
- Artifact-backed GETs carry
Cache-Control: public, max-age=300(bounded, explicit) - CORS:
GET, POST, OPTIONSwithContent-Typeallowed — browser clients work cross-origin - Per-IP fixed-window rate limit; exceeding it answers
429withRetry-After