> ## Documentation Index > Fetch the complete documentation index at: https://docs.litmus.ai/llms.txt > Use this file to discover all available pages before exploring further. # Runs > Starting a run, polling the job it becomes, and reading its results. 31 routes. Every example runs with `LITMUS_URL`, `LITMUS_TOKEN` and `LITMUS_ORG` (your org tag) set in your shell (see [Authentication](/authentication)). A `$NAME` in a path is an id you read from the listing route on this page; a `` 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. | Method | Path | Scope | | - | - | - | | POST | `/v0/orgs/{orgtag}/runs/start` | `push` | | POST | `/v0/orgs/{orgtag}/runs/finish` | `push` | | GET | `/v0/orgs/{orgtag}/runs/groups` | `read` | | GET | `/v0/orgs/{orgtag}/runs/live` | `read` | | GET | `/v0/orgs/{orgtag}/runs/compare` | `read` | | POST | `/v0/orgs/{orgtag}/runs/providers` | `push` | | GET | `/v0/orgs/{orgtag}/providers` | `read` | | GET | `/v0/orgs/{orgtag}/comparisons` | `read` | | GET | `/v0/orgs/{orgtag}/comparisons/{pcid}` | `read` | | GET | `/v0/orgs/{orgtag}/runs/clean` | `read` | | GET | `/v0/orgs/{orgtag}/runs/last/{env}` | `read` | | GET | `/v0/orgs/{orgtag}/runs/group/{gid}` | `read` | | GET | `/v0/orgs/{orgtag}/runs/group/{gid}/versions` | `read` | | POST | `/v0/orgs/{orgtag}/runs/group/{gid}/recount` | `push` | | GET | `/v0/orgs/{orgtag}/runs/group/{gid}/recount` | `read` | | POST | `/v0/orgs/{orgtag}/runs/group/{gid}/regrade` | `push` | | GET | `/v0/orgs/{orgtag}/runs/group/{gid}/regrade` | `read` | | GET | `/v0/orgs/{orgtag}/runs/group/{gid}/levels` | `read` | | POST | `/v0/orgs/{orgtag}/runs` | `push` | | GET | `/v0/orgs/{orgtag}/runs` | `read` | | GET | `/v0/runs/{rid}` | `read` | | POST | `/v0/orgs/{orgtag}/runs/{rid}/publish` | `push` | | GET | `/v0/orgs/{orgtag}/runs/{rid}/trace` | `read` | | POST | `/v0/orgs/{orgtag}/runs/{rid}/reanalyze` | `push` | | GET | `/v0/jobs` | `read` | | GET | `/v0/jobs/{job_id}` | `read` | | POST | `/v0/jobs/{job_id}/stop` | `push` | | POST | `/v0/jobs/{job_id}/cancel` | `push` | | GET | `/v0/jobs/{job_id}/live` | `read` | | GET | `/v0/jobs/{job_id}/audit` | `read` | | GET | `/v0/jobs/{job_id}/calls` | `read` | ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/start"]["POST"]` | | CLI | `litmus-ai experiment`, `litmus-ai eval` | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/start" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"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": ""}' ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/finish"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/finish" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"agent": "", "job": ""}' ``` ## `GET /v0/orgs/{orgtag}/runs/groups` This org's run groups, newest first, each with its status and counts. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/groups"]["GET"]` | | CLI | — | **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) ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/groups" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/live"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Response fields written in the handler:** `now`, `org`, `runs` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/live" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/runs/compare` Two run groups side by side, per environment and task: `?a=&b=`. 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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/compare"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `a`, `b`, `format`, `main` **Response:** A file, not JSON: `text/markdown`. ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/compare" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/runs/providers` `POST …/runs/providers {environment, tasks?, pins?, trials, timeout_seconds?}`. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/providers"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/providers" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": "", "environment": "", "pins": "", "tasks": "", "timeout_seconds": "", "trials": ""}' ``` ## `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`). | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/providers"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `audience` **Response fields written in the handler:** `harness`, `org`, `pins` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/providers" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/comparisons"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Response fields written in the helper the handler answers through:** `comparisons`, `org` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/comparisons" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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=` names the Base column every other pin is graded against; absent or unknown, the first. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/comparisons/{pcid}"]["GET"]` | | CLI | — | **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. ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/comparisons/$PCID" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/clean"]["GET"]` | | CLI | — | **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) ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/clean" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/runs/last/{env}` A sandbox's last landed run group, as its met / total. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/last/{env}"]["GET"]` | | CLI | — | **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. ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/last/$ENV" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/runs/group/{gid}` One group, rolled up per SUCCESS CRITERION — *"how their surface did"*. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}"]["GET"]` | | CLI | — | **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) ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/versions"]["GET"]` | | CLI | — | **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. ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/versions" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/recount"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/recount" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/recount"]["GET"]` | | CLI | — | **Path parameters:** `orgtag`, `gid` **Response fields written in the helper the handler answers through:** `group`, `org`, `runs`, `tier` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/recount" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/regrade"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/regrade" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `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=` 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`. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/regrade"]["GET"]` | | CLI | — | **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` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/regrade" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/group/{gid}/levels"]["GET"]` | | CLI | — | **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. ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/group/$GID/levels" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"diagnosis": "", "findings": "", "meta": "", "observations": "", "run_id": "", "summary": "", "trials": "", "usage": ""}' ``` ## `GET /v0/orgs/{orgtag}/runs` This org's imported runs, newest import first. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs"]["GET"]` | | CLI | `litmus-ai experiment` | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `group`, `retired` **Response fields written in the handler:** `jobs`, `runs` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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). | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/runs/{rid}"]["GET"]` | | CLI | `litmus-ai experiment` | **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) ```bash theme={null} curl -sS "$LITMUS_URL/v0/runs/$RID" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/{rid}/publish"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `rid` **Response fields written in the handler:** `missing`, `note`, `run`, `status` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/$RID/publish" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `GET /v0/orgs/{orgtag}/runs/{rid}/trace` One trial of a stored run as a span tree, priced per span. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/{rid}/trace"]["GET"]` | | CLI | — | **Path parameters:** `orgtag`, `rid` **Query parameters the handler or its helper reads:** `trial` **Response fields written in the handler:** `run`, `tree`, `trials` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/$RID/trace" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 | | Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/runs/{rid}/reanalyze"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/runs/$RID/reanalyze" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `GET /v0/jobs` `?org=` narrows to one customer, exactly as evidence does; `?org=*` is every org, asked for on purpose (`_org_scope`). | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | your token: the handler answers your org's rows only | | Policy row | `apitokens.POLICY["/v0/jobs"]["GET"]` | | CLI | `litmus-ai status` | **Query parameters the handler or its helper reads:** `live`, `org` **Response fields written in the handler:** `jobs`, `workspace` ```bash theme={null} curl -sS "$LITMUS_URL/v0/jobs" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}"]["GET"]` | | CLI | `litmus-ai serve`, `litmus-ai experiment` | **Path parameters:** `job_id` **Response fields written in the helper the handler answers through:** `cut`, `tally` (added to the job row) ```bash theme={null} curl -sS "$LITMUS_URL/v0/jobs/$JOB_ID" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/jobs/{job_id}/stop` Stop a run or a run group: `POST /v0/jobs/{id}/stop`, body `{by?}`. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}/stop"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/jobs/$JOB_ID/stop" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": ""}' ``` ## `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?}`. | | | | - | - | | Token scope | `push` or `admin` | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}/cancel"]["POST"]` | | CLI | — | **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. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/jobs/$JOB_ID/cancel" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": ""}' ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}/live"]["GET"]` | | CLI | — | **Path parameters:** `job_id` **Response:** Returns the job row. ```bash theme={null} curl -sS "$LITMUS_URL/v0/jobs/$JOB_ID/live" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}/audit"]["GET"]` | | CLI | — | **Path parameters:** `job_id` **Query parameters the handler or its helper reads:** `format` **Response fields written in the handler:** `events`, `id`, `kind` ```bash theme={null} curl -sS "$LITMUS_URL/v0/jobs/$JOB_ID/audit" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `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:`, `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. | | | | - | - | | Token scope | `read` (any org token) | | Org comes from | the stored record the path names; another org's id answers 404, as an unknown one does | | Policy row | `apitokens.POLICY["/v0/jobs/{job_id}/calls"]["GET"]` | | CLI | — | **Path parameters:** `job_id` **Response fields written in the helper the handler answers through:** `id`, `kind`, `landed`, `running`, `status`, `tally`, `tier`, `tries` ```bash theme={null} curl -sS "$LITMUS_URL/v0/jobs/$JOB_ID/calls" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.