Reference

REST API reference

REST is the canonical HTTP contract. Every route is versioned under /v1 and enforces the same scope clamp + ACL filter.

Base URL & conventions#

Base URL: https://superchargedb.krisch1218.workers.dev
Auth: Authorization: Bearer <token> (or a console session cookie).
Scope: X-Aegis-Scope header or ?scope= query param.
Content type: application/json for request + response bodies.

Errors share one shape:

error

{ "error": "forbidden", "detail": "read permission required", "status": 403 }

Status	When
`200`	Success.
`400 bad_request`	Body failed schema validation.
`401 unauthorized`	Missing / invalid token or session.
`403 forbidden`	Authenticated but lacking permission.
`404 not_found`	Unknown route/id, or hidden by ACL.
`500 internal_error`	Unhandled server error.

Health#

GET/v1/health

Public liveness + bindings check. No authentication required.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/health"

200 OK

{ "status": "ok", "service": "superchargedb", "version": "v1",
  "time": "2026-07-06T23:11:16.426Z",
  "bindings": { "catalog": "ok", "vector_index": ["aegis-text","aegis-visual","aegis-audio","aegis-docvisual"],
    "object_store": "aegis-raw", "key_value": "aegis-manifest", "inference": true } }

List scopes#

GET/v1/scopes

Registry scopes in the caller’s namespace that the caller is allowed to see.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/scopes" -H "Authorization: Bearer aegis_sk_alice"

200 OK

{ "scopes": [
  { "scope": "acme/alpha/backend", "namespace": "acme-corp", "parent": "acme/alpha",
    "planes": ["text"], "read_only_agents": false, "created_at": 1783343567016 },
  { "scope": "acme/alpha/frontend", "namespace": "acme-corp", "parent": "acme/alpha",
    "planes": ["text"], "read_only_agents": false, "created_at": 1783343567016 }
] }

Search#

POST/v1/search

Hybrid multimodal search. Requires the read permission. The body is an AegisQuery; the response is described in Hybrid search.

Param	In	Notes
`scope`	query / header	Overrides the body scope; `*` = all allowed.
`q`	body	Required query text.
`top_k, planes, rerank, filters, ...`	body	Full field list

fetch.ts

const res = await fetch("https://superchargedb.krisch1218.workers.dev/v1/search?scope=*", {
  method: "POST",
  headers: { Authorization: "Bearer aegis_sk_alice", "Content-Type": "application/json" },
  body: JSON.stringify({ q: "gross margin", top_k: 10, rerank: true }),
});
const { hits, trace, hidden_by_acl } = await res.json();

200 — { hits, answer, trace, context, hidden_by_acl }
400 — invalid AegisQuery (e.g. top_k > 50).
403 — caller lacks read.

List units#

GET/v1/units

Scope-clamped, ACL-filtered listing (lazy, up to 100 per page).

Query param	Default	Notes
`limit`	`100`	Max 100.
`cursor`	`0`	Offset cursor; echo back next_cursor to page.
`scope`	active	Via header/query as usual.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/units?limit=100" -H "Authorization: Bearer aegis_sk_alice"

200 OK (truncated)

{ "units": [ { "unit_id": "u-call-01", "scope": "acme/alpha/backend", "modality": "asr", ... } ],
  "hidden_by_acl": 0, "context": { ... }, "next_cursor": null }

Get a unit

GET/v1/units/:id

Returns a single Unit, enforced by scope + ACL. A Unit hidden by ACL returns 404 — identical to a non-existent id, so visibility never leaks.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/units/u-call-02" -H "Authorization: Bearer aegis_sk_alice"

Catalog stats#

GET/v1/catalog/stats

KPI tiles for the overview: per-plane vector counts, catalog row totals, and query counters.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/catalog/stats" -H "Authorization: Bearer aegis_sk_alice"

200 OK (abridged)

{ "namespace": "acme-corp", "scope": "acme/alpha/backend",
  "planes": [ { "plane": "text", "model": "bge-m3", "dims": 1024, "metric": "cosine",
               "vectors": 19, "indexed": 19, "lag": 0, "health": "green" }, ... ],
  "queries_per_day": 42,
  "storage": { "r2_gb": 0, "d1_rows": 19, "vectors": 19 } }

Grounded, cited answer synthesis. Requires read. The body is an AegisQuery with answer: true; the engine runs a retrieve → localize → verify → cite loop and returns a CitedAnswer alongside the supporting hits and trace. Full walkthrough in Cited answers.

curl

curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/answer?scope=acme/alpha/backend" \
  -H "Authorization: Bearer aegis_sk_alice" -H "Content-Type: application/json" \
  -d '{"q":"How fast was the failover cutover?","answer":true,"planes":["text","audio","doc_visual"]}'

200 — { answer, hits, trace, context, hidden_by_acl } with inline citations + nli_faithfulness.
400 — invalid AegisQuery.
403 — caller lacks read.

Audit log#

GET/v1/audit

Returns { namespace, rows: AuditRow[], count, next_cursor }, newest first. Requires read or admin. Supports limit + cursor. See Audit & verification.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/audit?limit=50" -H "Authorization: Bearer aegis_sk_alice"

Verify the chain

GET/v1/audit/verify

Recomputes the chain and reports whether it is intact — a tamper-evidence proof any reader can run independently.

curl

curl -s "https://superchargedb.krisch1218.workers.dev/v1/audit/verify" -H "Authorization: Bearer aegis_sk_alice"

200 OK

{ "namespace": "acme-corp", "intact": true, "checked": 128,
  "head_seq": 128, "head_hash": "3fa1c0e2…", "break_at": null, "reason": null }
// tampered: { ..., "intact": false, "break_at": 57, "reason": "row hash does not match its content" }

Ingest#

POST/v1/ingest

Batch-ingest multimodal Units. Requires write. Each Unit declares its modality and plane (text, visual, audio, doc-visual), an optional source_uri / mime pointing at the raw bytes in object storage, and an optional Locator. See Data model & ingestion for the full field list.

Field	Type	Notes
`text`	string?	Text (or extracted caption/OCR/ASR) to embed + FTS-index.
`modality`	`Modality`	text, chunk, caption, ocr, asr, image, image_region, doc_page, video_shot, audio_utterance, log_template, detection.
`plane`	`Plane`	text \| visual \| audio \| doc_visual (defaults from modality).
`source_uri`	string?	Object-storage key / origin pointer for the raw source.
`mime`	string?	Content type of the source (e.g. video/mp4, application/pdf).
`locator`	Locator?	Sub-unit span: time_range \| bbox \| char_span \| line_range.
`doc_id`	string?	Groups Units under one source.
`acl_owner`	string?	ABAC owner (defaults to your principal).
`acl_groups`	string[]?	ABAC groups that may read the Unit.

curl

curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/ingest" \
  -H "Authorization: Bearer aegis_sk_alice" -H "Content-Type: application/json" \
  -d '{"units":[
    {"text":"hello world","scope":"acme/alpha/backend"},
    {"text":"CFO discusses failover cutover","modality":"asr","plane":"audio",
     "source_uri":"acme/alpha/keynotes/keynote-q3.mp4","mime":"video/mp4",
     "locator":{"kind":"time_range","t_start_ms":767000,"t_end_ms":782000}}
  ]}'

Admin: seed#

POST/v1/admin/seed

(Re)seeds the demo dataset. Open on first run to bootstrap; once tokens exist it requires an admin principal. Returns the created principals, scopes, tokens, and counts.

Not yet implemented#

The shared route table reserves several endpoints that are part of the design but currently return 404. Do not depend on them yet:

Route	Purpose	Status
`GET /v1/grants`	Grant administration	`404`
`GET /v1/principals`	Principal administration	`404`
`GET /v1/namespaces`	Namespace registry	`404`
`GET /v1/sources/:id`	Raw source fetch	`404`

Verified behavior

Every request/response in this reference reflects the live, seeded Worker and is exercised by the automated integration test suite. See the Roadmap for what is planned next.

REST API reference

Base URL & conventions#

Health#

Get context#

List scopes#

Search#

List units#

Get a unit

Catalog stats#

Answer (cited synthesis)#

Audit log#

Verify the chain

Ingest#

Admin: seed#

Not yet implemented#