> ## 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.

# Sandboxes

> The fakes: surfaces, environments and their tasks, the worlds they serve, and re-drawing them.

88 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 `<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.

| Method | Path | Scope |
| - | - | - |
| GET | `/v0/bundles` | `read` |
| GET | `/v0/bundles/{bundle_id}/manifest` | `read` |
| GET | `/v0/bundles/{bundle_id}/axes` | `read` |
| POST | `/v0/orgs/{orgtag}/apidoor` | `push` |
| GET | `/v0/orgs/{orgtag}/apidoor` | `read` |
| POST | `/v0/orgs/{orgtag}/sandboxes/{sid}/door` | `push` |
| GET | `/v0/orgs/{orgtag}/sandboxes/{sid}/door` | `read` |
| DELETE | `/v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}` | `push` |
| POST | `/v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}/reset` | `push` |
| GET | `/v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}/tally` | `read` |
| POST | `/v0/orgs/{orgtag}/served-repo` | `push` |
| GET | `/v0/orgs/{orgtag}/served-repo` | `read` |
| GET | `/v0/orgs/{orgtag}/served-repo/{rid}` | `read` |
| GET | `/v0/orgs/{orgtag}/served-repo/{rid}/read` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/turns` | `push` |
| GET | `/v0/orgs/{orgtag}/surfaces` | `read` |
| GET | `/v0/orgs/{orgtag}/surfaces/{surface}/representation` | `read` |
| GET | `/v0/orgs/{orgtag}/surfaces/{surface}/progress` | `read` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/world/redraw` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/rebuild` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/world/revert` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/supersede` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/unsupersede` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/retire` | `push` |
| POST | `/v0/orgs/{orgtag}/surfaces/{surface}/restore` | `push` |
| GET | `/v0/orgs/{orgtag}/retired` | `read` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/revisions` | `read` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/revisions/{rev}` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/revisions/{rev}/restore` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/generate` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/for-criteria` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/retire` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/restore` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/tasks` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/tasks/retire` | `admin` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/tasks/restore` | `admin` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/surface-key` | `read` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/tools` | `read` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/fidelity` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/fidelity/answer-shapes` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/tasks` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/checks` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/checks/{n}/rehearse` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/scripts/starter` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/scripts/dry-run` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/scripts` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/scripts` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/realism` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/realism` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/world/refresh` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/world/table` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/review/regenerate` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/revoice` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/rekey` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/review/hold` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/review/rereview` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/review/correct` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/regate` | `push` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/reserve` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/review` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/review` | `push` |
| GET | `/v0/orgs/{orgtag}/environments/{env_id}/audit` | `read` |
| POST | `/v0/orgs/{orgtag}/environments/{env_id}/audit` | `push` |
| POST | `/v0/orgs/{orgtag}/worldplans/from-surface` | `push` |
| GET | `/v0/worldplans` | `read` |
| GET | `/v0/worldplans/{wid}` | `read` |
| PATCH | `/v0/worldplans/{wid}` | `push` |
| DELETE | `/v0/worldplans/{wid}` | `push` |
| GET | `/v0/worldplans/{wid}/harbor` | `read` |
| GET | `/v0/orgs/{orgtag}/sandboxes` | `read` |
| POST | `/v0/orgs/{orgtag}/sandboxes` | `push` |
| GET | `/v0/orgs/{orgtag}/realism/packet` | `read` |
| GET | `/v0/orgs/{orgtag}/realism` | `read` |
| POST | `/v0/orgs/{orgtag}/realism` | `push` |
| GET | `/v0/sandboxes/{sid}` | `read` |
| DELETE | `/v0/sandboxes/{sid}` | `push` |
| POST | `/v0/surfaces` | `push` |
| POST | `/v0/worlds` | `push` |
| GET | `/v0/worlds` | `read` |
| POST | `/v0/worlds/{bundle_id}/{world}/check` | `read` |
| POST | `/v0/worlds/{bundle_id}/{world}/reset` | `push` |
| GET | `/v0/worlds/{bundle_id}/{world}/state` | `read` |
| GET | `/v0/worlds/{bundle_id}/{world}/peek` | `read` |
| GET | `/v0/worlds/{bundle_id}/{world}/tools` | `read` |
| POST | `/v0/worlds/{bundle_id}/{world}/call` | `push` |
| POST | `/v0/tokens` | `push` |
| DELETE | `/v0/tokens/{tid}` | `push` |

## `GET /v0/bundles`

The gallery, as whoever is asking may see it.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | your token: the handler answers your org's rows only |
| Policy row | `apitokens.POLICY["/v0/bundles"]["GET"]` |
| CLI | `litmus-ai status` |

**Query parameters the handler or its helper reads:** `org`

**Response fields written in the handler:** `bundles`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/bundles" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/bundles/{bundle_id}/manifest`

The bundle's tool registry — exactly what an agent sees on tools/list.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/bundles/{bundle_id}/manifest"]["GET"]` |
| CLI | — |

**Path parameters:** `bundle_id`

**Response fields written in the handler:** `bundle_id`, `readonly_tools`, `tool_count`, `tools`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/bundles/$BUNDLE_ID/manifest" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/bundles/{bundle_id}/axes`

The admitted parameter axes for a bundle — the knobs a world can be designed with (deterministic; same machinery as profiles).

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/bundles/{bundle_id}/axes"]["GET"]` |
| CLI | — |

**Path parameters:** `bundle_id`

**Response fields written in the helper the handler answers through:** `available`, `awaiting_customer_data`, `axes`, `reason`, `rejected`, `sample_vectors`, `tier`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/bundles/$BUNDLE_ID/axes" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/apidoor`

Compile and serve an org's API door from evidence the workspace holds.

| | |
| - | - |
| 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}/apidoor"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `bundle_id`, `capture`, `description_overrides`, `grammar`, `quota_limit`

**Response fields written in the helper the handler answers through:** `bundle_id`, `census`, `compile`, `id`, `note`, `org`, `recompiled`, `reused_token`, `token_id`, `tool_names`, `world` (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/apidoor" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "<bundle_id>", "capture": "<capture>", "description_overrides": "<description_overrides>", "grammar": "<grammar>", "quota_limit": "<quota_limit>"}'
```

## `GET /v0/orgs/{orgtag}/apidoor`

What API doors this org has: bundle id, the worlds served, and for each world the base URL a wrapper points its upstream at beside the gaps URL it must be handed with.

| | |
| - | - |
| 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}/apidoor"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Response fields written in the helper the handler answers through:** `doors`, `org`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/apidoor" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/sandboxes/{sid}/door`

Mint a hosted door for this sandbox: its API mock on a public URL.

| | |
| - | - |
| 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}/sandboxes/{sid}/door"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `sid`

**Body fields the handler or its helper reads:** `label`, `version`

**Response fields written in the handler:** `door`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes/$SID/door" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "<label>", "version": "<version>"}'
```

## `GET /v0/orgs/{orgtag}/sandboxes/{sid}/door`

This sandbox's hosted doors, oldest first, revoked ones included with their `revoked_at`: a door somebody just killed has to be seen dead.

| | |
| - | - |
| 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}/sandboxes/{sid}/door"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `sid`

**Response fields written in the handler:** `doors`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes/$SID/door" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `DELETE /v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}`

Revoke one door. One-way (`worldtokens.revoke`): the URL answers the serving plane's one 404 from the next request, and its tally is written down as it stood.

| | |
| - | - |
| 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}/sandboxes/{sid}/door/{tid}"]["DELETE"]` |
| CLI | — |

**Path parameters:** `orgtag`, `sid`, `tid`

**Response fields written in the handler:** `door`

This call changes state in the org.

```bash theme={null}
curl -sS -X DELETE "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes/$SID/door/$TID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}/reset`

Put the door's world back to the state it was drawn at — the same answer `<door>/_litmus/reset` gives the token holder.

| | |
| - | - |
| 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}/sandboxes/{sid}/door/{tid}/reset"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `sid`, `tid`

**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.

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes/$SID/door/$TID/reset" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v0/orgs/{orgtag}/sandboxes/{sid}/door/{tid}/tally`

What this door has answered: counts by route template and status, unserved requests by method, how many the limit refused and how many resets. Never a body, a query string, a path or an id.

| | |
| - | - |
| 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}/sandboxes/{sid}/door/{tid}/tally"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `sid`, `tid`

**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/sandboxes/$SID/door/$TID/tally" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/served-repo`

Connect a customer's own MCP server as a `served_repo` surface.

| | |
| - | - |
| 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}/served-repo"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Query parameters the handler or its helper reads:** `wait`

**Body fields the handler or its helper reads:** `door`, `installation`, `token_env`, `url`

**Response fields written in the handler:** `job`, `poll`, `record`, `stages`, `state`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/served-repo" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"door": "<door>", "installation": "<installation>", "token_env": "<token_env>", "url": "<url>"}'
```

## `GET /v0/orgs/{orgtag}/served-repo`

This org's served repositories: pins and counts only, each with its `state` — `connecting`, `connected` or `refused`.

| | |
| - | - |
| 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}/served-repo"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Response fields written in the handler:** `org`, `served_repos`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/served-repo" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/served-repo/{rid}`

One registration's status read: the listing's row for it — `connecting` with the stages finished and their seconds, `connected` with its counts, or `refused` with the redacted refusal. A read token's route, redacted as the listing is; a record 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}/served-repo/{rid}"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `rid`

**Response fields written in the helper the handler answers through:** `commit`, `connected_at`, `door`, `egress`, `held`, `id`, `job`, `kind`, `label`, `manifest_hash`, `operations`, `ref`, `ref_words`, `refusal`, `refused_at`, `removed_at_checkout`, `replaced_earlier`, `response_keys`, `retired_at`, `serving`, `stages`, `state`, `superseded_by`, `surface_id`, `tier`, `transport`, `upstream_env`, `versions`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/served-repo/$RID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/served-repo/{rid}/read`

One served version's client read: the route keys and `field_codes` the door is handed for it, read over its cached checkout (or the read stored at registration) — what a try's door serves codes by, seen without a run. Each route row names the `forms` its read took and, read under no key, a `trace` of where its body went instead, by function name. Names and literals of their source only; a record of another org answers as one that does not exist, as the status read does.

| | |
| - | - |
| 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}/served-repo/{rid}/read"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `rid`

**Response fields written in the helper the handler answers through:** `commit`, `id`, `read`, `ref`, `source`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/served-repo/$RID/read" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/turns`

`POST …/environments/{env}/tasks/{index}/turns` with `{turns, by, note?}`: scripted follow-up user turns on one task (`tasktags.set_turns`). The runner plays them in order; nothing reacts to the agent's answer, and the task says so.

| | |
| - | - |
| 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}/environments/{env_id}/tasks/{index}/turns"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`, `index`

**Body fields the handler or its helper reads:** `by`, `note`, `turns`

**Response fields written in the handler:** `by`, `environment`, `index`, `turns`, `turns_kind`, `turns_tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks/$INDEX/turns" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "note": "<note>", "turns": "<turns>"}'
```

## `GET /v0/orgs/{orgtag}/surfaces`

Every surface this org serves, with the environments it hosts.

| | |
| - | - |
| 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}/surfaces"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Query parameters the handler or its helper reads:** `superseded`

**Response fields written in the helper the handler answers through:** `agent_door`, `hero`, `org`, `previous`, `surfaces`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/surfaces/{surface}/representation`

This surface's representation — what the BUILDER offers and what the ONTOLOGY PAGE shows.

| | |
| - | - |
| 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}/surfaces/{surface}/representation"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Query parameters the handler or its helper reads:** `count`, `limit`, `offset`, `part`, `version`

**Response fields written in the helper the handler answers through:** `ontology_version` (added to a stored record whose own keys are not in the source)

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/representation" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/surfaces/{surface}/progress`

`GET …/surfaces/{surface}/progress` — where the agent started on this system and what it took to get to the last mile: every agent version with a landed run on the system or a declared version of it (`variant_of`), oldest first; per version, per golden path, met / not met / not decided / untested at the weakest tier of its verdicts, with the first version that met it; per known failure mode, the version at which it stopped reproducing; per version, what changed (the run's label, the agent version's notes, or the system's declared change).

| | |
| - | - |
| 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}/surfaces/{surface}/progress"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**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/surfaces/$SURFACE/progress" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/world/redraw`

POST /v0/orgs/\{orgtag}/surfaces/\{surface}/world/redraw.

| | |
| - | - |
| 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}/surfaces/{surface}/world/redraw"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `model`, `reason`, `reauthor`, `regate`, `reobserve`, `revert`, `seed`

**Response fields written in the helper the handler answers through:** `environments_refreshed`, `held_to_observed`, `observed_changed`, `previous_kept`, `reauthor`, `record`, `redrawn`, `regated`, `reobserved`, `resolved_by`, `reverted`, `seed`, `surface`, `tier`, `worlds_reset`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/world/redraw" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>", "reason": "<reason>", "reauthor": "<reauthor>", "regate": "<regate>", "reobserve": "<reobserve>", "revert": "<revert>", "seed": "<seed>"}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/rebuild`

Rebuild a derived surface version in place under the current compiler.

| | |
| - | - |
| 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}/surfaces/{surface}/rebuild"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `mode`, `reason`

**Response fields written in the handler:** `code`, `error`, `surface`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/rebuild" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "<mode>", "reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/world/revert`

POST /v0/orgs/\{orgtag}/surfaces/\{surface}/world/revert.

| | |
| - | - |
| 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}/surfaces/{surface}/world/revert"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `reason`

**Response fields written in the helper the handler answers through:** `environments_refreshed`, `held_to_observed`, `observed_changed`, `previous_kept`, `reauthor`, `record`, `redrawn`, `regated`, `reobserved`, `resolved_by`, `reverted`, `seed`, `surface`, `tier`, `worlds_reset`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/world/revert" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/supersede`

Mark one surface superseded by another this org serves.

| | |
| - | - |
| 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}/surfaces/{surface}/supersede"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `reason`, `superseded_by`

**Response fields written in the handler:** `superseded`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/supersede" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "<reason>", "superseded_by": "<superseded_by>"}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/unsupersede`

Lift a supersession: the surface is listed by default again.

| | |
| - | - |
| 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}/surfaces/{surface}/unsupersede"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Response fields written in the handler:** `restored`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/unsupersede" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/retire`

Take one surface, and every state of it, off this org's pages.

| | |
| - | - |
| 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}/surfaces/{surface}/retire"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `by`, `reason`

**Response fields written in the handler:** `retired`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/retire" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/surfaces/{surface}/restore`

Put a retired surface back on this org's pages.

| | |
| - | - |
| 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}/surfaces/{surface}/restore"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `surface`

**Body fields the handler or its helper reads:** `by`, `reason`

**Response fields written in the handler:** `restored`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/restore" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "reason": "<reason>"}'
```

## `GET /v0/orgs/{orgtag}/retired`

THE OPERATOR VIEW: what this org has retired, and what it was.

| | |
| - | - |
| 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}/retired"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**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/retired" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/revisions`

`GET /v0/orgs/{org}/environments/{env_id}/revisions` — this sandbox's revisions, newest first, at most `afteringest.REVISIONS_LISTED`, each as `GET …/revisions/{rev}` answers it, with `n` (every one it holds). An environment with none answers an empty list. Counts and ids only.

| | |
| - | - |
| 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}/environments/{env_id}/revisions"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the helper the handler answers through:** `environment`, `n`, `revisions`, `tier`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/revisions" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/revisions/{rev}`

`GET /v0/orgs/{org}/environments/{env_id}/revisions/{rev}` — one revision as it stands: its kind and state, the audit's before/after counts (rows that contradict each other, realism flags) with what came out worse and whether the re-draw held, what it kept, and the jobs it ran with each one's cost — priced once ended, its estimate while running. The one number that says a re-draw held was readable only from the pass job's result once the pass ended. 404 for a revision this org or this sandbox does not hold. Counts and ids only; no model call.

| | |
| - | - |
| 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}/environments/{env_id}/revisions/{rev}"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`, `rev`

**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/environments/$ENV_ID/revisions/$REV" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/revisions/{rev}/restore`

`POST /v0/orgs/{org}/environments/{env_id}/revisions/{rev}/restore` — put back what an applied act replaced: the draw, the tasks and the verifiers kept under `rev`. `{reason?}`. The state it replaces is kept as a revision too (`undo` in the answer), so restoring that undoes this. 404 for a revision this org or this sandbox does not hold; 409 while a run, a pipeline, a re-draw or a re-author is live on the sandbox, and for a revision already restored. Counts and ids only.

| | |
| - | - |
| 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}/environments/{env_id}/revisions/{rev}/restore"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`, `rev`

**Body fields the handler or its helper reads:** `by`, `reason`

**Response fields written in the handler:** `error`, `revision`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/revisions/$REV/restore" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/environments/generate`

Generate N environments for one selection of dimension values.

| | |
| - | - |
| 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}/environments/generate"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `bundle`, `count`, `criteria`, `criteria_only`, `exemplars`, `history`, `kind_floor`, `model`, `representation`, `selection`, `situations`, `surface`, `surface_version`, `tasks`, `voice`, `web`

**Response fields written in the helper the handler answers through:** `checks`, `count`, `job`, `note`, `selection`, `stage`, `stages`, `surface`, `surface_version`, `tasks`, `voice`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/generate" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle": "<bundle>", "count": "<count>", "criteria": "<criteria>", "criteria_only": "<criteria_only>", "exemplars": "<exemplars>", "history": "<history>", "kind_floor": "<kind_floor>", "model": "<model>", "representation": "<representation>", "selection": "<selection>", "situations": "<situations>", "surface": "<surface>", "surface_version": "<surface_version>", "tasks": "<tasks>", "voice": "<voice>", "web": "<web>"}'
```

## `POST /v0/orgs/{orgtag}/environments/for-criteria`

POST /v0/orgs/\{org}/environments/for-criteria.

| | |
| - | - |
| 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}/environments/for-criteria"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `criteria`, `dry_run`, `max_new`, `model`, `tasks`, `voice`

**Response fields written in the handler:** `dry_run`, `jobs`, `note`, `refused`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/for-criteria" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"criteria": "<criteria>", "dry_run": "<dry_run>", "max_new": "<max_new>", "model": "<model>", "tasks": "<tasks>", "voice": "<voice>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/retire`

Take one DRAWN STATE off this org's pages.

| | |
| - | - |
| 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}/environments/{env_id}/retire"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `by`, `reason`

**Response fields written in the handler:** `retired`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/retire" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/restore`

Put a retired drawn state back on this org's pages.

| | |
| - | - |
| 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}/environments/{env_id}/restore"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `by`, `reason`

**Response fields written in the handler:** `restored`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/restore" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "reason": "<reason>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/tasks`

This environment's tasks, each with its verifier and what it decides, and `family` on a task a rule-written family wrote.

| | |
| - | - |
| 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}/environments/{env_id}/tasks"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Query parameters the handler or its helper reads:** `audience`, `retired`

**Response fields written in the handler:** `audience`, `caveat`, `check`, `chosen`, `coverage`, `coverage_at_generation`, `dimensions`, `environment`, `evidence_id`, `generations`, `links`, `max_rounds`, `org`, `refused_tasks`, `review_checks`, `review_counts`, `rooted`, `selection`, `serves`, `state`, `suite`, `surface`, `tasks`, `tasks_state`, `tool_gate`, `verifier_health`, `world_missing`, `world_snapshot`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/tasks/retire`

Retire a range of this environment's tasks, by index.

| | |
| - | - |
| Token scope | `admin` |
| Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 |
| Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/environments/{env_id}/tasks/retire"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the helper the handler answers through:** `act`, `environment`, `mark`, `model_calls`, `retired_tasks`, `standing`, `tasks`, `tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks/retire" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/tasks/restore`

Put a retired range back. `{from, to, reason?, by?}`.

| | |
| - | - |
| Token scope | `admin` |
| Org comes from | the `{orgtag}` path segment; a token for another org is refused with 403 |
| Policy row | `apitokens.POLICY["/v0/orgs/{orgtag}/environments/{env_id}/tasks/restore"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the helper the handler answers through:** `act`, `environment`, `mark`, `model_calls`, `retired_tasks`, `standing`, `tasks`, `tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks/restore" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/surface-key`

`GET /v0/orgs/{org}/environments/{env_id}/surface-key` — the surface key run against this sandbox: how many of the fixture's declared behaviours it reproduces (`present`), does not (`absent`), and could not be asked about (`undecidable`), each with the probes behind it, at tier `deterministic`. `undecidable` is its own count and never folds into `absent`. Every probe writes to a scratch copy of the seed; nothing is kept and no model is called. A sandbox that is not this org's answers 404 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}/environments/{env_id}/surface-key"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `environment`, `note`, `org`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/surface-key" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/tools`

`GET /v0/orgs/{org}/environments/{env_id}/tools` — the tools this sandbox serves, by name with a one-line description: what a no-data report's "holds the rows" may name. Read off the bundle's manifest on disk; no world is loaded, no model is called. A sandbox that is not this org's answers 404 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}/environments/{env_id}/tools"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `count`, `environment`, `org`, `read`, `tier`, `tools`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tools" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/fidelity`

`GET /v0/orgs/{org}/environments/{env_id}/fidelity` — how much of the org's real tool surface this sandbox serves: one row per tool of the code at the agent's main, fields served / lacked / invented (each sourced `code` or `sessions`), enum values and relations lacked, `unobserved` for a tool the sessions never call; the fix list ranked by `n_calls`; `terms.coverage` and the line "serves X of N tool shapes by name (deterministic)". Each row is also joined by API route: its `data_source` routes against the sandbox's own observed route map, `layer`, `routes_served` / `routes_of`, the sandbox tools it maps to; `terms.routes` counts the tools with every route served, some, none and no data source, and the line names that layer apart — or says the sandbox has no route map. Where no tool the sessions call is a sandbox tool, `terms.answer_shapes` is `{replayable: 0, reason}` and the line says why. `terms.api_routes`, the code's distinct `data_source` routes the sandbox's API door serves ("K of M API routes served", the unserved ones named), absent when the code names no route. Files on disk only; no model, no write. 404 `no_tool_listing` when no agent of the org has a listing; a sandbox not this org's answers 404 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}/environments/{env_id}/fidelity"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**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/environments/$ENV_ID/fidelity" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/fidelity/answer-shapes`

`POST /v0/orgs/{org}/environments/{env_id}/fidelity/answer-shapes` — `{dry_run?, model?}`.

| | |
| - | - |
| 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}/environments/{env_id}/fidelity/answer-shapes"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `dry_run`, `model`

**Response fields written in the handler:** `differ`, `environment`, `model`, `n`, `of`, `org`, `replayed`, `stored`, `surface`, `tier`, `tools`, `world`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/fidelity/answer-shapes" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": "<dry_run>", "model": "<model>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}`

One environment and its `realism` block: how far its written requests sit from the real requests of what it was generated under — numbers, each with its tier and n, never a request. The deterministic measures are read now over the tasks it holds; the attribute distance is the one its generation stored, and an environment minted before exemplars existed says it has none (the "no exemplar" arm).

| | |
| - | - |
| 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}/environments/{env_id}"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `environment`, `org`, `persona_draw`, `realism`, `redraw`, `revertable`, `state`, `suite`, `surface`, `tasks`, `world_columns`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/tasks`

Generate `count` more tasks on this environment and APPEND them; or, with `{goal: {mode, n, voice?, max_turns?, usd_cap?, personas?, fallback?, from_sessions?}}`, have the Litmus agent write `n` tasks that reproduce one failure mode, as a job, the rule writing only as its labelled fallback.

| | |
| - | - |
| 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}/environments/{env_id}/tasks"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `count`, `criteria`, `dimensions`, `failure_mode`, `families`, `from_pairs`, `goal`, `label`, `ladder`, `model`, `pairs`, `review`, `tool`, `voice`

**Response fields written in the handler:** `count`, `coverage`, `criteria`, `criteria_named`, `criterion_ids`, `dimensions`, `environment`, `floor_first`, `have`, `job`, `kind_floor`, `note`, `stages`, `state`, `suite`, `voice`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"count": "<count>", "criteria": "<criteria>", "dimensions": "<dimensions>", "failure_mode": "<failure_mode>", "families": "<families>", "from_pairs": "<from_pairs>", "goal": "<goal>", "label": "<label>", "ladder": "<ladder>", "model": "<model>", "pairs": "<pairs>", "review": "<review>", "tool": "<tool>", "voice": "<voice>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/checks`

WHAT RUNS FOR EACH CHECK ON ONE TASK, verbatim: the deterministic read as executed, or the judge's full prompt as sent with the pinned model and the "asked twice" rule — and the last run's verdicts on it, with the read's result or both of the judge's answers.

| | |
| - | - |
| 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}/environments/{env_id}/tasks/{index}/checks"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`, `index`

**Response fields written in the handler:** `org`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks/$INDEX/checks" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/tasks/{index}/checks/{n}/rehearse`

RUN ONE CHECK ON ONE STORED TRIAL, AS A REHEARSAL: `{trial}`.

| | |
| - | - |
| 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}/environments/{env_id}/tasks/{index}/checks/{n}/rehearse"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`, `index`, `n`

**Response fields written in the handler:** `calls`, `check`, `cost`, `environment`, `index`, `org`, `rehearsal`, `run`, `stored`, `trial`, `verdict`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/tasks/$INDEX/checks/$N/rehearse" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/scripts/starter`

GET /v0/orgs/\{org}/environments/\{env}/scripts/starter → `{script, from: {site, form}}`: a `.spec.ts` written from the sign-up journey on this environment's own household web — log in with the account's own credential (a `process.env` line, never a value), fill the form, submit, expect the page the site answers with. It passes its own dry run.

| | |
| - | - |
| 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}/environments/{env_id}/scripts/starter"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `environment`, `org`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/scripts/starter" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/scripts/dry-run`

POST /v0/orgs/\{org}/environments/\{env}/scripts/dry-run `{source}` → the script parsed, compiled and replayed once in a real browser on this environment's own world (drawn with its household web into a temp dir), its checks graded on the captured trace and on an empty one: `{steps, checks, noop, facts, events, gate, compiled, parse: {refused}}`.

| | |
| - | - |
| 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}/environments/{env_id}/scripts/dry-run"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `source`

**Response fields written in the handler:** `environment`, `org`, `provider_run`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/scripts/dry-run" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "<source>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/scripts`

GET /v0/orgs/\{org}/environments/\{env}/scripts → `{scripts: [{task, name, title, sha256, checks_n, created_at}]}`: the script tasks on this environment, never their source. A kept read: nothing is drawn or run.

| | |
| - | - |
| 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}/environments/{env_id}/scripts"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `environment`, `org`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/scripts" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/scripts`

POST /v0/orgs/\{org}/environments/\{env}/scripts `{source, name?}` — a Playwright script made a task on this environment.

| | |
| - | - |
| 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}/environments/{env_id}/scripts"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `name`, `source`

**Response fields written in the handler:** `checks`, `environment`, `facts`, `gate`, `note`, `org`, `provider_run`, `task`, `web_added`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/scripts" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "<name>", "source": "<source>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/realism`

The human marks on this environment: the whole thing, and per task.

| | |
| - | - |
| 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}/environments/{env_id}/realism"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `entities`, `environment`, `flags`, `grader_kinds`, `n_rule`, `org`, `placed_feedback`, `realism`, `split`, `state`, `surface`, `tier`, `verdicts`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/realism" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/realism`

Mark this environment — or one task of it, or one table or column of its world — realistic / not / unsure.

| | |
| - | - |
| 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}/environments/{env_id}/realism"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `column`, `grader`, `grader_kind`, `grader_side`, `origin`, `reason`, `scope`, `source`, `table`, `task_index`, `verdict`

**Response fields written in the handler:** `feedback`, `hold`, `mark`, `realism`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/realism" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"column": "<column>", "grader": "<grader>", "grader_kind": "<grader_kind>", "grader_side": "<grader_side>", "origin": "<origin>", "reason": "<reason>", "scope": "<scope>", "source": "<source>", "table": "<table>", "task_index": "<task_index>", "verdict": "<verdict>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/world/refresh`

POST /v0/orgs/\{orgtag}/environments/\{env\_id}/world/refresh — re-snapshot.

| | |
| - | - |
| 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}/environments/{env_id}/world/refresh"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `environment`, `org`, `surface`, `world_snapshot`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/world/refresh" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/world/table`

GET /v0/orgs/\{orgtag}/environments/\{env\_id}/world/table?table=\[\&limit=]

| | |
| - | - |
| 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}/environments/{env_id}/world/table"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `bound`, `environment`, `org`, `surface`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/world/table" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/review/regenerate`

Re-author the HELD tasks with the failing reasons in the brief: `{model?}`.

| | |
| - | - |
| 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}/environments/{env_id}/review/regenerate"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `model`, `only`

**Response fields written in the handler:** `environment`, `held`, `job`, `max_rounds`, `note`, `only`, `reauthoring`, `round`, `stages`, `surface`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/review/regenerate" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>", "only": "<only>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/revoice`

Re-voice tasks: `{voice, tasks: [index, …], model?, review?}`.

| | |
| - | - |
| 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}/environments/{env_id}/revoice"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `model`, `review`, `tasks`, `voice`

**Response fields written in the handler:** `environment`, `job`, `note`, `review`, `stages`, `surface`, `tasks`, `voice`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/revoice" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>", "review": "<review>", "tasks": "<tasks>", "voice": "<voice>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/rekey`

Key this environment's tasks to every criterion their keys decide: `{}`. One model call over the task set, or one per page of tasks when the reply could outgrow one call; answers a job.

| | |
| - | - |
| 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}/environments/{env_id}/rekey"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the handler:** `criteria`, `environment`, `job`, `note`, `pages`, `stages`, `surface`, `tasks`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/rekey" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/review/hold`

A PERSON holds one task: `{index, reason, grader, grader_kind?}`.

| | |
| - | - |
| 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}/environments/{env_id}/review/hold"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `grader`, `grader_kind`, `index`, `reason`

**Response fields written in the handler:** `counts`, `environment`, `hold`, `tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/review/hold" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grader": "<grader>", "grader_kind": "<grader_kind>", "index": "<index>", "reason": "<reason>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/review/rereview`

Re-review the HELD tasks on this environment: `{indexes?, model?}`.

| | |
| - | - |
| 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}/environments/{env_id}/review/rereview"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `indexes`, `model`

**Response fields written in the handler:** `environment`, `job`, `note`, `rereviewed`, `stages`, `surface`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/review/rereview" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"indexes": "<indexes>", "model": "<model>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/review/correct`

A PERSON corrects one task's expected fact: `{index, fact, literal?, aliases?, fact_text?, note, grader, grader_kind?}`.

| | |
| - | - |
| 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}/environments/{env_id}/review/correct"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `aliases`, `fact`, `fact_text`, `grader`, `grader_kind`, `index`, `literal`, `note`

**Response fields written in the helper the handler answers through:** `counts`, `environment`, `fact_index`, `index`, `model_calls`, `tier` (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/environments/$ENV_ID/review/correct" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aliases": "<aliases>", "fact": "<fact>", "fact_text": "<fact_text>", "grader": "<grader>", "grader_kind": "<grader_kind>", "index": "<index>", "literal": "<literal>", "note": "<note>"}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/regate`

Re-gate this environment's standing tasks on the world it serves NOW.

| | |
| - | - |
| 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}/environments/{env_id}/regate"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**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.

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/regate" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/reserve`

POST /v0/orgs/\{org}/environments/\{env\_id}/reserve — `{surface: B}`.

| | |
| - | - |
| 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}/environments/{env_id}/reserve"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `surface`

**Response fields written in the handler:** `checks`, `environment`, `job`, `note`, `poll`, `source_surface`, `stage`, `stages`, `surface`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/reserve" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"surface": "<surface>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/review`

This environment's review: five verdicts per task, and the 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}/environments/{env_id}/review"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Query parameters the handler or its helper reads:** `format`

**Response fields written in the handler:** `asks`, `checks`, `counts`, `environment`, `max_rounds`, `org`, `replaced_tasks`, `suite`, `surface`, `tasks`, `tier`, `verdicts`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/review" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/review`

Review every task on this environment: `{model?}`.

| | |
| - | - |
| 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}/environments/{env_id}/review"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `force`, `model`

**Response fields written in the handler:** `asks`, `checks`, `environment`, `force`, `job`, `note`, `stages`, `surface`, `tasks`, `tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/review" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": "<force>", "model": "<model>"}'
```

## `GET /v0/orgs/{orgtag}/environments/{env_id}/audit`

GET /v0/orgs/\{orgtag}/environments/\{env\_id}/audit — the stored report.

| | |
| - | - |
| 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}/environments/{env_id}/audit"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Response fields written in the helper the handler answers through:** `human_flags` (added to a stored record whose own keys are not in the source)

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/audit" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/environments/{env_id}/audit`

POST /v0/orgs/\{orgtag}/environments/\{env\_id}/audit — `{model?}`.

| | |
| - | - |
| 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}/environments/{env_id}/audit"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `env_id`

**Body fields the handler or its helper reads:** `model`

**Response fields written in the handler:** `environment`, `job`, `rubric`, `stages`, `surface`, `tier`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/environments/$ENV_ID/audit" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>"}'
```

## `POST /v0/orgs/{orgtag}/worldplans/from-surface`

Generate tasks on a served surface: `{bundle, count?, label?, model?}`.

| | |
| - | - |
| 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}/worldplans/from-surface"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `bundle`, `count`, `dimensions`, `label`, `model`

**Response fields written in the handler:** `bundle`, `count`, `environment`, `job`, `note`, `stages`, `suite`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/worldplans/from-surface" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle": "<bundle>", "count": "<count>", "dimensions": "<dimensions>", "label": "<label>", "model": "<model>"}'
```

## `GET /v0/worldplans`

One page of plans, newest first, with the count and the cursor.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the `org` query parameter; forced to your token's org |
| Policy row | `apitokens.POLICY["/v0/worldplans"]["GET"]` |
| CLI | — |

**Query parameters the handler or its helper reads:** `after`, `all`, `limit`, `offset`, `org`

**Response fields written in the handler:** `next`, `total`, `worldplans`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worldplans?org=$LITMUS_ORG" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/worldplans/{wid}`

No description: the handler has no docstring, and nothing here is inferred.

| | |
| - | - |
| 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/worldplans/{wid}"]["GET"]` |
| CLI | — |

**Path parameters:** `wid`

**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/worldplans/$WID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `PATCH /v0/worldplans/{wid}`

Edit a plan's label or tasks — the primitives that make generated task sets auditable AND ownable: a person can rewrite a task, drop one, or trim an expectation, and the artifact is theirs from then on.

| | |
| - | - |
| 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/worldplans/{wid}"]["PATCH"]` |
| CLI | — |

**Path parameters:** `wid`

**Body fields the handler or its helper reads:** `label`, `tasks`

**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.

This call changes state in the org.

```bash theme={null}
curl -sS -X PATCH "$LITMUS_URL/v0/worldplans/$WID" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "<label>", "tasks": "<tasks>"}'
```

## `DELETE /v0/worldplans/{wid}`

No description: the handler has no docstring, and nothing here is inferred.

| | |
| - | - |
| 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/worldplans/{wid}"]["DELETE"]` |
| CLI | — |

**Path parameters:** `wid`

**Response fields written in the handler:** `deleted`

This call changes state in the org.

```bash theme={null}
curl -sS -X DELETE "$LITMUS_URL/v0/worldplans/$WID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/worldplans/{wid}/harbor`

One minted world as a Harbor dataset: a task directory per task, each with its own verifier. The batch runs against an agent pointed at the mocked tool service; verifiers check the agent's captured trace.

| | |
| - | - |
| 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/worldplans/{wid}/harbor"]["GET"]` |
| CLI | — |

**Path parameters:** `wid`

**Query parameters the handler or its helper reads:** `tier`

**Response:** A file, not JSON: `application/zip`.

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worldplans/$WID/harbor" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/sandboxes`

The org's auditable sandboxes, each carrying the representation that produced it, plus the human realism roll-up over all of them.

| | |
| - | - |
| 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}/sandboxes"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Response fields written in the handler:** `hypotheses`, `mint`, `realism`, `sandboxes`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/sandboxes`

Mint one sandbox from a named representation. 202 + a job id.

| | |
| - | - |
| 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}/sandboxes"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `hypothesis`, `label`, `seed`, `surface`

**Response fields written in the handler:** `deduplicated`, `hypothesis`, `job`, `note`, `status`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/sandboxes" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hypothesis": "<hypothesis>", "label": "<label>", "seed": "<seed>", "surface": "<surface>"}'
```

## `GET /v0/orgs/{orgtag}/realism/packet`

GET /v0/orgs/\{orgtag}/realism/packet?per=\&limit=\&grader=\&audience= — the review packet: tasks for a person to mark realistic / not / unsure, each with that grader's own current mark and the cell's n and graders. By default the bounded round with its minutes and what remains beyond it; `per=all` is every task. The org is the path's; nothing here reads another org's records. No model call, nothing written. `mode=entities&environment=` is the entity walk: one sandbox's tables, twelve by default, each with five rows, to mark at scope `table` or `column`.

| | |
| - | - |
| 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}/realism/packet"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Response fields written in the helper the handler answers through:** `audience`, `failure_modes_to_classify`, `missing`, `source` (added to a stored record whose own keys are not in the source)

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/realism/packet" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/orgs/{orgtag}/realism`

The per-hypothesis realism roll-up, and the marks behind it.

| | |
| - | - |
| 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}/realism"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Response fields written in the handler:** `marks`, `realism`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/realism" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/orgs/{orgtag}/realism`

Mark one record, or a whole sandbox, "would pass as real" / "would not".

| | |
| - | - |
| 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}/realism"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `grader`, `note`, `record`, `record_id`, `sandbox_id`, `scope`, `source`, `table`, `verdict`

**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.

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/realism" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grader": "<grader>", "note": "<note>", "record": "<record>", "record_id": "<record_id>", "sandbox_id": "<sandbox_id>", "scope": "<scope>", "source": "<source>", "table": "<table>", "verdict": "<verdict>"}'
```

## `GET /v0/sandboxes/{sid}`

One sandbox in full — every table's rows, the held-out real records beside them, and the marks already given on it.

| | |
| - | - |
| 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/sandboxes/{sid}"]["GET"]` |
| CLI | — |

**Path parameters:** `sid`

**Response fields written in the handler:** `grades`, `ledger`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/sandboxes/$SID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `DELETE /v0/sandboxes/{sid}`

Remove one sandbox. Its realism marks are kept: they carry the hypothesis and a copy of the record they were given on, so a deleted sandbox does not delete the evidence a person produced about it.

| | |
| - | - |
| 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/sandboxes/{sid}"]["DELETE"]` |
| CLI | — |

**Path parameters:** `sid`

**Response fields written in the handler:** `deleted`

This call changes state in the org.

```bash theme={null}
curl -sS -X DELETE "$LITMUS_URL/v0/sandboxes/$SID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/surfaces`

Traces from an unknown tool surface in; a gated, served mock out.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | `org` in the JSON body; filled in from your token when you leave it out |
| Policy row | `apitokens.POLICY["/v0/surfaces"]["POST"]` |
| CLI | `litmus-ai serve`, `litmus-ai mock` |

**Body fields the handler or its helper reads:** `async`, `catalog`, `evidence`, `name`, `org`, `traces`

**Response fields written in the handler:** `id`, `job_id`, `poll`, `status`, `surface_id`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/surfaces" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"async": "<async>", "catalog": "<catalog>", "evidence": "<evidence>", "name": "<name>", "traces": "<traces>"}'
```

## `POST /v0/worlds`

No description: the handler has no docstring, and nothing here is inferred.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds"]["POST"]` |
| CLI | `litmus-ai serve` |

**Body fields the handler or its helper reads:** `bundle_id`, `cell`, `sample_n`, `seed`, `vectors`

**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.

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/worlds" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "<bundle_id>", "cell": "<cell>", "sample_n": "<sample_n>", "seed": "<seed>", "vectors": "<vectors>"}'
```

## `GET /v0/worlds`

The served fleets, scoped by `_org_scope` like every listing.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | your token: the handler answers your org's rows only |
| Policy row | `apitokens.POLICY["/v0/worlds"]["GET"]` |
| CLI | — |

**Query parameters the handler or its helper reads:** `org`

**Response fields written in the handler:** `served`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worlds" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/worlds/{bundle_id}/{world}/check`

Run a verifier against a served world's CURRENT state.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/check"]["POST"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Body fields the handler or its helper reads:** `verify`

**Response fields written in the handler:** `bundle_id`, `tier`, `verified`, `world`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/check" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"verify": "<verify>"}'
```

## `POST /v0/worlds/{bundle_id}/{world}/reset`

POST /v0/worlds/\{bundle\_id}/\{world}/reset — the served copy back to the pristine mint. Answers the world file's sha256 after the reset so a runner on another machine can hold the rule `CommandReset` holds locally: every reset of a run must reproduce the first one's world, or the trial does not start from the same world and is not in the denominator.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/reset"]["POST"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Response fields written in the handler:** `bundle_id`, `path`, `reset`, `sha256`, `world`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/reset" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `GET /v0/worlds/{bundle_id}/{world}/state`

GET /v0/worlds/\{bundle\_id}/\{world}/state — the served world's CURRENT state, every table, through the control plane and never through the tools under test: the independent read path for a runner grading a hosted world. `path: mock` on the dump.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/state"]["GET"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Response fields written in the handler:** `bundle_id`, `state`, `world`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/state" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/worlds/{bundle_id}/{world}/peek`

GET /v0/worlds/\{bundle\_id}/\{world}/peek — the served world, bounded.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/peek"]["GET"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Response fields written in the handler:** `bundle_id`, `operations`, `world`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/peek" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `GET /v0/worlds/{bundle_id}/{world}/tools`

GET /v0/worlds/\{bundle\_id}/\{world}/tools — the tool specs this world serves.

| | |
| - | - |
| Token scope | `read` (any org token) |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/tools"]["GET"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Response fields written in the handler:** `bundle_id`, `tools`, `world`

```bash theme={null}
curl -sS "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/tools" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

## `POST /v0/worlds/{bundle_id}/{world}/call`

POST /v0/worlds/\{bundle\_id}/\{world}/call \{tool, args} — call one tool.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/worlds/{bundle_id}/{world}/call"]["POST"]` |
| CLI | — |

**Path parameters:** `bundle_id`, `world`

**Body fields the handler or its helper reads:** `args`, `tool`

**Response fields written in the handler:** `bundle_id`, `result`, `tool`, `world`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/worlds/$BUNDLE_ID/$WORLD/call" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"args": "<args>", "tool": "<tool>"}'
```

## `POST /v0/tokens`

No description: the handler has no docstring, and nothing here is inferred.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | the org the named surface bundle is registered to; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/tokens"]["POST"]` |
| CLI | — |

**Body fields the handler or its helper reads:** `bundle_id`, `world`

**Response fields written in the handler:** `connector_url`, `id`, `mcp_url`, `token`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/tokens" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "<bundle_id>", "world": "<world>"}'
```

## `DELETE /v0/tokens/{tid}`

DELETE /v0/tokens/\{tid} — revoke one world connector token.

| | |
| - | - |
| Token scope | `push` or `admin` |
| Org comes from | the org of the bundle behind the world token; another org's answers 404 |
| Policy row | `apitokens.POLICY["/v0/tokens/{tid}"]["DELETE"]` |
| CLI | — |

**Path parameters:** `tid`

**Response fields written in the handler:** `bundle_id`, `id`, `note`, `revoked_at`, `world`

This call changes state in the org.

```bash theme={null}
curl -sS -X DELETE "$LITMUS_URL/v0/tokens/$TID" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.