LITMUS_URL, LITMUS_TOKEN and LITMUS_ORG (your org tag) set in your shell (see Authentication). A $NAME in a path is an id you read from the listing route on this page; a <field> in a body is a value you supply, and every field the handler reads is shown, so send only the ones you need. Fields are what the handler’s source reads and writes, listed mechanically; they are not a schema.
POST /v0/orgs/{orgtag}/runs/start
Start a run of one minted world as a job: 202 + job id, poll it as a pipeline job. A separate verb from POST …/runs on purpose — that one IMPORTS a finished bundle and answers with data; this one does work and answers with something to poll, and a route that did either depending on the body would hide which one it did.
Path parameters:
orgtag
Body fields the handler or its helper reads: agent, agent_version, autofix, by, control, environment, force, group, harness, include_held, model, provider, resume, resume_group, selection, tasks, tasks_by_environment, tier, timeout_seconds, trials, trigger, worldplan
Response fields written in the handler: environment, job, org, poll, worldplan
This call changes state in the org.
POST /v0/orgs/{orgtag}/runs/finish
POST /v0/orgs/{org}/runs/finish {job, agent?} — land a stopped run’s finished trials as a run record. 202 and a job to poll.
Path parameters:
orgtag
Body fields the handler or its helper reads: agent, job
Response fields written in the handler: group, job, landed, landing, note, poll, run, stages
This call changes state in the org.
GET /v0/orgs/{orgtag}/runs/groups
This org’s run groups, newest first, each with its status and counts.
Path parameters:
orgtag
Query parameters the handler or its helper reads: retired
Response fields written in the helper the handler answers through: as_of, behind (added to a stored record whose own keys are not in the source)
GET /v0/orgs/{orgtag}/runs/live
GET /v0/orgs/{org}/runs/live — every live run and group of this org, and those that ended in the last LIVE_RECENT_S, each as jobs_live answers it: the Runner’s Runs tab in one read.
Path parameters:
orgtag
Response fields written in the handler: now, org, runs
GET /v0/orgs/{orgtag}/runs/compare
Two run groups side by side, per environment and task: ?a=<group>&b=<group>. Met of N per arm, the delta, the calls that differ by trial and sequence, and a refusal with its reason for any task the two did not run under the same terms (held in one and not the other, absent from one). A READER over stored records, like the roll-up: nothing is re-graded, re-run or re-priced. Either group of another org answers as one that does not exist.
Path parameters:
orgtag
Query parameters the handler or its helper reads: a, b, format, main
Response: A file, not JSON: text/markdown.
POST /v0/orgs/{orgtag}/runs/providers
POST …/runs/providers {environment, tasks?, pins?, trials, timeout_seconds?}.
Path parameters:
orgtag
Body fields the handler or its helper reads: by, environment, pins, tasks, timeout_seconds, trials
Response fields written in the handler: comparison, environment, groups, org, poll
This call changes state in the org.
GET /v0/orgs/{orgtag}/providers
GET …/providers: the pins a comparison can run, each with whether the workspace holds its provider’s key (by name) and whether its model has a price row. model is staff-only (_member_reader).
Path parameters:
orgtag
Query parameters the handler or its helper reads: audience
Response fields written in the handler: harness, org, pins
GET /v0/orgs/{orgtag}/comparisons
GET …/comparisons: this org’s provider comparisons, newest first — id, when, the environment’s label, the pins by label, how many tasks, and the status their groups add up to.
Path parameters:
orgtag
Response fields written in the helper the handler answers through: comparisons, org
GET /v0/orgs/{orgtag}/comparisons/{pcid}
GET …/comparisons/{id}: the pins side by side — per pin its status, trials by terminal state, met of valid, cost and cost per met trial, latency — and one row per task with a cell per pin (providercompare.read). A reader over the groups’ stored records; read on request, because it is two or three groups of one environment, not the org’s every group. ?base=<pin id> names the Base column every other pin is graded against; absent or unknown, the first.
Path parameters:
orgtag, pcid
Query parameters the handler or its helper reads: audience, base
Response: JSON: a stored record or a helper’s result, answered as it is, so its keys are not written in the source and none are listed.
GET /v0/orgs/{orgtag}/runs/clean
The kept clean run per dataset: for each environment, the most recent group the org’s PRIMARY agent ran that finished, landed every environment and has every trial valid. A read over what exists — no scheduling, no spend — so a demo opens a run that exists instead of starting one live. An org with no primary agent gets none, and says so.
Path parameters:
orgtag
Response fields written in the helper the handler answers through: org, rule, tier (added to a stored record whose own keys are not in the source)
GET /v0/orgs/{orgtag}/runs/last/{env}
A sandbox’s last landed run group, as its met / total.
Path parameters:
orgtag, env
Response: JSON: a stored record or a helper’s result, answered as it is, so its keys are not written in the source and none are listed.
GET /v0/orgs/{orgtag}/runs/group/{gid}
One group, rolled up per SUCCESS CRITERION — “how their surface did”.
Path parameters:
orgtag, gid
Response fields written in the helper the handler answers through: group (added to a stored record whose own keys are not in the source)
GET /v0/orgs/{orgtag}/runs/group/{gid}/versions
GET /v0/orgs/{org}/runs/group/{gid}/versions: the versions this group’s tasks can run on — every agent version of its agent and, for a surface agent, every surface version — each with runnable, how many tasks and environments it would run, and the refusal sentence runs/start {group, agent_version} would give. A reader: nothing is started, written or priced. No model string.
Path parameters:
orgtag, gid
Response: JSON: a stored record or a helper’s result, answered as it is, so its keys are not written in the source and none are listed.
POST /v0/orgs/{orgtag}/runs/group/{gid}/recount
POST …/runs/group/{gid}/recount: count a landed group again against the LIVE review and keys. 200 with, per landed record, the count record written and its numbers before and after.
Path parameters:
orgtag, gid
Response fields written in the handler: counted_at, counts, group, model_calls, org, skipped, tier, words
This call changes state in the org.
GET /v0/orgs/{orgtag}/runs/group/{gid}/recount
GET …/runs/group/{gid}/recount: every count of a group’s landed records, oldest first — the one each landed with, under its own stamp, then each re-count — with each count’s numbers and which one the pages read (read, the newest). A reader; nothing is counted here.
Path parameters:
orgtag, gid
Response fields written in the helper the handler answers through: group, org, runs, tier
POST /v0/orgs/{orgtag}/runs/group/{gid}/regrade
POST …/runs/group/{gid}/regrade: re-grade a landed eval from its stored tries at the deterministic tier, with no agent and no judge. 200 with the version written, per run, and the checks that moved against the version before it.
Path parameters:
orgtag, gid
Response fields written in the handler: changed, cost_usd, graded_at, group, model_calls, moved, org, runs, skipped, tier, trials_started, versions
This call changes state in the org.
GET /v0/orgs/{orgtag}/runs/group/{gid}/regrade
GET …/runs/group/{gid}/regrade: an eval’s verdict versions, read. Per run, every version written beside it, oldest first, and the checks that moved between the newest two; ?version=<n> also returns each try’s checks at version n, so an earlier version stays readable. A reader: nothing is graded here. A group never re-graded answers versions: 0.
Path parameters:
orgtag, gid
Query parameters the handler or its helper reads: version
Response fields written in the helper the handler answers through: changed, group, moved, org, runs, skipped, tier, versions
GET /v0/orgs/{orgtag}/runs/group/{gid}/levels
GET /v0/orgs/{org}/runs/group/{gid}/levels: the group at three levels (the call works / the right call / the job got done), its failures grouped by a root cause a record names, and one improvement report per audience written by rule (runlevels). A reader over stored runs.
Path parameters:
orgtag, gid
Response: JSON: a stored record or a helper’s result, answered as it is, so its keys are not written in the source and none are listed.
POST /v0/orgs/{orgtag}/runs
Import one exported run bundle into this org. The body is the bundle as litmus export wrote it; the record keeps it whole under this org.
Path parameters:
orgtag
Body fields the handler or its helper reads: diagnosis, findings, meta, observations, run_id, summary, trials, usage
Response fields written in the helper the handler answers through: by_state, cost, created_at, environment, finding_tiers, findings, group, id, imported_at, meta, org, run_id, summary, tasks_held, tier, trials (added to a stored record whose own keys are not in the source)
This call changes state in the org.
GET /v0/orgs/{orgtag}/runs
This org’s imported runs, newest import first.
Path parameters:
orgtag
Query parameters the handler or its helper reads: group, retired
Response fields written in the handler: jobs, runs
GET /v0/runs/{rid}
One imported run, whole: the bundle as litmus export wrote it, plus the org it was imported under (which record:runs:rid guards on).
Path parameters:
rid
Response fields written in the helper the handler answers through: takeaways (added to a stored record whose own keys are not in the source)
POST /v0/orgs/{orgtag}/runs/{rid}/publish
Publish one stored run’s transcripts to LangFuse. 200 with what the exporter reported, or 200 with status: "not configured" naming the variables that are unset.
Path parameters:
orgtag, rid
Response fields written in the handler: missing, note, run, status
This call changes state in the org.
GET /v0/orgs/{orgtag}/runs/{rid}/trace
One trial of a stored run as a span tree, priced per span.
Path parameters:
orgtag, rid
Query parameters the handler or its helper reads: trial
Response fields written in the handler: run, tree, trials
POST /v0/orgs/{orgtag}/runs/{rid}/reanalyze
Re-analyse one stored run from the directory already on disk. 200 with counts: findings by about, observations by about, citations resolving, before and after.
Path parameters:
orgtag, rid
Response fields written in the handler: after, analyst_findings_kept, before, behavioural_findings, citations, diagnosis, environment, group, reanalyzed_at, run, run_id, state_on_disk, trials_started
This call changes state in the org.
GET /v0/jobs
?org= narrows to one customer, exactly as evidence does; ?org=* is every org, asked for on purpose (_org_scope).
Query parameters the handler or its helper reads:
live, org
Response fields written in the handler: jobs, workspace
GET /v0/jobs/{job_id}
One job. A RUN GROUP is a job too, so job_status follows a matrix with nothing added to it — the group’s status is computed from its children here, because a group owns no task of its own and a stored status would be a claim nobody updates when a child goes stale.
Path parameters:
job_id
Response fields written in the helper the handler answers through: cut, tally (added to the job row)
POST /v0/jobs/{job_id}/stop
Stop a run or a run group: POST /v0/jobs/{id}/stop, body {by?}.
Path parameters:
job_id
Body fields the handler or its helper reads: by
Response fields written in the handler: job, stop
This call changes state in the org.
POST /v0/jobs/{job_id}/cancel
Cancel a generation, a task mint, a derive or an ontology compile: POST /v0/jobs/{id}/cancel, body {by?}.
Path parameters:
job_id
Body fields the handler or its helper reads: by
Response fields written in the handler: cancel, job, note
This call changes state in the org.
GET /v0/jobs/{job_id}/live
GET /v0/jobs/{id}/live — a run’s or a group’s trials as they start and end, the in-flight trial’s tool calls so far, n of N and the estimate to finish. 400 for a job that is neither.
Path parameters:
job_id
Response: Returns the job row.
GET /v0/jobs/{job_id}/audit
GET /v0/jobs/{id}/audit — the run’s audit log, oldest first: started, each trial’s start and end, stops and who asked, restarts and resumes, the end. ?format=text is the same as a text file to keep. Kinds, ids, counts and times only — never a task’s text.
Path parameters:
job_id
Query parameters the handler or its helper reads: format
Response fields written in the handler: events, id, kind
GET /v0/jobs/{job_id}/calls
GET /v0/jobs/{id}/calls — a run’s or a group’s tries so far, call by call, while it runs: per try, its task (task 07), its try number, each call’s tool and the class of its answer (data, empty, error:<class>, refused, pending), its egress forwarded and refused counts when its tools were a served version, its final answer’s class (answered, said_no_data, refused, none) and the names of the checks it failed; and tally, per pinned version, met, failed, infra and invalid so far. Classes, counts and names only — never a row’s value, a call’s arguments or a task’s text. 400 for a job that is neither a run nor a group.
Path parameters:
job_id
Response fields written in the helper the handler answers through: id, kind, landed, running, status, tally, tier, tries