Run registry API
SuperWitness keeps its own list of runs so you can browse work without asking every source for a fresh inventory. Each product that runs work, a source, reports its runs as they start, change and finish, much as it sends telemetry to an OTLP endpoint. SuperWitness never asks a product to list its runs. If a source has not reported a run, the list cannot invent it—but the run’s own page still works when you have its link.
Reporting runs
Section titled “Reporting runs”POST /v1/runs takes one report, or a batch of 1 to 100:
{ "source": "superpipeline", "external_ref": "brd_01/run_01", "scope": {"id": "brd_01", "name": "Press"}, "title": "Draft the release note", "stage_key": "draft", "card_id": "crd_01", "executor": {"id": "prn_…", "name": "drafter"}, "status": "running", "source_status": "in_progress", "started_at": "2026-10-06T09:00:00Z", "ended_at": null, "reported_at": "2026-10-06T09:00:01Z" }{ "runs": [ { … }, { … } ] }| Field | Required | Rule |
|---|---|---|
source |
yes | lowercase letters, digits and -, starting with a letter, at most 32 |
external_ref |
yes | the source’s own reference for the run, 1 to 256 characters |
scope |
no | {"id", "name"}: where the run belongs, such as a board. id is required, 1 to 128 characters; name, 1 to 200, may be left out. Leave scope out rather than send null |
title |
no | 1 to 200 characters. Leave it out rather than send null or "" |
stage_key |
no | the source’s stage the run belongs to, such as a board stage’s key, 1 to 128 characters. Leave it out rather than send null or "" |
card_id |
no | the source’s work item the run is for, such as a board card’s id, 1 to 128 characters. Leave it out rather than send null or "" |
executor |
no | {"id", "name"}: who ran it. name is required, 1 to 200 characters; id, when known, is a hub principal id (prn_ and 20 lowercase hex digits). Leave executor out rather than send null |
status |
yes | queued, running, waiting, succeeded, failed or cancelled |
source_status |
yes | the source’s own word for the state, 1 to 64 characters |
started_at, ended_at |
no | RFC 3339 timestamps, or null when not yet known |
reported_at |
yes | RFC 3339: when the source produced this report |
Unknown fields are refused, and field names are matched exactly. Timestamps are RFC 3339
date-time strings of at most 64 characters, kept to the microsecond. The format is strict: the fraction separator is a dot, not a comma, and an offset hour is at most 23. The body may be at most
256 KiB.
Who may report
Section titled “Who may report”A reporter is an AgentPod service principal whose token carries the runs:write scope and
SuperWitness’s audience (SW_PUBLIC_URL). SuperWitness also binds each reporter to one source
with SW_RUN_SOURCES, for example SW_RUN_SOURCES=prn_reporter01=superpipeline; a report for
any other source is refused. Session cookies are never accepted here.
Newer reports win
Section titled “Newer reports win”A report updates its run only when its reported_at is strictly newer than the one stored.
An equal or older report changes nothing and answers "applied": false, so retries and
out-of-order deliveries cannot move a run backwards. A reported_at more than 5 minutes ahead
of SuperWitness’s clock is refused, so that one report from a fast clock cannot freeze a run.
The answer
Section titled “The answer”{"results": [{"external_ref": "brd_01/run_01", "applied": true}]}One result per report, in the order sent. A batch is checked as a whole: if one report is
invalid, nothing is written, and the error names its position with index. A single report’s errors carry no index; a batch from a reporter that is not bound to the source gets index 0:
{"error": {"code": "invalid_report", "message": "runs[3].status: one of queued, …", "index": 3}}| Status | Code | When | Retry? |
|---|---|---|---|
| 400 | invalid_json |
the body is not one report or {"runs": [...]} of 1 to 100 |
no |
| 401 | unauthenticated |
no token, or one not valid for this service | no |
| 403 | service_principal_required |
the token’s principal is not a service | no |
| 403 | insufficient_scope |
the token lacks runs:write |
no |
| 403 | source_not_allowed |
the reporter is not bound to this report’s source | no |
| 413 | body_too_large |
the body is over 256 KiB | no |
| 422 | invalid_report |
a report breaks a rule above | no |
| 503 | store_unavailable |
SuperWitness’s database is unavailable; Retry-After is set |
yes |
A reporter should retry 5xx answers and network errors with backoff, and set any other 4xx aside: sending it again will get the same answer.
Each report refused after its token is accepted is logged as runs.report_rejected, with the caller’s principal, the
error code and, for a batch, the index.
An applied: true result means the registry now reflects that report. An older retry returns
applied: false, which is still a successful receipt: the registry kept the newer truth.
The schema
Section titled “The schema”The body is described by a JSON Schema (draft 2020-12), published at
/schemas/run-report.schema.json and kept in the
repository at internal/contracts/run-report.schema.json. SuperWitness’s own tests run the same
bodies through the schema and through its handler and require the same answer from both.
SuperWitness keeps four rules beyond the schema: reported_at may be at most 5 minutes ahead
of its clock, no string may contain NUL (\u0000), a timestamp may not be a leap second, and a
timestamp’s year in UTC must be 0 to 9999.
Listing runs
Section titled “Listing runs”GET /v1/runs lists runs newest first: by started_at, or by when SuperWitness first heard of
the run when it has not started, then by source and external_ref.
| Query | Meaning |
|---|---|
source |
only runs from this source |
scope |
only runs in this scope id |
status |
only runs with this status; repeat it for several |
executor |
only runs this principal executed |
stage_key |
only runs reported with this stage_key; with scope, one stage’s history on one board. On main, not yet released |
since, until |
RFC 3339; runs whose start (or first sighting) is at or after since and before until |
needs_verdict |
true: finished runs (succeeded, failed, cancelled) that no verdict names yet |
cursor |
next_cursor from the previous page |
limit |
page size, 1 or more (0 or less is 400 invalid_limit); default 50, and anything above 200 is 200 |
{ "runs": [ { "source": "superpipeline", "external_ref": "brd_01/run_01", "ref": "superpipeline:brd_01/run_01", "scope": {"id": "brd_01", "name": "Press"}, "title": "Draft the release note", "stage_key": "draft", "card_id": "crd_01", "executor": {"id": "prn_…", "name": "drafter"}, "status": "succeeded", "source_status": "done", "started_at": "2026-10-06T09:00:00Z", "ended_at": "2026-10-06T09:05:00Z", "reported_at": "2026-10-06T09:05:01Z", "first_seen_at": "2026-10-06T09:00:02Z", "updated_at": "2026-10-06T09:05:02Z", "latest_verdict": { "id": "vrd_01", "judge": "prn_human01", "judge_kind": "human", "standard": "rubric:press@1", "value": {"decision": "pass"}, "created_at": "2026-10-06T09:30:00Z" } } ], "next_cursor": null, "counts": {"queued": 0, "running": 2, "waiting": 1, "succeeded": 14, "failed": 3, "cancelled": 0}}refis the run as<source>:<external_ref>. A verdict’s run subject is accepted only assuperpipeline:<board>/<run>, so for a SuperPipeline run record a verdict with"subject_kind": "run"and this assubject_ref. A run from any other source, or with anexternal_refthat is not<board>/<run>, cannot be a verdict’s subject yet: it is refused 400invalid_subject.stage_keyandcard_idare as last reported, ornullwhen the newest report left them out. Onmain, not yet released: v0.0.12 answers neither.latest_verdictis the newest verdict on the run that no other verdict supersedes, ornull. Verdicts on the run’s attempts do not count.countstotals every status for the same filter withoutstatus, so a view can show its tabs.next_cursorisnullon the last page. A cursor stays valid while new runs arrive: the next page continues where the last one ended.
Errors: 400 invalid_source, invalid_status, invalid_time, invalid_cursor, invalid_limit
or invalid_needs_verdict, and 503 store_unavailable. Any principal whose token carries
SuperWitness’s audience may list runs, as with every other read.
The MCP tool list_runs takes the same filters as arguments (status as a list) and answers the
same body (MCP tools). Follow next_cursor and you can walk the matching history in its documented order, while counts
keeps the status tabs honest across every page rather than just the slice in front of you.