Skip to content

Run registry API

Open as Markdown

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.

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.

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.

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.

{"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 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.

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}
}
  • ref is the run as <source>:<external_ref>. A verdict’s run subject is accepted only as superpipeline:<board>/<run>, so for a SuperPipeline run record a verdict with "subject_kind": "run" and this as subject_ref. A run from any other source, or with an external_ref that is not <board>/<run>, cannot be a verdict’s subject yet: it is refused 400 invalid_subject.
  • stage_key and card_id are as last reported, or null when the newest report left them out. On main, not yet released: v0.0.12 answers neither.
  • latest_verdict is the newest verdict on the run that no other verdict supersedes, or null. Verdicts on the run’s attempts do not count.
  • counts totals every status for the same filter without status, so a view can show its tabs.
  • next_cursor is null on 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.