All API responses are JSON unless noted. Authenticated endpoints require:
Authorization: Bearer <supabase_access_token>
Creates a research session.
Request:
{ "query": "Research AI agent evaluation systems" }Response:
{ "session": { "id": "...", "status": "draft", "phase": "intake" } }Lists sessions for the authenticated user.
Returns session detail with current run, current run cost, current post-mortem, sources, evaluations, learnings, events, approvals, and report.
Queues a worker-owned research run for an owned session. This endpoint returns before long-running model/search work starts.
Response:
{ "runId": "...", "status": "queued", "run": { "id": "...", "metadata": { "stage": "research" } } }Returns run status, run-linked events, cost, and post-mortem for an owned run.
Returns persisted claims and claim gaps for an owned session.
Records approval, rejection, or follow-up request.
Request:
{
"action": "approve",
"notes": "Sources look good.",
"approvedSourceIds": ["src_abc"],
"waivedGapIds": []
}Approval, rejection, and follow-up requests are accepted only while the owned session is awaiting_approval; stale clients receive 409 approval_not_available before any approval, event, state, gap-waiver, or run-enqueue side effect. The decision is recorded by a transactional Supabase RPC so gap waivers, approval history, events, session state, and queued follow-on runs commit together or not at all. An approval queues a reporting-stage run and returns 202 { "runId": "...", "status": "queued" }. Unresolved critical gaps return 409 critical_gaps_unresolved unless every critical gap is explicitly listed in waivedGapIds with reviewer notes.
Returns the human decision history for an owned session.
Response:
{
"approvals": [
{
"id": "approval_abc",
"sessionId": "session_abc",
"userId": "user_abc",
"action": "approve",
"notes": "Sources look good.",
"approvedSourceIds": ["src_abc"],
"waivedGapIds": [],
"createdAt": "2026-06-24T00:00:00.000Z"
}
]
}Returns server-sent event formatted run events.
Returns user-scoped memories. Pass ?sessionId=... to include session-scoped memory for an owned session.
Writes explicit user or session memory.
Request:
{
"sessionId": "optional-for-session-scope",
"scope": "session",
"namespace": "procedure",
"key": "operator-note:1",
"value": { "note": "Prefer primary sources." }
}Returns the deterministic offline eval regression summary used by CI. This recomputes local fixtures on request and is intentionally separate from configured live-demo proof and persisted history.
Returns persisted offline eval proof history from Supabase. This is a public read-only operational proof endpoint; it uses the server service role and returns only fixture IDs, pass/fail status, scores, issues, regressions, and timestamps.
Query parameters:
suite: optional suite name, defaultofflinelimit: optional recent run count, default20, maximum50
Response:
{
"suite": "offline",
"runs": [
{
"id": "eval_run_abc",
"suite": "offline",
"status": "passed",
"summary": { "passed": true, "total": 3, "failed": 0, "results": [] },
"createdAt": "2026-06-24T00:00:00.000Z"
}
],
"latest": {
"id": "eval_run_abc",
"suite": "offline",
"status": "passed",
"summary": { "passed": true, "total": 3, "failed": 0, "results": [] },
"createdAt": "2026-06-24T00:00:00.000Z",
"results": []
}
}If Supabase is not configured, the endpoint returns 503 supabase_not_configured. Empty history returns 200 with runs: [] and latest: null.
Exports the session report as markdown.
Errors use a consistent envelope:
{
"error": {
"code": "validation_error",
"message": "The request payload is invalid.",
"details": {}
}
}Validation errors include field-level details for client-correctable payloads. Internal server errors intentionally return the generic message Unexpected server error. so repository messages, tokens, user IDs, and report text are not leaked to clients.