Skip to content
Browse documentation

Getting started

Quickstart

Authenticate, run a hybrid search, and read the result — using the live, seeded demo index.

Prerequisites#

  • A bearer token. The demo exposes aegis_sk_alice (full access) and aegis_sk_bob (read-only, narrower ACL).
  • Any HTTP client — curl, fetch, or the language of your choice.

1. Check the service is up#

The health endpoint is public (no token required) and reports the bound resources:

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": {
    "d1": "ok",
    "vectorize": ["aegis-text", "aegis-visual", "aegis-audio", "aegis-docvisual"],
    "r2": "aegis-raw",
    "kv": "aegis-manifest",
    "ai": true
  }
}

2. Run your first search#

Send a natural-language query to POST /v1/search with your bearer token. The body is an AegisQuery; only q is required.

curl
curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/search" \
  -H "Authorization: Bearer aegis_sk_alice" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Q3 revenue miss and gross margin",
    "top_k": 5,
    "rerank": true
  }'

The same call with the JavaScript / TypeScript fetch API:

fetch.ts
const res = await fetch("https://superchargedb.krisch1218.workers.dev/v1/search", {
  method: "POST",
  headers: {
    Authorization: "Bearer aegis_sk_alice",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ q: "Q3 revenue miss and gross margin", top_k: 5 }),
});

const result = await res.json();
for (const hit of result.hits) {
  console.log(hit.score.toFixed(3), hit.unit_id, "—", hit.snippet);
}

3. Read the response#

Each hit includes the Unit id, a snippet, a Locator, a score breakdown, and its scope. The trace reports per-stage latency and compute cost, and hidden_by_acl tells you how many candidates your ACL removed.

200 OK (truncated)
{
  "hits": [
    {
      "unit_id": "u-call-02",
      "plane": "text",
      "modality": "asr",
      "source_uri": "acme/alpha/backend/earnings/2026-q3-earnings-call.mp3#t=95",
      "doc_id": "doc-earnings-call",
      "snippet": "CFO: Total Q3 revenue came in at 412 million dollars, below our guidance...",
      "locator": { "kind": "time_range", "t_start_ms": 95000, "t_end_ms": 121000, "speaker": "CFO" },
      "score": 0.87,
      "scores": { "fused": 0.031, "dense": 0.71, "lexical": -1.2, "rerank": 0.87 },
      "scope": "acme/alpha/backend"
    }
  ],
  "answer": null,
  "trace": {
    "stages": [
      { "stage": "embed", "ms": 42, "neurons": 120 },
      { "stage": "vectorize", "ms": 61 },
      { "stage": "d1_fts", "ms": 9 },
      { "stage": "rrf", "ms": 1 },
      { "stage": "rerank", "ms": 180, "neurons": 900 }
    ],
    "total_ms": 300,
    "total_neurons": 1020,
    "est_cost_usd": 0.01122,
    "cache": "miss"
  },
  "context": { "effective_scopes": ["acme/alpha/backend"], "perms": ["read", "write", "admin"] },
  "hidden_by_acl": 0
}

4. See access control in action#

Run the exact same query as aegis_sk_bob. Bob is not in the finance group, so finance-only Units are removed and counted in hidden_by_acl:

curl
curl -s -X POST "https://superchargedb.krisch1218.workers.dev/v1/search" \
  -H "Authorization: Bearer aegis_sk_bob" \
  -H "Content-Type: application/json" \
  -d '{"q":"Q3 revenue miss and gross margin","top_k":10}' | \
  # bob sees fewer hits and hidden_by_acl > 0

Next steps

Learn how scope is chosen in Authentication, tune the query in Query & the AegisQuery AST, and see every endpoint in the REST API reference.