> ## 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. # Ontology > What Litmus understands about the systems your agent talks to: the ontology, its dimensions, criteria and coverage. 27 routes. Every example runs with `LITMUS_URL`, `LITMUS_TOKEN` and `LITMUS_ORG` (your org tag) set in your shell (see [Authentication](/authentication)). A `$NAME` in a path is an id you read from the listing route on this page; a `` in a body is a value you supply, and every field the handler reads is shown, so send only the ones you need. Fields are what the handler's source reads and writes, listed mechanically; they are not a schema. | Method | Path | Scope | | - | - | - | | GET | `/v0/orgs/{orgtag}/situations` | `read` | | GET | `/v0/orgs/{orgtag}/criteria/readiness` | `read` | | POST | `/v0/orgs/{orgtag}/dimensions/values/{value_id}/profile` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/personas/{value}/draw` | `push` | | GET | `/v0/orgs/{orgtag}/dimensions/personas` | `read` | | POST | `/v0/orgs/{orgtag}/dimensions/personas` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/personas-from-document` | `push` | | GET | `/v0/orgs/{orgtag}/coverage` | `read` | | GET | `/v0/orgs/{orgtag}/ontology` | `read` | | POST | `/v0/orgs/{orgtag}/ontology/compile` | `push` | | GET | `/v0/orgs/{orgtag}/ontology/pins` | `read` | | POST | `/v0/orgs/{orgtag}/ontology/restore` | `push` | | GET | `/v0/orgs/{orgtag}/ontology/nodes/{node_id:path}` | `read` | | POST | `/v0/orgs/{orgtag}/surfaces/{surface}/ontology/derive` | `push` | | GET | `/v0/orgs/{orgtag}/surfaces/{surface}/ontology/versions` | `read` | | GET | `/v0/orgs/{orgtag}/surfaces/{surface}/ontology/diff` | `read` | | POST | `/v0/orgs/{orgtag}/surfaces/{surface}/relations/document` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/values/{value_id}/parent` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/merge-spellings` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/values/{value_id}/hero` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/values/{value_id}/accept` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions/values/{value_id}/dismiss` | `push` | | POST | `/v0/orgs/{orgtag}/ontology/revisions/{rev}/restore` | `push` | | GET | `/v0/orgs/{orgtag}/dimensions` | `read` | | POST | `/v0/orgs/{orgtag}/dimensions/derive` | `push` | | POST | `/v0/orgs/{orgtag}/dimensions` | `admin` | | DELETE | `/v0/dimensions/{did}` | `admin` | ## `GET /v0/orgs/{orgtag}/situations` `GET /v0/orgs/{org}/situations`. | | | | - | - | | 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}/situations"]["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/situations" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/criteria/readiness` `GET /v0/orgs/{org}/criteria/readiness[?agent=]`. | | | | - | - | | 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}/criteria/readiness"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `agent` **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/criteria/readiness" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/dimensions/values/{value_id}/profile` `POST …/dimensions/values/{value_id}/profile` with any of `weight`, `profile`, `jobs`, `personas`, and `by` (`valueprofile.set_profile`). | | | | - | - | | 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}/dimensions/values/{value_id}/profile"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value_id` **Body fields the handler or its helper reads:** `by` **Response fields written in the handler:** `org`, `value` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/values/$VALUE_ID/profile" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/personas/{value}/draw` `POST /v0/orgs/{org}/dimensions/personas/{value}/draw` with `{by, surface?}`: a member's press on a persona's card — its sandbox's generate job now, the day's budget notwithstanding (a press, as accepting a proposal is), on the pass's ledger like any draw. | | | | - | - | | 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}/dimensions/personas/{value}/draw"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value` **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/dimensions/personas/$VALUE/draw" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `GET /v0/orgs/{orgtag}/dimensions/personas` `GET|POST /v0/orgs/{org}/dimensions/personas`. | | | | - | - | | 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}/dimensions/personas"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Response fields written in the handler:** `added`, `draw` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/personas" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/dimensions/personas` `GET|POST /v0/orgs/{org}/dimensions/personas`. | | | | - | - | | 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}/dimensions/personas"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `add`, `by`, `cited`, `draw`, `n`, `notes`, `personas`, `stated_from`, `surface` **Response fields written in the handler:** `added`, `draw` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/personas" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"add": "", "by": "", "cited": "", "draw": "", "n": "", "notes": "", "personas": "", "stated_from": "", "surface": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/personas-from-document` `POST /v0/orgs/{org}/dimensions/personas-from-document` with `{source}`: the personas the source's documents' PINNED extractions cite, written as the named `persona` axis (`valueprofile.from_document`). No model call — the pin is the read; a document never read is 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}/dimensions/personas-from-document"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Response fields written in the helper the handler answers through:** `derived_from`, `field`, `org`, `pins`, `row`, `source`, `tier`, `values` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/personas-from-document" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` ## `GET /v0/orgs/{orgtag}/coverage` `GET /v0/orgs/{org}/coverage`: the persona x job matrix — which cells hold tasks and verifiers, which a person marked as a job of that persona and are still gaps (`valueprofile.coverage`). | | | | - | - | | 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}/coverage"]["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/coverage" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/ontology` One graph's snapshot: `?surface=` names it (or the org's only surface is resolved), `?legacy=1` addresses the pre-keying per-org graph. Carries `surfaces` — the org's, as data — beside the graph; `compile` is the named surface's newest compile job and null on a legacy read; `counts.removed` is what the current revision retired from the one before it. `?part=head` is the same record without the graph (`nodes`, `edges`, `evidence_refs`, `plans`, `ontology`) for a page that draws none; the graph is kept per surface version and `x-litmus-ontology-cache` says `hit` or `miss`. | | | | - | - | | 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}/ontology"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `legacy`, `part`, `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/ontology" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/ontology/compile` Compile one surface's graph from its corpus. 202 + a job id; a repeat while that surface's compile runs returns the running job with `deduplicated: true`. The job's `result` is the compiler's report: what landed, what was `refused` (proposed and never admitted) and what was `removed` (held by the previous revision, unevidenced by this corpus), and `schema_pin` — the pinned model draw it compiled over, reused when the corpus, model and prompt are unchanged. `redraw: true` is the explicit act that draws again and supersedes that pin. | | | | - | - | | 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}/ontology/compile"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `force`, `redraw`, `surface` **Response fields written in the handler:** `deduplicated`, `job`, `note`, `status`, `surface` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/ontology/compile" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"force": "", "redraw": "", "surface": ""}' ``` ## `GET /v0/orgs/{orgtag}/ontology/pins` The pinned model draws of one surface's ontology: every pin it has had (`?surface=`), or one by id (`?pin=oxp_…`), current or superseded — so a sandbox's `schema_pin` can be read back to the draw it came from. | | | | - | - | | 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}/ontology/pins"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Query parameters the handler or its helper reads:** `pin`, `surface` **Response fields written in the handler:** `org`, `pins`, `prompt_version`, `surface` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/ontology/pins" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/ontology/restore` Restore one SURFACE's revision; the answer names the 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}/ontology/restore"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `expected_revision`, `legacy`, `revision`, `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. This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/ontology/restore" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"expected_revision": "", "legacy": "", "revision": "", "surface": ""}' ``` ## `GET /v0/orgs/{orgtag}/ontology/nodes/{node_id:path}` One node of one graph, with the edges that touch it and the evidence behind both; the graph is addressed as `ontology_get` addresses 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}/ontology/nodes/{node_id:path}"]["GET"]` | | CLI | — | **Path parameters:** `orgtag`, `node_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/ontology/nodes/$NODE_ID" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/surfaces/{surface}/ontology/derive` `POST /v0/orgs/{org}/surfaces/{surface}/ontology/derive` — store the ontology of the version this surface serves NOW under its `sfv-`. | | | | - | - | | 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}/ontology/derive"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `surface` **Body fields the handler or its helper reads:** `agent`, `agent_version` **Response fields written in the handler:** `counts`, `exposed_by`, `job`, `ontology`, `status`, `surface`, `surface_version`, `tier` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/ontology/derive" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"agent": "", "agent_version": ""}' ``` ## `GET /v0/orgs/{orgtag}/surfaces/{surface}/ontology/versions` `GET …/surfaces/{surface}/ontology/versions` — the switcher's list: every stored version with the agent versions that expose it, and the current one (a pointer, read live) whether or not it was derived. | | | | - | - | | 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}/ontology/versions"]["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/ontology/versions" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `GET /v0/orgs/{orgtag}/surfaces/{surface}/ontology/diff` `GET …/surfaces/{surface}/ontology/diff?a=sfv-…&b=sfv-…` — what moved between two stored versions: operations added / removed / renamed, relation edges moved, surface-half dimension values moved. Both must be stored; `b` defaults to the current version. | | | | - | - | | 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}/ontology/diff"]["GET"]` | | CLI | — | **Path parameters:** `orgtag`, `surface` **Query parameters the handler or its helper reads:** `a`, `b` **Response fields written in the handler:** `surface` ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/ontology/diff" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/surfaces/{surface}/relations/document` `{source?}` — one model pass over the org's document, written as the edges it states between this surface's services, objects and data. | | | | - | - | | 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}/relations/document"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `surface` **Body fields the handler or its helper reads:** `source` **Response fields written in the handler:** `evidence`, `job`, `note`, `org`, `poll`, `stages`, `surface` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/surfaces/$SURFACE/relations/document" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"source": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/values/{value_id}/parent` A PERSON says which value this one belongs to. | | | | - | - | | 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}/dimensions/values/{value_id}/parent"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value_id` **Body fields the handler or its helper reads:** `field`, `grader`, `grader_kind`, `reason`, `value` **Response fields written in the handler:** `attachment`, `grader`, `note`, `org`, `parent`, `replaced`, `tier`, `value` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/values/$VALUE_ID/parent" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"field": "", "grader": "", "grader_kind": "", "reason": "", "value": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/merge-spellings` Fold a use case the org holds in two spellings into the first one written. | | | | - | - | | 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}/dimensions/merge-spellings"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `apply`, `by`, `field` **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/dimensions/merge-spellings" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"apply": "", "by": "", "field": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/values/{value_id}/hero` Mark a use case as one of the org's HERO use cases, or unmark 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}/dimensions/values/{value_id}/hero"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value_id` **Body fields the handler or its helper reads:** `by`, `cites`, `hero` **Response fields written in the handler:** `by`, `cites`, `hero`, `org`, `value` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/values/$VALUE_ID/hero" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": "", "cites": "", "hero": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/values/{value_id}/accept` `{by, reason?}` — accept or dismiss a proposed axis (`dx_…`) or one of its values (`dv_…`). | | | | - | - | | 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}/dimensions/values/{value_id}/accept"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value_id` **Body fields the handler or its helper reads:** `by`, `personas`, `reason` **Response fields written in the handler:** `act`, `axis`, `org`, `target` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/values/$VALUE_ID/accept" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": "", "personas": "", "reason": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions/values/{value_id}/dismiss` `{by, reason?}` — accept or dismiss a proposed axis (`dx_…`) or one of its values (`dv_…`). | | | | - | - | | 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}/dimensions/values/{value_id}/dismiss"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `value_id` **Body fields the handler or its helper reads:** `by`, `personas`, `reason` **Response fields written in the handler:** `act`, `axis`, `org`, `target` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/values/$VALUE_ID/dismiss" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": "", "personas": "", "reason": ""}' ``` ## `POST /v0/orgs/{orgtag}/ontology/revisions/{rev}/restore` `POST /v0/orgs/{org}/ontology/revisions/{rev}/restore` — put back what an applied ontology diff changed: the agent's layer slots as the revision found them. `{reason?}`. The state it replaces is kept as a revision (`undo`), so restoring that re-applies the diff. 404 for a revision this org does not hold or that is not an ontology revision; 409 for one already restored. Ids only; 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}/ontology/revisions/{rev}/restore"]["POST"]` | | CLI | — | **Path parameters:** `orgtag`, `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/ontology/revisions/$REV/restore" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"by": "", "reason": ""}' ``` ## `GET /v0/orgs/{orgtag}/dimensions` Every axis this org's representation carries, with its provenance. | | | | - | - | | 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}/dimensions"]["GET"]` | | CLI | — | **Path parameters:** `orgtag` **Response fields written in the helper the handler answers through:** `facets` (added to a stored record whose own keys are not in the source) ```bash theme={null} curl -sS "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions" \ -H "Authorization: Bearer $LITMUS_TOKEN" ``` ## `POST /v0/orgs/{orgtag}/dimensions/derive` `{source}` — one model pass over one source, written as 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}/dimensions/derive"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `additive`, `attributes`, `curve`, `limit`, `propose`, `source`, `subsample` **Response fields written in the handler:** `complements`, `deduped`, `dropped_ids`, `job`, `model`, `note`, `org`, `partial`, `poll`, `prompt_version`, `proposed`, `read`, `read_chars`, `records`, `refused`, `stages`, `tier` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions/derive" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"additive": "", "attributes": "", "curve": "", "limit": "", "propose": "", "source": "", "subsample": ""}' ``` ## `POST /v0/orgs/{orgtag}/dimensions` Declare a dimension: `{field, values, label?, description?, added_by?}`, answered with the stored record. | | | | - | - | | 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}/dimensions"]["POST"]` | | CLI | — | **Path parameters:** `orgtag` **Body fields the handler or its helper reads:** `added_by`, `description`, `field`, `label`, `preset`, `values` **Response fields written in the helper the handler answers through:** `already`, `dimensions`, `preset`, `registered` This call changes state in the org. ```bash theme={null} curl -sS -X POST "$LITMUS_URL/v0/orgs/$LITMUS_ORG/dimensions" \ -H "Authorization: Bearer $LITMUS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"added_by": "", "description": "", "field": "", "label": "