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

# Evidence

> What a source delivers: pushed traces and documents, the corpus, labels, feedback, and the pass that runs after an ingestion.

43 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 |
| - | - | - |
| POST | `/v0/evidence` | `push` |
| GET | `/v0/evidence` | `read` |
| POST | `/v0/orgs/{orgtag}/corpus` | `push` |
| POST | `/v0/orgs/{orgtag}/pipeline` | `push` |
| GET | `/v0/orgs/{orgtag}/pipeline` | `read` |
| GET | `/v0/evidence/{eid}` | `read` |
| POST | `/v0/evidence/{eid}/assign` | `push` |
| POST | `/v0/orgs/{orgtag}/evidence/{eid}/reconvert` | `push` |
| GET | `/v0/evidence/{eid}/toolspec` | `read` |
| POST | `/v0/evidence/{eid}/attributes` | `push` |
| GET | `/v0/evidence/{eid}/attributes` | `read` |
| POST | `/v0/evidence/{eid}/extract` | `push` |
| GET | `/v0/evidence/{eid}/extraction` | `read` |
| POST | `/v0/evidence/{eid}/re-extract` | `push` |
| POST | `/v0/facets` | `push` |
| GET | `/v0/facets` | `read` |
| GET | `/v0/facets/{fid}` | `read` |
| POST | `/v0/evidence/{eid}/match` | `push` |
| POST | `/v0/evidence/{eid}/worldplan` | `push` |
| POST | `/v0/evidence/{eid}/worldplans/coverage` | `push` |
| GET | `/v0/orgs/{orgtag}/after-ingest` | `read` |
| POST | `/v0/orgs/{orgtag}/after-ingest` | `push` |
| POST | `/v0/orgs/{orgtag}/after-ingest/proposals/{pid}/accept` | `push` |
| POST | `/v0/orgs/{orgtag}/after-ingest/proposals/{pid}/dismiss` | `push` |
| GET | `/v0/orgs/{orgtag}/changes` | `read` |
| GET | `/v0/orgs/{orgtag}/feedback` | `read` |
| POST | `/v0/orgs/{orgtag}/feedback` | `push` |
| GET | `/v0/orgs/{orgtag}/feedback/ledger` | `read` |
| DELETE | `/v0/orgs/{orgtag}/feedback/{fid}` | `admin` |
| POST | `/v0/orgs/{orgtag}/feedback/derive` | `push` |
| GET | `/v0/orgs/{orgtag}/statements` | `read` |
| POST | `/v0/orgs/{orgtag}/statements` | `push` |
| POST | `/v0/orgs/{orgtag}/statements/derive` | `push` |
| GET | `/v0/orgs/{orgtag}/labels` | `read` |
| POST | `/v0/orgs/{orgtag}/labels` | `push` |
| GET | `/v0/orgs/{orgtag}/labels/policy` | `read` |
| PUT | `/v0/orgs/{orgtag}/labels/policy` | `push` |
| GET | `/v0/orgs/{orgtag}/corpus` | `read` |
| POST | `/v0/orgs/{orgtag}/corpus/derive` | `push` |
| GET | `/v0/orgs/{orgtag}/corpus/policy` | `read` |
| PUT | `/v0/orgs/{orgtag}/corpus/policy` | `push` |
| GET | `/v0/orgs/{orgtag}/records` | `read` |
| GET | `/v0/orgs/{orgtag}/records/{kind}/{rid}` | `read` |

## `POST /v0/evidence`

Store one evidence record: `POST /v0/evidence`.

| | |
| - | - |
| 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/evidence"]["POST"]` |
| CLI | `litmus-ai push`, `litmus-ai compare`, `litmus-ai pull` |

**Body fields the handler or its helper reads:** `allow_secrets`, `author`, `author_member`, `content`, `data_access`, `format`, `idempotency_key`, `kind`, `org`, `pipeline`, `progress`, `provenance`, `source`, `tag`

**Response fields written in the helper the handler answers through:** `admitted`, `agent`, `agent_name`, `agent_version`, `columns`, `data_access`, `derive`, `document`, `format`, `id`, `ids`, `job`, `kind`, `line`, `linked_by`, `method`, `never_pulled`, `org`, `origin`, `pipeline`, `provenance_detected`, `provenance_kind`, `refused`, `source`, `source_name`, `stats`, `superseded`, `surface`, `tags`, `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/evidence" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allow_secrets": "<allow_secrets>", "author": "<author>", "author_member": "<author_member>", "content": "<content>", "data_access": "<data_access>", "format": "<format>", "idempotency_key": "<idempotency_key>", "kind": "<kind>", "pipeline": "<pipeline>", "progress": "<progress>", "provenance": "<provenance>", "source": "<source>", "tag": "<tag>"}'
```

## `GET /v0/evidence`

`?org=` narrows to one customer. The console passes it on every read, so that a workspace holding two customers never hands one of them the other's listing — the separation has to happen HERE, not in the page that renders it.

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

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

**Response fields written in the handler:** `data_access`, `evidence`

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

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

`POST /v0/orgs/{org}/corpus` with `{items: [{text, provenance: {site, date, url}, licence}], licence?, site?}` — short public requests about personal-agent use, stored as text and provenance 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}/corpus"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `items`, `licence`, `site`

**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/corpus" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": "<items>", "licence": "<licence>", "site": "<site>"}'
```

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

Run the whole pipeline for one org+surface as a job. 202 + job id; a second call while one runs queues a single rerun instead of racing.

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

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `admit`, `augment`, `k`, `surface`

**Response fields written in the handler:** `admit`, `org`, `poll`, `surface`

This call changes state in the org.

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

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

The org's pipeline runs, newest first — the status row the console 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}/pipeline"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

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

## `GET /v0/evidence/{eid}`

`?summary=1` returns a PREVIEW instead of the record.

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

**Path parameters:** `eid`

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

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

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

## `POST /v0/evidence/{eid}/assign`

Set the org/surface an existing evidence record belongs to.

| | |
| - | - |
| 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/evidence/{eid}/assign"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

**Body fields the handler or its helper reads:** `agent`, `agent_version`, `pipeline`, `provenance`, `superseded_by`

**Response fields written in the handler:** `agent`, `agent_version`, `id`, `org`, `pipeline`, `provenance_kind`, `provenance_kind_before`, `superseded_by`, `surface`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/evidence/$EID/assign" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "<agent>", "agent_version": "<agent_version>", "pipeline": "<pipeline>", "provenance": "<provenance>", "superseded_by": "<superseded_by>"}'
```

## `POST /v0/orgs/{orgtag}/evidence/{eid}/reconvert`

Re-convert one stored Datadog record through today's converter: `POST /v0/orgs/{org}/evidence/{eid}/reconvert`, `{source?, by?}`. Each trace inside Datadog's 15 days is pulled again by its trace id from the org's Datadog row, converted, anonymised and censused as a span round's are, and written over the stored trace at its position, so the evidence id and every link to it stay. The record as it stood is kept first as a revision. A trace past retention, or one Datadog no longer holds, is counted by position and left as it is. No model call, no pipeline: it writes that one record. 202 with the job to follow; the job's `result` carries the counts. A Datadog break part-way keeps what was read whole, and calling again resumes at the next trace. 404 for another org's record, 409 while one runs on it or when the row's key is not the key the record was anonymised under, 422 for a record that is not a stored Datadog batch.

| | |
| - | - |
| 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}/evidence/{eid}/reconvert"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `eid`

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

**Response fields written in the handler:** `evidence`, `job`, `model_calls`, `poll`, `stages`

This call changes state in the org.

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

## `GET /v0/evidence/{eid}/toolspec`

Per-tool parameter value spaces for one source — the mock spec.

| | |
| - | - |
| 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/evidence/{eid}/toolspec"]["GET"]` |
| CLI | — |

**Path parameters:** `eid`

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

## `POST /v0/evidence/{eid}/attributes`

File per-trace EXTRACTED attributes (X55) beside the record.

| | |
| - | - |
| 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/evidence/{eid}/attributes"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

**Body fields the handler or its helper reads:** `attributes`, `extractor_model`, `method`

**Response fields written in the handler:** `_v`, `attributes`, `extracted`, `id`

This call changes state in the org.

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

## `GET /v0/evidence/{eid}/attributes`

The stored per-trace attributes, as stored. The extraction's core claim is that the one model pass is pinned and INSPECTABLE per trace — which was not true while the sidecar had no read path. Falsifier passes read from here rather than from anything recomputed.

| | |
| - | - |
| 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/evidence/{eid}/attributes"]["GET"]` |
| CLI | — |

**Path parameters:** `eid`

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

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

## `POST /v0/evidence/{eid}/extract`

Kick off attribute extraction for one record. 202 + a job id.

| | |
| - | - |
| 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/evidence/{eid}/extract"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

**Body fields the handler or its helper reads:** `fresh`, `limit`, `usd_cap`

**Response fields written in the handler:** `evidence_id`, `job`, `poll`, `traces`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/evidence/$EID/extract" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fresh": "<fresh>", "limit": "<limit>", "usd_cap": "<usd_cap>"}'
```

## `GET /v0/evidence/{eid}/extraction`

What a document contributed, as pinned: the current pin in full and every version it has had; `?pin=<id>` reads one version, superseded ones included. For a corpus: its documents' pins and its mapping.

| | |
| - | - |
| 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/evidence/{eid}/extraction"]["GET"]` |
| CLI | — |

**Path parameters:** `eid`

**Query parameters the handler or its helper reads:** `cites`, `pin`

**Response fields written in the handler:** `cites`, `current`, `documents`, `id`, `map`, `note`, `orphaned`, `versions`

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

## `POST /v0/evidence/{eid}/re-extract`

Re-read a document (or every document of a corpus, and redraw its mapping). The ONLY way a pin is replaced: a mint never does it. 202 + a job; the result says which pin superseded which and what moved.

| | |
| - | - |
| 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/evidence/{eid}/re-extract"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

**Response fields written in the handler:** `evidence_id`, `job`, `poll`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/evidence/$EID/re-extract" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `POST /v0/facets`

File an induced facet space. The measures come WITH it — a space that cannot say how stable it is, or what it predicts, is a picture.

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

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

**Response fields written in the handler:** `clusters`, `id`, `method`, `org`

This call changes state in the org.

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

## `GET /v0/facets`

`?org=` narrows to one customer, exactly as evidence does.

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

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

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

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

## `GET /v0/facets/{fid}`

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

**Path parameters:** `fid`

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

## `POST /v0/evidence/{eid}/match`

How many runs match a selection — and what each next value would cost.

| | |
| - | - |
| 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/evidence/{eid}/match"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

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

**Response fields written in the handler:** `corpus_n`, `counted_selection`, `matched_n`, `min_traces`, `per_field`, `unfilterable`

This call changes state in the org.

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

## `POST /v0/evidence/{eid}/worldplan`

Mint a world plan from an attribute selection over one source.

| | |
| - | - |
| 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/evidence/{eid}/worldplan"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

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

**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/evidence/$EID/worldplan" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"augment": "<augment>", "label": "<label>", "selection": "<selection>"}'
```

## `POST /v0/evidence/{eid}/worldplans/coverage`

Mint k worlds covering the corpus's attribute space — the default mint. The corpus chooses the points (deterministic clustering over the stored per-trace attributes); each chosen point is declared as a selection and minted through the ordinary path, so coverage worlds supersede and link exactly like hand-pinned ones. 202 + a job id.

| | |
| - | - |
| 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/evidence/{eid}/worldplans/coverage"]["POST"]` |
| CLI | — |

**Path parameters:** `eid`

**Body fields the handler or its helper reads:** `augment`, `k`

**Response fields written in the handler:** `evidence_id`, `job`, `k`, `poll`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/evidence/$EID/worldplans/coverage" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"augment": "<augment>", "k": "<k>"}'
```

## `GET /v0/orgs/{orgtag}/after-ingest`

`GET /v0/orgs/{org}/after-ingest?since=<epoch s>` — what the org's last pass found: its one-line summary and counts, the open proposals with their measured reasons, the starters it wrote, the tally per proposal kind, and — with `since`, a member's last visit — the operations first seen after it. A read of one record; 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}/after-ingest"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

**Response fields written in the handler:** `queued`, `running`

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

## `POST /v0/orgs/{orgtag}/after-ingest`

`POST /v0/orgs/{org}/after-ingest` — run the pass now, the one an ingestion queues. 202 with the job; the one already running when there is one (`deduplicated`).

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

**Path parameters:** `orgtag`

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

**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/after-ingest" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>"}'
```

## `POST /v0/orgs/{orgtag}/after-ingest/proposals/{pid}/accept`

`POST /v0/orgs/{org}/after-ingest/proposals/{pid}/accept` — the one press. Runs the act the proposal names through that act's own route (the re-draw, or the task generation) as the caller, and closes the proposal as accepted only when that route accepted the act; its answer is returned as `act`. 404 for a proposal this org does not hold; 409 for one already closed or superseded.

| | |
| - | - |
| 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}/after-ingest/proposals/{pid}/accept"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `pid`

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

**Response fields written in the handler:** `accepted`, `act`, `job`, `proposal`, `revision`, `state`, `status`, `touched`, `touched_n`

This call changes state in the org.

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

## `POST /v0/orgs/{orgtag}/after-ingest/proposals/{pid}/dismiss`

`POST …/after-ingest/proposals/{pid}/dismiss` — not now. Counted in the tally; offered again only when its reason changes.

| | |
| - | - |
| 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}/after-ingest/proposals/{pid}/dismiss"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`, `pid`

**Response fields written in the handler:** `dismissed`, `proposal`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/after-ingest/proposals/$PID/dismiss" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

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

`GET /v0/orgs/{org}/changes?since=<epoch s>&page=home|ontology` — what the org's standing pass changed after `since` (a member's last visit; absent is every kept line), as lines newest first: what moved in the ontology, the sessions it pulled, each sandbox it re-drew or put back, the tasks it generated and what waits on tomorrow's budget. Each line carries counts only, its revision id and `undo` (the restore route) where it has one, its tier and its cost. A kept 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}/changes"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

**Query parameters the handler or its helper reads:** `page`, `since`

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

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

This org's notes, oldest first. `?kind=` `?id=` `?index=` narrow by what they are about; `?id=` alone matches every kind, so an environment's page reads the notes on it and on its tasks in one 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}/feedback"]["GET"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

**Response fields written in the handler:** `about_kinds`, `audience`, `count`, `feedback`, `flags`, `method`, `org`, `polarities`, `source`, `tier`

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

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

`{text, author | by, about?: {kind, id, index?}, polarity?, context?, seen?: {head, route?}, origin?, origin_source?, fields?, filed_by?}`.

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

**Path parameters:** `orgtag`

**Body fields the handler or its helper reads:** `about`, `author`, `author_member`, `by`, `context`, `fields`, `filed_by`, `make_mode`, `missing`, `mode`, `origin`, `origin_source`, `place`, `polarity`, `seen`, `target`, `text`, `visibility`

**Response fields written in the handler:** `count`, `feedback`, `flag`, `label`, `org`, `source`

This call changes state in the org.

```bash theme={null}
curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/feedback" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"about": "<about>", "author": "<author>", "author_member": "<author_member>", "by": "<by>", "context": "<context>", "fields": "<fields>", "filed_by": "<filed_by>", "make_mode": "<make_mode>", "missing": "<missing>", "mode": "<mode>", "origin": "<origin>", "origin_source": "<origin_source>", "place": "<place>", "polarity": "<polarity>", "seen": "<seen>", "target": "<target>", "text": "<text>", "visibility": "<visibility>"}'
```

## `GET /v0/orgs/{orgtag}/feedback/ledger`

`GET /v0/orgs/{org}/feedback/ledger` — the feedback sheet's reports against Datadog's retention: how many are read, waiting on the Datadog pull, past retention, not found or undated, when the oldest waiting session leaves Datadog (a UTC date), and the line the Sources page prints. Every count is deterministic. Counts and dates only — no id, no note's words — so a `read` token of the org reads it whatever its audience. Writes nothing and calls no model.

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

**Path parameters:** `orgtag`

**Response fields written in the handler:** `leaves_retention_on`, `line`, `oldest_waiting_at`, `past_retention`, `read`, `reports`, `retention_days`, `tier`, `undated`, `undated_bound_past`, `undated_leave_by`, `unreachable`, `waiting`

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

## `DELETE /v0/orgs/{orgtag}/feedback/{fid}`

`{by?}` — retire one note: `retired_at` and `retired_by` on its evidence row, and every list, the derive pass and the run verdicts skip it from now on. A MARK, NOT AN ERASE: the row stays, so what was filed and who withdrew it are both on the record. Retiring twice keeps the first mark; another org's id answers as one that does not exist.

| | |
| - | - |
| 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}/feedback/{fid}"]["DELETE"]` |
| CLI | `litmus-ai feedback` |

**Path parameters:** `orgtag`, `fid`

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

**Response fields written in the handler:** `already`, `id`, `org`, `retired`, `retired_at`, `retired_by`

This call changes state in the org.

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

## `POST /v0/orgs/{orgtag}/feedback/derive`

`{limit?}` — ONE model pass over the notes no earlier pass read, writing PROPOSALS (`dimension`, `criterion_kind`, `review_rule`, `generator_gate`, `analyzer_detector`) into the proposed axes built, each citing the notes that motivate it and naming the stage it would change. It applies nothing: a proposal is accepted or dismissed through `…/dimensions/values/{id}/accept|dismiss`, and only an accepted dimension reaches the space a generation selects over. Nothing unread is an answer with no model call.

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

**Path parameters:** `orgtag`

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

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

This call changes state in the org.

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

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

`GET /v0/orgs/{org}/statements` — the statements on record (never their words; `?id=` returns one with its text) and the stated-buckets proposals made from them, any status.

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

**Path parameters:** `orgtag`

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

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

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

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

`{text, author | by, origin: upload|paste|home, file_name?, derive?}` — store the words verbatim (tier human), then, unless `derive` is false, run the ONE derive pass on them: its estimate is said before the call and its spend after, on the answer. Nothing is stated until a member accepts the proposal.

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

**Path parameters:** `orgtag`

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

**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/statements" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"derive": "<derive>"}'
```

## `POST /v0/orgs/{orgtag}/statements/derive`

`{statement?}` — ONE model pass over one statement no earlier pass read (the one named, else the oldest): at most one stated-buckets proposal, each bucket with its label, one-sentence profile and the sentence of the source it came from. Nothing unread is an answer with no model call; a statement with no categorization proposes nothing and 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}/statements/derive"]["POST"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

**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/statements/derive" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement": "<statement>"}'
```

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

`GET /v0/orgs/{org}/labels[?surface=]`: the org's labels (ids, kinds, whether each has a correction and what it became), per-stream counts, the production-only opt-in, and the superset guard over the standing tasks. No correction's words, ever.

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

**Path parameters:** `orgtag`

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

**Response fields written in the helper the handler answers through:** `labels`, `org`, `origin`, `policy`, `streams`

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

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

The webhook: `POST /v0/orgs/{org}/labels` with `{surface, labels: [{trace, polarity, correction?}]}` (or one label's fields at the top).

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

**Path parameters:** `orgtag`

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

**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/labels" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels": "<labels>", "surface": "<surface>", "trace": "<trace>"}'
```

## `GET /v0/orgs/{orgtag}/labels/policy`

`GET /v0/orgs/{org}/labels/policy`: whether the org has said that a production-only dataset is what it wants, who said it and when. Unset reads as no (`labels.policy`).

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

**Path parameters:** `orgtag`

**Response fields written in the helper the handler answers through:** `at`, `by`, `production_only`, `set`

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

## `PUT /v0/orgs/{orgtag}/labels/policy`

`PUT /v0/orgs/{org}/labels/policy` with `{production_only, by}`: the org's answer to whether a production-only dataset is what it wants. The superset guard holds one until this says yes, with who said 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}/labels/policy"]["PUT"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

**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 PUT "$LITMUS_URL/v0/orgs/$LITMUS_ORG/labels/policy" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "production_only": "<production_only>"}'
```

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

`GET /v0/orgs/{org}/corpus`: the corpus's counts by licence and site, the hand-set use cases its items READ as (the keyword rule), the org's public-demand toggle, and every candidate value with its status. Ids, counts and our value names — never an item's text.

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

**Path parameters:** `orgtag`

**Response fields written in the helper the handler answers through:** `by_status`, `candidates`, `corpus`, `hand_set`, `licences`, `org`, `passes`, `policy`, `source`, `tier`

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

## `POST /v0/orgs/{orgtag}/corpus/derive`

`POST /v0/orgs/{org}/corpus/derive` with `{limit?}` — ONE model pass over the items no earlier pass read, clustering them into use cases and phrasing registers the hand-set axes do not name. A candidate is kept only when its quote resolves in an item it cites (`document.resolve`, the PRD extraction's gate), and is stored as a proposal: it reaches a generation only when a person accepts it (`…/dimensions/values/{id}/ accept`) and the org's toggle is on. Nothing unread is an answer with no model call.

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

**Path parameters:** `orgtag`

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

**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/corpus/derive" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": "<limit>"}'
```

## `GET /v0/orgs/{orgtag}/corpus/policy`

`GET /v0/orgs/{org}/corpus/policy`: whether public demand shapes this org's datasets, who said so and when. Unset reads as off.

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

**Path parameters:** `orgtag`

**Response fields written in the helper the handler answers through:** `at`, `by`, `public_demand`, `set`

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

## `PUT /v0/orgs/{orgtag}/corpus/policy`

`PUT /v0/orgs/{org}/corpus/policy` with `{public_demand, by}`: the org's answer to whether accepted corpus values are dealt beside the hand-set situations on its generations. Refused without who gave 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}/corpus/policy"]["PUT"]` |
| CLI | — |

**Path parameters:** `orgtag`

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

**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 PUT "$LITMUS_URL/v0/orgs/$LITMUS_ORG/corpus/policy" \
  -H "Authorization: Bearer $LITMUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"by": "<by>", "public_demand": "<public_demand>"}'
```

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

Every record this org holds, by kind: the ids of each kind a copy takes, and a count with its reason for each kind that stays behind.

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

**Path parameters:** `orgtag`

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

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

## `GET /v0/orgs/{orgtag}/records/{kind}/{rid}`

One record of a kind `store.KINDS` copies, exactly as stored.

| | |
| - | - |
| 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}/records/{kind}/{rid}"]["GET"]` |
| CLI | — |

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

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


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