Concepts

Cited answers

POST /v1/answer runs the full agentic loop — retrieve, localize, verify, then synthesize — and returns a grounded answer where every claim carries a citation that points at the exact sub-unit span.

The retrieve → localize → verify → cite loop#

A cited answer is not a bare LLM completion. SuperChargeDB runs a bounded pipeline and refuses to speak past what the evidence supports:

Retrieve — cheap, high-recall hybrid search across every requested plane (dense + BM25 fused by RRF), scope-clamped and ACL-filtered.
Localize — narrow to a small top-k and pin each candidate to its exact Locator (moment, bbox region, passage, or line).
Verify — an NLI / faithfulness pass checks each drafted claim against its cited source; unsupported claims are dropped before synthesis.
Cite — synthesize the answer with inline [n] markers, each resolving to a citation with a unit_id, source_uri, and Locator.

Endpoint#

POST/v1/answer

Requires the read permission. The request body is an AegisQuery with answer: true — the same validated query object used by POST /v1/search, so planes, modalities, filters, rerank, and budget all apply. Scope is set via the X-Aegis-Scope header or ?scope=, never the body.

Field	Type	Default	Notes
`q`	string	— (required)	The natural-language question.
`answer`	boolean	`true`	Must be true on this route; synthesis is always requested.
`planes`	Plane[]	`["text"]`	Planes to retrieve from — add visual/audio/doc_visual for multimodal evidence.
`modalities`	Modality[]	unset	Restrict the evidence to specific modalities.
`budget`	Budget	unset	Bounds rounds, MLLM calls, inference units, and latency (see Query).

Request#

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": "Where does the Q3 keynote demo the failover, and how fast was the cutover?",
    "answer": true,
    "planes": ["text", "audio", "doc_visual"],
    "top_k": 8,
    "rerank": true
  }'

The same call with the JavaScript / TypeScript fetch API:

answer.ts

const res = await fetch("https://superchargedb.krisch1218.workers.dev/v1/answer?scope=acme/alpha/backend", {
  method: "POST",
  headers: {
    Authorization: "Bearer aegis_sk_alice",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "Where does the Q3 keynote demo the failover?",
    answer: true,
    planes: ["text", "audio", "doc_visual"],
    top_k: 8,
  }),
});

const { answer, hits, trace, context } = await res.json();
for (const c of answer.citations) {
  console.log(`[${c.index}]`, c.source_uri, c.locator);
}
console.log("faithfulness", answer.nli_faithfulness);

Response#

The response is a superset of the search response: the same hits, trace, and enforcement context, plus a populated answer object.

200 OK (abridged)

{
  "answer": {
    "text": "The live failover is demonstrated 12:47 into the keynote, where the primary region is drained and traffic re-homes with no dropped requests [1]. The runbook confirms a sub-second cutover [2].",
    "citations": [
      {
        "index": 1,
        "unit_id": "u-keynote-shot-19",
        "source_uri": "acme/alpha/keynotes/keynote-q3.mp4#t=767",
        "locator": { "kind": "time_range", "t_start_ms": 767000, "t_end_ms": 782000, "shot_idx": 19 }
      },
      {
        "index": 2,
        "unit_id": "u-runbook-p14",
        "source_uri": "acme/alpha/backend/runbooks/failover.pdf#page=14",
        "locator": { "kind": "bbox", "box": [72, 512, 540, 611], "page": 14 }
      }
    ],
    "nli_faithfulness": 1.0
  },
  "hits": [ /* SearchHit[] — same shape as POST /v1/search */ ],
  "trace": {
    "stages": [
      { "stage": "embed", "ms": 40, "neurons": 120 },
      { "stage": "vectorize", "ms": 58, "detail": "text+audio+doc_visual" },
      { "stage": "d1_fts", "ms": 8 },
      { "stage": "rrf", "ms": 1, "detail": "k=60" },
      { "stage": "rerank", "ms": 175, "neurons": 900 },
      { "stage": "localize", "ms": 22, "detail": "2 spans pinned" },
      { "stage": "verify", "ms": 210, "neurons": 1400, "detail": "NLI 2/2 grounded" },
      { "stage": "synth", "ms": 640, "neurons": 5200 }
    ],
    "total_ms": 1154,
    "total_neurons": 7620,
    "est_cost_usd": 0.0838,
    "cache": "miss"
  },
  "context": { "effective_scopes": ["acme/alpha/backend"], "perms": ["read", "write", "admin"] }
}

Citations resolve to Locators

Each entry in answer.citations carries the inline marker index, the source unit_id and source_uri, and an optional Locator. Because the Locator is the same discriminated union used everywhere else, an audio citation resolves to a timestamp window, a doc-visual citation to a page bbox, and a text citation to a character span — so a UI can deep-link to the exact spot.

The faithfulness score

nli_faithfulness is a 0.0–1.0 score from the natural-language inference (NLI) verification stage: the fraction of the answer’s claims that are entailed by their cited evidence. A score below your threshold is a signal to fall back to raw hits or to widen retrieval rather than trust the prose.

Field	Meaning
`answer.text`	The synthesized answer with inline [n] citation markers.
`answer.citations[]`	`{ index, unit_id, source_uri, locator? }` — one per marker.
`answer.nli_faithfulness`	0–1 fraction of claims entailed by their sources.

Verify, don't assume

The localize, verify, and synth stages appear in the trace so you can see exactly what each answer cost in latency and inference units. Assert on invariants — every sentence has a citation, citations resolve to visible Units, faithfulness meets your bar — rather than on exact wording, which shifts as models evolve.

Response shape to re-verify

The documented body is { answer, hits, trace, context } where answer matches the shared CitedAnswer schema. Confirm the final streaming semantics (SSE/WS vs. buffered JSON) against the deployed Worker before building a streaming client.