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.
`402 upgrade_required / quota_exceeded`	Action or volume exceeds your tier (carries `required_tier`).
`403 forbidden`	Authenticated but lacking permission, or targeting an unowned namespace.
`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 } }

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 }
] }

Create / get / delete a scope

POST/v1/scopes

GET/v1/scopes/:scope

DELETE/v1/scopes/:scope

POST creates a project scope in your namespace (requires write); the engine self-grants you read/write/admin on the new scope so it is usable immediately. GET /v1/scopes/:scope returns one scope’s metadata (path-like scopes are URL-encoded), and DELETE removes it (requires admin). Metadata PATCH updates are still on the roadmap.

curl

curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/scopes" \
  -H "Authorization: Bearer aegis_sk_alice" -H "Content-Type: application/json" \
  -d '{"scope":"acme/alpha/research"}'

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 } }

Answer (cited synthesis)#

POST/v1/answer

Grounded, cited answer synthesis. Requires read. The body is an AegisQuery with answer: true; a Workers AI LLM (with a CF + OpenAI fallback chain) answers strictly from the retrieved, cited context and returns a CitedAnswer alongside the supporting hits and trace. Gated to Pro / Enterprise. 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}}
  ]}'

Delete units#

POST/v1/units:delete

Tombstone Units by ids or by a filter, scope-clamped and ACL-enforced. Requires write. Pass hard: true to purge the raw source and vectors rather than soft-tombstoning. Returns the affected counts.

curl

curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/units:delete" \
  -H "Authorization: Bearer aegis_sk_alice" -H "Content-Type: application/json" \
  -d '{"ids":["u-call-01"],"hard":false}'

Compaction#

GET/v1/compaction

POST/v1/compaction

GET reports per-plane index freshness (indexed vs. pending, lag, health); POST requests a compaction pass to reconcile the vector index with the catalog. Requires read (status) / admin (trigger).

curl

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

Registries: namespaces, grants, principals#

Namespaces, grants, and principals are managed through first-class registry endpoints. Each supports create, list, get-by-id, and delete; PATCH updates are still on the roadmap.

Namespaces are self-service: GET /v1/namespaces and POST /v1/namespaces only require authentication (they are tenant-isolated to what you own, and creation is bounded by your tier’s max_namespaces quota). Grants and principals CRUD require an admin principal, as do get/delete on a single namespace. See multi-namespace tenancy.

Resource	Create	List	Get / Delete
`namespaces`	`POST /v1/namespaces`	`GET /v1/namespaces`	`GET` / `DELETE /v1/namespaces/:ns`
`grants`	`POST /v1/grants`	`GET /v1/grants`	`GET` / `DELETE /v1/grants/:id`
`principals`	`POST /v1/principals`	`GET /v1/principals`	`GET` / `DELETE /v1/principals/:id`

curl

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

Billing (Stripe)#

Subscription endpoints backed by Stripe (Pro + Enterprise × monthly / yearly / lifetime). Full pricing and the upgrade flow are in Pricing & billing.

Route	Method	Auth	Purpose
`/v1/billing/plans`	GET	public	The purchasable catalog + payment links + publishable key.
`/v1/billing/checkout`	POST	bearer/session	Create a Checkout Session: `{ tier, cadence }` → hosted URL.
`/v1/billing/subscription`	GET	bearer/session	Current tier + subscription rows for the caller.
`/v1/billing/portal`	POST	bearer/session	Open the Stripe customer portal.
`/v1/billing/webhook`	POST	Stripe HMAC	Signature-verified event sink that fulfills tiers.
`/v1/billing/reconcile`	POST	cron secret	Re-sync tiers from Stripe.

The webhook verifies the Stripe-Signature first: a bad/missing signature is a clean 400 invalid_signature, and a missing endpoint secret is 503 webhook_not_configured (never a misleading 500).

curl

curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/billing/checkout" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"tier":"pro","cadence":"monthly"}'

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.

Benchmarks & eval#

GET/v1/benchmarks

GET/v1/eval

Return the published BenchmarkReport (engine/system benchmarks and retrieval-quality evals) so the SDK/CLI/MCP bench & eval tools resolve. The report is published to the manifest store by the benchmark tooling; when none has been published yet the routes return a valid, honestly-empty report — { benchmarks: [], evals: [], generated_at } — never a 404.

curl

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

Not yet implemented#

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

Route	Purpose	Status
`GET /v1/sources/:id`	Raw source fetch	`404`
`PATCH /v1/scopes · /namespaces · /grants · /principals`	In-place metadata updates (create/list/get/delete are live)	`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.