# API: Decisions and drafts

Create Decisions, write and check their drafts, and work with the Definition assistant.

Part of the API reference: requests carry a personal access token as `Authorization: Bearer <token>`, and bodies and answers are JSON.

- [API reference](https://typefuse.dev/guides/api-reference)
- [Try it in the API console](https://api.typefuse.dev/docs)

## Decisions

### GET /v1/organisations/{org}/decisions

**List Decisions.**

The Decisions in use; with `archived=true`, the archived ones instead.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `archived` | `boolean` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `decisions` | `array` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/decisions" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions

**Create a Decision.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | `string` | Required |  |
| `name` | `string` | Required |  |
| `description` | `string or null` | Optional |  |
| `definition` | `object` | Optional | An initial draft, for example from a template or the authoring model. |
| `source` | `string` | Optional | The initial draft as YAML or JSON source, instead of `definition`: TypeFuse parses it, keeps it exactly as written, and refuses it with the exact path of any problem. |
| `sourceFormat` | `string`, one of `yaml`, `json` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"refunds","name":"Refunds"}'
```

### GET /v1/organisations/{org}/decisions/{slug}

**Get a Decision.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### PATCH /v1/organisations/{org}/decisions/{slug}

**Update a Decision.**

Rename: name and description only; the slug is part of the identifier and stays.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Required |  |
| `description` | `string or null` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X PATCH "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Refunds","description":"<description>"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/move

**Move a Decision to another organisation.**

Moves the Decision to another organisation. Owners and admins of both. dryRun reports without changing anything; 409 MOVE_BLOCKED carries the report and its blockers; 503 RUNTIME_SYNC_FAILED means the database moved and repeating the call finishes it.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | `string` | Required | The organisation to move to; the caller must be an owner or admin of both. |
| `dryRun` | `boolean` | Optional | Report what would move, and what stops it, without changing anything. |

It answers with no body.

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/move" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"<to>"}'
```

### GET /v1/organisations/{org}/decisions/{slug}/forwards

**List a Decision's old identifiers.**

The Decision's old identifiers, which forward to it permanently.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `forwards` | `array` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/forwards" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions/{slug}/forwards/{from}/stop-old-keys

**Stop the old organisation's keys.**

Stops accepting the old organisation's API keys at one old identifier. The identifier keeps forwarding for this organisation's keys and its name stays reserved. Owners and admins.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |
| `from` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `forwards` | `array` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/forwards/<from>/stop-old-keys" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions/{slug}/archive

**Archive a Decision.**

Archive: out of every environment it can leave at once, off the lists and the plan's count, read-only; its history stays. Owners and admins. 409 when it serves production, when taking it out needs an approval, or while a request waits.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/archive" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions/{slug}/restore

**Restore an archived Decision.**

Restore an archived Decision, if the plan has room for it (402 PLAN_LIMIT otherwise).

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/restore" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### PUT /v1/organisations/{org}/decisions/{slug}/readme

**Update the readme.**

Replaces the draft README Markdown; publishing freezes it into the version.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `markdown` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X PUT "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/readme" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"<markdown>"}'
```

## Drafts

### PUT /v1/organisations/{org}/decisions/{slug}/draft

**Save the draft.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `definition` | `object` | Optional | The parsed draft. Leave it out to have TypeFuse parse `source`. |
| `source` | `string` | Required | YAML authored by the user, preserved exactly. |
| `sourceFormat` | `string`, one of `yaml`, `json` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `slug` | `string` |  |
| `address` | `string` | `organisation/decision`: the Decision's identifier. |
| `name` | `string` |  |
| `description` | `string or null` |  |
| `category` | `string or null` | Cached output from the platform's deployed Decision categoriser. |
| `categorySource` | `string or null` | Which classifier set the category, and its version. |
| `draft` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `draftHash` | `string` |  |
| `draftSource` | `string` | YAML authored by the user, preserved exactly. |
| `draftSourceFormat` | `string`, one of `yaml`, `json` |  |
| `readmeMarkdown` | `string` | Markdown documentation edited with the draft and frozen on publish. |
| `readmeHash` | `string` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `archivedAt` | `string or null` | When it was archived; null while in use. |
| `archivedBy` | `integer or null` | Who archived it; null while in use. |
| `agents` | `object` | What it tells agents, and whether it's offered to them. |
| `agents.offered` | `boolean` | Agents the organisation allows can find it and call it wherever it's deployed. |
| `agents.whenToUse` | `string or null` |  |
| `agents.whenNotToUse` | `string or null` |  |
| `agents.exampleIntents` | `array of string` |  |

```sh
curl -X PUT "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"<source>","sourceFormat":"yaml"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/compile

**Compile the draft.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `ok` | `boolean` |  |
| `plan` | `object` | The compiled ExecutionPlan. Its shape is owned by |
| `errors` | `array of { "path": string, "message": string }` |  |
| `estimate` | `object` | Present whenever the draft parses, compiled or not. |
| `estimate.fixedTokens` | `integer` | Overhead, context and ordinary questions: paid on every call. |
| `estimate.each` | `array of { "question": string, "each": string, "maxItems": integer, "tokensPerItem": integer }` |  |
| `estimate.questionTokensAtMax` | `integer` |  |
| `estimate.inputTokensAtMax` | `integer` | Caller input at its limits, estimated from state_schema (maxLength where declared). |
| `estimate.requestTokensAtMax` | `integer` |  |
| `advice` | `array` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/compile" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/run

**Run the draft in the Sandbox.**

Sandbox: runs the draft as it is now, without publishing. With X-TypeSafe-Key it runs on your own TypeSafe key, for this request only and never stored.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-TypeSafe-Key` | `string` | Optional |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | `string or object or array` | Required | Dynamic TypeSafe state: a string, object, or array, checked by state_schema. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `versionId` | `string or null` | Null when the run executed the draft; see draftHash. |
| `draftHash` | `string or null` |  |
| `role` | `string or null`, one of `primary`, `variant`, `compatible`, `shadow` | For served runs, which part of the deployment this was; null otherwise. |
| `environment` | `string` |  |
| `source` | `string` |  |
| `actorType` | `string` |  |
| `actorId` | `string` |  |
| `startedAt` | `string` |  |
| `latencyMs` | `integer` |  |
| `input` | `string or object or array` | Dynamic TypeSafe state: a string, object, or array, checked by state_schema. |
| `answers` | `object or null` | Native TypeSafe answers, keyed by question id; a list in item order for an `each` question. |
| `inputTokens` | `integer or null` | Input tokens, as the provider reported them. |
| `outputTokens` | `integer or null` |  |
| `itemCount` | `integer or null` | Items judged by per-item (`each`) questions; null for a Decision without them. |
| `status` | `string` |  |
| `error` | `string or null` |  |
| `applicationId` | `string or null` | The calling software (its key's Application); null for sandbox and test runs. |
| `reference` | `object or null` | What the call was about, in the caller's terms. |
| `reference.type` | `string` |  |
| `reference.id` | `string` |  |
| `correlationId` | `string or null` | The thread of calls it belongs to. |
| `sealId` | `string or null` | The seal that fixed its content in the audit chain; null until the next seal. |
| `responseOrigin` | `string or null`, one of `provider`, `caller` | Where the provider's response came from: `provider` when TypeFuse received it from TypeSafe itself (Managed, BYOK), `caller` when the caller reported it (Relay, and the removed record-only mode). Null for runs from before it was recorded. Included in the run's seal. |
| `planHash` | `string` |  |
| `completedAt` | `string` |  |
| `state` | `object` | The state exactly as sent to the provider. |
| `provider` | `string` |  |
| `providerModel` | `string or null` |  |
| `providerRequestId` | `string or null` |  |
| `usage` | `object or null` |  |
| `usage.inputTokens` | `integer` |  |
| `usage.outputTokens` | `integer` |  |
| `proof` | `object` | On a single run: its content hashes and seal. |
| `proof.planHash` | `string` |  |
| `proof.inputHash` | `string or null` |  |
| `proof.stateHash` | `string or null` |  |
| `proof.answersHash` | `string or null` |  |
| `proof.seal` | `object or null` |  |
| `versionNumber` | `integer or null` | On a single run: the number of the version it ran (`versionId`'s), null for a draft run. |
| `servedBy` | `object or null` | On a single served call: the deployment that answered it, who asked for it and who approved it. Null for Sandbox, Test set and Evaluation runs. |
| `servedBy.deploymentId` | `string` |  |
| `servedBy.liveAt` | `string` | When the deployment went live. |
| `servedBy.requestedBy` | `object or null` | The person or deploy token that asked for it; null when neither is known any more. |
| `servedBy.approvedBy` | `string or null` |  |
| `servedBy.approvedAt` | `string or null` |  |
| `servedBy.selfApproved` | `boolean` | The person who approved it also asked for it (the only owner or admin). |
| `notStored` | `string` | Present when the run's stored input and the state sent to the model have expired under the plan's retention (or the Sandbox's): the sentence that says so. The run keeps its answers, hashes and seal; `input` is then empty and `state` is `{}`. |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/run" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"<input>"}'
```

## Draft review

### POST /v1/organisations/{org}/decisions/{slug}/draft/review

**Review the draft.**

The Definition assistant's Review: deterministic checks over the draft (or source not yet saved), each finding with a mechanical fix where there is one. It writes nothing, so a Read token may call it.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | `string` | Optional |  |
| `sourceFormat` | `string`, one of `yaml`, `json` | Optional |  |
| `triage` | `boolean` | Optional | Also run the assistant review's judgment checks: one model call, whose answer is kept for each question. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `draftHash` | `string` |  |
| `saved` | `boolean` | False when unsaved source was reviewed. |
| `ok` | `boolean` | False when the source does not parse; `errors` says why. |
| `errors` | `array of { "path": string, "message": string }` |  |
| `estimate` | `object or null` | The estimated tokens and cost of one call, with every list at its limit. |
| `estimate.fixedTokens` | `integer` | Overhead, context and ordinary questions: paid on every call. |
| `estimate.each` | `array of { "question": string, "each": string, "maxItems": integer, "tokensPerItem": integer }` |  |
| `estimate.questionTokensAtMax` | `integer` |  |
| `estimate.inputTokensAtMax` | `integer` | Caller input at its limits, estimated from state_schema (maxLength where declared). |
| `estimate.requestTokensAtMax` | `integer` |  |
| `findings` | `array` | Worst first. |
| `triage` | `object or null` | The judgment checks when `triage` was asked for; null otherwise. |
| `triage.status` | `string`, one of `ok`, `unavailable`, `failed`, `rate_limited`, `not_permitted` | not_permitted: viewers and read-only tokens get the rule checks only; nothing was asked. |
| `triage.message` | `string or null` |  |
| `triage.retryAfterSeconds` | `integer or null` |  |
| `triage.reviewer` | `object or null` |  |
| `triage.findings` | `array` | Worst first. |
| `triage.worthALook` | `array` |  |
| `triage.passed` | `integer` |  |
| `triage.totalQuestions` | `integer` |  |
| `triage.reviewedQuestions` | `integer` |  |
| `triage.cachedQuestions` | `integer` |  |
| `triage.askedQuestions` | `integer` |  |
| `triage.usage` | `object` |  |
| `usage` | `object` |  |
| `usage.modelCalls` | `integer` | 0 for the rule checks; at most 1 with triage. |
| `usage.authoringCalls` | `integer` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/review" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/review/apply

**Apply a review fix.**

Applies one fix to the saved draft as a single edit. Never publishes. 409 DRAFT_MOVED, 422 FIX_UNAVAILABLE.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fixId` | `string` | Required |  |
| `draftHash` | `string or null` | Optional | The draft the fix was offered for; 409 DRAFT_MOVED when it changed since. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `draftHash` | `string` |  |
| `previousDraftHash` | `string` |  |
| `draftSource` | `string or null` |  |
| `draftSourceFormat` | `string or null`, one of `yaml`, `json` |  |
| `applied` | `object` |  |
| `applied.fixId` | `string` |  |
| `applied.code` | `string` |  |
| `applied.title` | `string` |  |
| `applied.label` | `string` |  |
| `applied.releaseType` | `string`, one of `initial`, `major`, `minor`, `patch`, `none` |  |
| `applied.nextRelease` | `object or null` |  |
| `review` | `object` | The draft reviewed again after the fix. |
| `review.draftHash` | `string` |  |
| `review.saved` | `boolean` | False when unsaved source was reviewed. |
| `review.ok` | `boolean` | False when the source does not parse; `errors` says why. |
| `review.errors` | `array of { "path": string, "message": string }` |  |
| `review.estimate` | `object or null` | The estimated tokens and cost of one call, with every list at its limit. |
| `review.findings` | `array` | Worst first. |
| `review.triage` | `object or null` | The judgment checks when `triage` was asked for; null otherwise. |
| `review.usage` | `object` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/review/apply" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fixId":"<fixId>"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/review/dismiss

**Dismiss a finding.**

"Not a problem" / "Not now" on a Review finding (rule or judgment check), by its finding id. Records the dismissal on the audit trail (codes and paths only); the draft is unchanged. "Not a problem" also hides the finding on this Decision until the part of the Definition it is about changes (`subjectHash`, or the saved draft's). 422 FINDING_UNAVAILABLE for an id no check has.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `findingId` | `string` | Required | `<check>:<path>`, as a review returned it. |
| `reason` | `string`, one of `not_a_problem`, `not_now` | Required | not_a_problem: the check was wrong (how the checks are improved); not_now: set aside. |
| `probability` | `number or null` | Optional | The judgment check's probability as shown; ignored for a rule check. |
| `reviewer` | `string or null` | Optional | Which review check made the finding, with its version, for a judgment check. |
| `subjectHash` | `string or null` | Optional | findingSubjectHash of the source the person saw; the saved draft's when absent. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `dismissed` | `string` |  |
| `reason` | `string`, one of `not_a_problem`, `not_now` |  |
| `hidden` | `object or null` | The hidden finding, for not_a_problem; null for not_now. |
| `hidden.findingId` | `string` | `<check>:<path>`. |
| `hidden.code` | `string` |  |
| `hidden.path` | `string` |  |
| `hidden.subjectHash` | `string` | findingSubjectHash ( |
| `hidden.dismissedAt` | `integer` | Unix seconds. |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/review/dismiss" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"findingId":"<findingId>","reason":"not_a_problem"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/review/suggest

**Suggest a fix for a finding.**

Suggests a fix for one finding of the assistant review: a patch scoped to the finding's paths, checked by the compiler, with the same review question asked again of the rewrite. 402 FAIR_USE_REACHED, 409 DRAFT_MOVED, 422 FINDING_UNAVAILABLE, 503 REVIEW_UNAVAILABLE when the assistant review can't run.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `findingId` | `string` | Required |  |
| `draftHash` | `string or null` | Optional | The draft the finding was found on; 409 DRAFT_MOVED when it changed since. |
| `retryOf` | `string or null` | Optional | "Try again": a Not verified suggestion for this finding, whose verification is fed back. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string or null` | Pass it to /draft/review/suggestions/{id}/accept; null when there is no rewrite. |
| `findingId` | `string` |  |
| `code` | `string` |  |
| `path` | `string` |  |
| `title` | `string` |  |
| `outcome` | `string`, one of `suggested`, `no_rewrite` |  |
| `message` | `string or null` |  |
| `howToFix` | `string` |  |
| `explanation` | `string or null` |  |
| `operations` | `array of { "op": string, "path": string, "value": any JSON value, "to": string }` |  |
| `sourceAfter` | `string or null` |  |
| `preservedFormatting` | `boolean` |  |
| `diff` | `object or null` |  |
| `diff.lines` | `array of { "kind": string, "text": string }` |  |
| `diff.added` | `integer` |  |
| `diff.removed` | `integer` |  |
| `unifiedDiff` | `string or null` |  |
| `effect` | `object or null` | What a fix would do: whether it compiles, its release and the cost of one call. |
| `effect.compiles` | `boolean` |  |
| `effect.errors` | `array of { "path": string, "message": string }` |  |
| `effect.change` | `object` | This change alone. |
| `effect.nextRelease` | `object or null` | The draft's next release with this change, against the latest published version. |
| `effect.estimate` | `object` |  |
| `verification` | `object or null` |  |
| `verification.status` | `string`, one of `verified`, `not_verified`, `unavailable` |  |
| `verification.code` | `string` |  |
| `verification.before` | `number` |  |
| `verification.after` | `number or null` | The same check re-asked on the rewrite; null when the question was removed. |
| `verification.threshold` | `number` |  |
| `verification.removed` | `boolean` |  |
| `verification.questionIds` | `array of string` |  |
| `verification.newFindings` | `array of { "id": string, "code": string, "path": string, "title": string, "probability": number }` |  |
| `verification.message` | `string or null` |  |
| `canAccept` | `boolean` |  |
| `attemptsLeft` | `integer` | Rewrites left for this finding on this draft (2 in all; 422 SUGGESTION_LIMIT after). |
| `provenance` | `object` |  |
| `provenance.reviewer` | `string` |  |
| `provenance.model` | `string` |  |
| `usage` | `object` |  |
| `usage.authoringCalls` | `integer` |  |
| `usage.authoringInputTokens` | `integer` |  |
| `usage.authoringOutputTokens` | `integer` |  |
| `usage.modelCalls` | `integer` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/review/suggest" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"findingId":"<findingId>"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/review/suggestions/{suggestionId}/accept

**Accept a suggested fix.**

Accepts a verified suggestion into the saved draft as one edit. Never publishes. 409 DRAFT_MOVED, 422 SUGGESTION_UNAVAILABLE.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |
| `suggestionId` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `draftHash` | `string or null` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `draftHash` | `string` |  |
| `previousDraftHash` | `string` |  |
| `draftSource` | `string or null` |  |
| `draftSourceFormat` | `string or null`, one of `yaml`, `json` |  |
| `applied` | `object` |  |
| `applied.fixId` | `string` |  |
| `applied.code` | `string` |  |
| `applied.title` | `string` |  |
| `applied.label` | `string` |  |
| `applied.releaseType` | `string`, one of `initial`, `major`, `minor`, `patch`, `none` |  |
| `applied.nextRelease` | `object or null` |  |
| `review` | `object` | The draft reviewed again after the fix. |
| `review.draftHash` | `string` |  |
| `review.saved` | `boolean` | False when unsaved source was reviewed. |
| `review.ok` | `boolean` | False when the source does not parse; `errors` says why. |
| `review.errors` | `array of { "path": string, "message": string }` |  |
| `review.estimate` | `object or null` | The estimated tokens and cost of one call, with every list at its limit. |
| `review.findings` | `array` | Worst first. |
| `review.triage` | `object or null` | The judgment checks when `triage` was asked for; null otherwise. |
| `review.usage` | `object` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/review/suggestions/<suggestionId>/accept" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## The Definition assistant

### POST /v1/organisations/{org}/decisions/{slug}/draft/assist

**Ask the Definition assistant.**

"I'm trying to…": the Definition assistant reads this Decision through the same read tools an agent has (never the inputs of recorded runs) and answers with at most one proposal. 402 FAIR_USE_REACHED, 409 DRAFT_MOVED, 422 SUGGESTION_LIMIT.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `goal` | `string` | Required | What the author is trying to do, in their words. |
| `draftHash` | `string or null` | Optional | 409 DRAFT_MOVED when the saved draft changed since. |
| `retryOf` | `string or null` | Optional | "Try another": the id of the earlier answer to the same goal (2 asks per goal per draft). |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `goal` | `string` |  |
| `draftHash` | `string` |  |
| `intent` | `string`, one of `add_judgment`, `change_behaviour`, `reduce_cost`, `explain_behaviour`, `restructure`, `not_a_definition_change` |  |
| `answer` | `string` |  |
| `reads` | `array of { "tool": string, "ok": boolean, "summary": string }` |  |
| `proposal` | `{ "kind": string, "id": string, "tool": string, "arguments": object, "why": string, "effect": { "summary": string, "detail": any JSON value }, "canAccept": boolean, "blockedReason": string or null } or null or { "kind": string, "brief": string, "suggestion": { "id": string or null, "findingId": string, "code": string, "path": string, "title": string, "outcome": string, "message": string or null, "howToFix": string, "explanation": string or null, "operations": array of any JSON value, "sourceAfter": string or null, "preservedFormatting": boolean, "diff": { "lines": any JSON value, "added": any JSON value, "removed": any JSON value } or null, "unifiedDiff": string or null, "effect": { "compiles": any JSON value, "errors": any JSON value, "change": any JSON value, "nextRelease": any JSON value, "estimate": any JSON value } or null, "verification": { "status": any JSON value, "code": any JSON value, "before": any JSON value, "after": any JSON value, "threshold": any JSON value, "removed": any JSON value, "questionIds": any JSON value, "newFindings": any JSON value, "message": any JSON value } or null, "canAccept": boolean, "attemptsLeft": integer, "provenance": { "reviewer": any JSON value, "model": any JSON value }, "usage": { "authoringCalls": any JSON value, "authoringInputTokens": any JSON value, "authoringOutputTokens": any JSON value, "modelCalls": any JSON value } } } or null` |  |
| `capped` | `boolean` |  |
| `attemptsLeft` | `integer` |  |
| `model` | `string` |  |
| `usage` | `object` |  |
| `usage.authoringCalls` | `integer` |  |
| `usage.authoringInputTokens` | `integer` |  |
| `usage.authoringOutputTokens` | `integer` |  |
| `usage.modelCalls` | `integer` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/assist" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal":"<goal>"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/draft/assist/proposals/{proposalId}/accept

**Accept a proposed action.**

Runs an action proposal as the person accepting it. 409 PROPOSAL_UNAVAILABLE or 422 PROPOSAL_REFUSED.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |
| `proposalId` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `tool` | `string` |  |
| `ok` | `boolean` |  |
| `result` | `any JSON value` |  |
| `message` | `string or null` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/draft/assist/proposals/<proposalId>/accept" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```
