HTTP API
SuperWitness serves a small JSON API under /v1. If you are building a client, we can keep the
map simple: the MCP tools are thin layers over the same operations, and this page is
the literal route, parameter and error reference. Eight routes have no tool:
GET /v1/runs/by-attempt/{attempt}, POST /v1/runs, the two rubric
reads, the transcript step route (GET /v1/runs/superpipeline/{board}/{run}/transcript/items/{seq_from}),
GET /v1/me, GET /v1/verdicts and GET /v1/scopes. (GET /v1/runs is the list_runs tool.)
Authentication
Section titled “Authentication”Every /v1 route takes a bearer token with SuperWitness’s SW_PUBLIC_URL as its audience,
issued by the AgentPod hub or, when SW_ORG_PLANE_ISSUER is set, by the organization plane
(hub tokens are then refused):
Authorization: Bearer <token>With AgentPod and SuperPipeline
lists what a token must carry. A missing or refused token is 401 unauthenticated. In fake
mode, tokens are dev:<principal>:<human|agent|service>.
A browser signed in to the app is authenticated by its session cookie instead; changes made that way must carry Origin equal to SW_PUBLIC_URL. A bearer token always wins over a cookie. POST /v1/runs and /mcp take bearer tokens only. A person’s token is resolved to their prn_ principal id; if AgentPod cannot be asked, the answer is 503 principal_unresolved.
Routes
Section titled “Routes”| Method | Path | Answers |
|---|---|---|
GET |
/v1/runs/superpipeline/{board}/{run} |
200 with the run document |
GET |
/v1/runs/superpipeline/{board}/{run}/spans |
200 with one page of spans |
GET |
/v1/runs/superpipeline/{board}/{run}/logs |
200 with one page of log lines |
GET |
/v1/runs/superpipeline/{board}/{run}/transcript |
200 with one page of an attempt’s transcript (Transcripts) |
GET |
/v1/runs/superpipeline/{board}/{run}/transcript/items/{seq_from} |
200 with one transcript step whole |
GET |
/v1/runs/by-attempt/{attempt} |
302 to the run document |
POST |
/v1/runs |
200 with one result per report (Run registry API) |
GET |
/v1/runs |
200 with one page of registry runs (Run registry API) |
GET |
/v1/rubrics |
200 with every rubric version, without bodies |
GET |
/v1/rubrics/{id}/{version} |
200 with one rubric version and its body |
GET |
/v1/me |
200 with {"principal", "kind", "email", "via"}: who the caller is, and whether by session or bearer |
GET |
/v1/verdicts |
200 with every verdict on one subject (subject_kind, subject_ref), oldest first, each with superseded_by; past 500, the newest 500 |
GET |
/v1/scopes |
200 with every scope runs were reported in: {"scopes": [{"source", "id", "name", "runs"}]} |
POST |
/v1/verdicts |
201 with a new verdict, or 200 with the one already recorded under the key |
Path parameters:
{board}and{run}are SuperPipeline board and run ids: letters, digits,_and-, starting with a letter or digit, up to 128 characters. Otherwise 400invalid_run_ref.{attempt}isattempt_followed by 1 to 128 letters, digits,_or-. Otherwise 400invalid_attempt_id.
JSON answers carry Content-Type: application/json and Cache-Control: no-store.
GET /v1/runs/superpipeline/{board}/{run}
Section titled “GET /v1/runs/superpipeline/{board}/{run}”The run document, assembled from every source at read time. It is 404 run_not_found only when
SuperPipeline and the AgentPod hub both say they do not know the run; any other source failure
is a 200 with that source’s status in sources. Read a run.
GET /v1/runs/superpipeline/{board}/{run}/spans
Section titled “GET /v1/runs/superpipeline/{board}/{run}/spans”| Query | Meaning |
|---|---|
cursor |
next_cursor from the previous page; left out for the first page |
limit |
page size, 1 or more; default 100, and anything above 500 is 500 |
Answers {"spans": [...], "next_cursor": "…"}, oldest first; next_cursor is left out on the
last page. Each span has trace_id, span_id, parent_span_id (left out for a root span),
name, service, start, duration_ms and attributes (string values).
GET /v1/runs/superpipeline/{board}/{run}/logs
Section titled “GET /v1/runs/superpipeline/{board}/{run}/logs”| Query | Meaning |
|---|---|
cursor |
next_cursor from the previous page; left out for the first page |
level |
debug, info, warn or error; left out for every level |
limit |
page size, 1 or more; default 100, and anything above 500 is 500 |
Answers {"logs": [...], "next_cursor": "…" or null, "trace_join": "<status>"}, oldest first;
next_cursor is null on the last page. Each line has at, service, level, message, and,
when the line has them, trace_id, span_id and run_id. trace_join is the traces source’s
status while the run’s trace ids were looked up; when it is not ok, lines were matched by run
id only. Read a run.
GET /v1/runs/superpipeline/{board}/{run}/transcript
Section titled “GET /v1/runs/superpipeline/{board}/{run}/transcript”| Query | Meaning |
|---|---|
attempt |
the attempt to read; required when the run has more than one |
seq_from, seq_to |
the range, inside the attempt; default the whole attempt |
cursor |
next_cursor from the previous page; send the same seq_from and seq_to with it |
Needs a signed-in session or a token granted transcripts:read. Answers AgentPod’s transcript
page unchanged, plus attempt_id, with Cache-Control: no-store; 200 steps a page.
GET …/transcript/items/{seq_from}?attempt=&full=1 answers one step whole, by its first seq; it
also accepts seq_from and seq_to, the range the step was shown in, which must lie inside the
attempt. Transcripts has the shape, the redaction and the audit.
GET /v1/runs/by-attempt/{attempt}
Section titled “GET /v1/runs/by-attempt/{attempt}”302 with Location: /v1/runs/superpipeline/{board}/{run} for the run the attempt belongs to,
and no body.
GET /v1/rubrics and GET /v1/rubrics/{id}/{version}
Section titled “GET /v1/rubrics and GET /v1/rubrics/{id}/{version}”GET /v1/rubrics answers {"rubrics": [...]}, ordered by id and then newest version first.
Each has id, version, standard (rubric:<id>@<version>, what a verdict names), name,
scale as recorded, recognised_scale, created_by and created_at. The single-rubric route
adds body. recognised_scale is the scale in one of the shapes on
Verdicts, or null when it is in none of them.
POST /v1/verdicts
Section titled “POST /v1/verdicts”Body: one JSON verdict request, at most 64 KiB, with no unknown fields. Answers the stored verdict. Verdicts has every field and rule; Contracts has the shape.
Outside /v1
Section titled “Outside /v1”| Path | |
|---|---|
GET /health |
No token. 200 whenever the process is alive, with each source’s status in the body (Operations). |
/mcp |
The MCP server, with the same bearer token (MCP tools). A request that arrives through the public edge (from a SW_TRUSTED_PROXIES address, carrying CF-Connecting-IP) is answered 404 before authentication. |
GET /auth/login, GET /auth/callback, POST /auth/logout |
Signing in to and out of the app (The app). 404 “Sign-in is off” when no one is allowed to sign in. Logout answers 204, or 503 store_unavailable with the cookie cleared. |
GET / (the runs list), GET /runs/superpipeline/{board}/{run}, GET /rubrics, GET /rubrics/{id}/{version} |
Pages of the app, built into the binary (The app). |
Any other GET or HEAD outside /v1 and /mcp is served by the app: one of its files,
or the page itself for a path without a file extension. Other methods on unknown paths are 404
not_found. A wrong method on a route that exists, such as POST /health, is 405
method_not_allowed.
Errors
Section titled “Errors”Every error from /v1 is one JSON object:
{"error":{"code":"logs_unavailable","message":"logs is unavailable","retryable":true}}codeis stable; match on it.messageis for people and may change.retryableis present, andtrue, only when the same request may succeed later. A retryable 503 also carriesRetry-After: 5.
Every code
Section titled “Every code”| Status | Code | When |
|---|---|---|
| 400 | invalid_run_ref |
a board or run id is malformed |
| 400 | invalid_attempt_id |
the attempt id is not attempt_<id> |
| 400 | invalid_limit |
limit is not a whole number of 1 or more |
| 400 | invalid_cursor |
cursor is not one SuperWitness issued |
| 400 | invalid_seq |
seq_from or seq_to is not a whole number of 0 or more |
| 400 | attempt_required |
a transcript of a run with several attempts names none |
| 400 | range_outside_attempt |
the transcript range is not inside the attempt |
| 400 | invalid_level |
level is not debug, info, warn or error |
| 400 | invalid_source |
source is not a source name |
| 400 | invalid_status |
a status is not one of the six |
| 400 | invalid_time |
since or until is not RFC 3339 |
| 400 | invalid_needs_verdict |
needs_verdict is not true or false |
| 400 | invalid_rubric_ref |
the rubric id or version is malformed |
| 400 | invalid_json |
the body is not exactly one JSON object of known fields, or is over 64 KiB (verdicts); not one report or a batch of 1 to 100 (runs) |
| 400 | invalid_idempotency_key |
the key is missing, over 200 bytes, or holds NUL |
| 400 | invalid_kind |
kind is not grader, review, eval or calibration |
| 400 | invalid_subject_kind |
subject_kind is not run, attempt or eval_case_run |
| 400 | invalid_subject |
subject_ref does not fit its subject_kind |
| 400 | invalid_value |
value is not exactly one of decision, score (0 to 1), label or text |
| 400 | invalid_comment |
comment holds NUL |
| 400 | comment_too_long |
comment is over 10000 characters |
| 400 | invalid_evidence_refs |
evidence_refs is not up to 100 span ids or session ranges |
| 400 | invalid_supersedes |
supersedes is not a verdict id |
| 400 | judge_mismatch |
judge is set to someone other than the caller |
| 400 | judge_kind_not_accepted |
judge_kind is set; it comes from the caller’s principal record |
| 401 | unauthenticated |
the bearer token is missing or not valid for this service |
| 403 | origin_mismatch |
a change made with a session did not come from SW_PUBLIC_URL |
| 403 | transcripts_forbidden |
a transcript read with a token that lacks transcripts:read |
| 403 | not_authorised |
the session’s person is no longer on SW_ALLOWED_PRINCIPALS |
| 403 | bearer_required |
a run report made with a session |
| 403 | service_principal_required |
a run report from a principal that is not a service |
| 403 | insufficient_scope |
a run report whose token lacks runs:write |
| 403 | source_not_allowed |
a run report for a source the reporter is not bound to |
| 403 | self_judgement |
a non-human judge’s verdict on a run or attempt it executed |
| 403 | not_original_judge |
superseding someone else’s verdict |
| 404 | run_not_found |
neither SuperPipeline nor the hub knows the run |
| 404 | attempt_not_found |
the hub does not know the attempt, or the run has no such attempt |
| 404 | session_not_found |
AgentPod holds no such session or step, or the attempt has no session |
| 404 | attempt_has_no_run |
the attempt was not dispatched from a SuperPipeline run |
| 404 | subject_not_found |
the verdict’s run or attempt does not exist |
| 404 | rubric_not_found |
no such rubric version |
| 404 | not_found |
no such route |
| 405 | method_not_allowed |
the route exists, but not with this method |
| 409 | idempotency_conflict |
the key was already used for a different verdict |
| 409 | already_superseded |
the verdict named in supersedes already has a successor |
| 413 | item_too_large |
the step is over 1 MiB |
| 413 | body_too_large |
a run report body over 256 KiB |
| 422 | invalid_report |
a run report breaks a rule; a batch’s error has index |
| 422 | missing_standard |
the verdict names no standard |
| 422 | invalid_standard |
the standard is not rubric:<id>@<version>, stage:<key> or case:<id> |
| 422 | unknown_rubric |
the rubric version does not exist |
| 422 | supersedes_not_found |
the verdict named in supersedes does not exist |
| 422 | supersedes_mismatch |
the correction names a different subject or standard |
| 429 | rate_limited |
over a rate limit; Retry-After says when to retry |
| 500 | internal |
an unexpected failure |
| 502 | hub_refused |
AgentPod refused SuperWitness’s credential for transcripts (its grant lacks transcripts:read) |
| 502 | <source>_unauthorized |
a source refused SuperWitness’s credential |
| 503 | <source>_unavailable |
a source could not be reached or failed (retryable) |
| 503 | source_unavailable |
AgentPod could not be read for a transcript (retryable) |
| 503 | store_unavailable |
the database is unavailable (retryable) |
| 503 | principal_unresolved |
AgentPod could not say which principal a person’s token names (retryable) |
| 503 | subject_unresolved |
SuperWitness could not confirm the subject or who executed it (retryable) |
| 504 | <source>_timeout |
a source did not answer in time (retryable) |
<source> is the source a route depends on: traces for spans, logs for logs, and
agentpod for by-attempt. So the source codes are traces_unavailable, traces_timeout,
traces_unauthorized, logs_unavailable, logs_timeout, logs_unauthorized,
agentpod_unavailable, agentpod_timeout and agentpod_unauthorized. The run document itself
never fails for a source; it reports the source’s status instead.
The 401 comes from the authentication layer and carries WWW-Authenticate: Bearer realm="superwitness"; its body has code and message only. Match on code, honor
retryable and Retry-After, and your client can explain a failure without teaching itself to
parse prose that is allowed to change.