# API: Versions and models

Publish versions, run them, and try a newer model before you move to it.

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)

## Versions

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

**List versions.**

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `versions` | `array` |  |

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

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

**Publish a version.**

**Path**

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

**Body**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `number` | `integer` | Immutable publication sequence used by /v/{number} and runtime pins. |
| `semanticVersion` | `string` | Automatically calculated consumer-impact version, such as 2.1.0. |
| `releaseType` | `string`, one of `initial`, `major`, `minor`, `patch` |  |
| `changeSummary` | `array of { "severity": string, "area": string, "path": string, "message": string }` |  |
| `label` | `string or null` |  |
| `definitionHash` | `string` |  |
| `readmeHash` | `string` |  |
| `planHash` | `string` |  |
| `compilerVersion` | `string` |  |
| `provider` | `string` |  |
| `providerModel` | `string` |  |
| `publishedBy` | `integer` |  |
| `publishedAt` | `string` |  |
| `readmeMarkdown` | `string` |  |
| `definition` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `definitionSource` | `string` |  |
| `definitionSourceFormat` | `string`, one of `yaml`, `json` |  |
| `plan` | `object` | The compiled ExecutionPlan. Its shape is owned by |

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

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

**Get the latest version.**

The newest version whole (the highest number); 404 NOT_FOUND before the first.

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `number` | `integer` | Immutable publication sequence used by /v/{number} and runtime pins. |
| `semanticVersion` | `string` | Automatically calculated consumer-impact version, such as 2.1.0. |
| `releaseType` | `string`, one of `initial`, `major`, `minor`, `patch` |  |
| `changeSummary` | `array of { "severity": string, "area": string, "path": string, "message": string }` |  |
| `label` | `string or null` |  |
| `definitionHash` | `string` |  |
| `readmeHash` | `string` |  |
| `planHash` | `string` |  |
| `compilerVersion` | `string` |  |
| `provider` | `string` |  |
| `providerModel` | `string` |  |
| `publishedBy` | `integer` |  |
| `publishedAt` | `string` |  |
| `readmeMarkdown` | `string` |  |
| `definition` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `definitionSource` | `string` |  |
| `definitionSourceFormat` | `string`, one of `yaml`, `json` |  |
| `plan` | `object` | The compiled ExecutionPlan. Its shape is owned by |

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

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

**Get a version.**

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `number` | `integer` | Immutable publication sequence used by /v/{number} and runtime pins. |
| `semanticVersion` | `string` | Automatically calculated consumer-impact version, such as 2.1.0. |
| `releaseType` | `string`, one of `initial`, `major`, `minor`, `patch` |  |
| `changeSummary` | `array of { "severity": string, "area": string, "path": string, "message": string }` |  |
| `label` | `string or null` |  |
| `definitionHash` | `string` |  |
| `readmeHash` | `string` |  |
| `planHash` | `string` |  |
| `compilerVersion` | `string` |  |
| `provider` | `string` |  |
| `providerModel` | `string` |  |
| `publishedBy` | `integer` |  |
| `publishedAt` | `string` |  |
| `readmeMarkdown` | `string` |  |
| `definition` | `object` | The authored Definition: `format: 3`, `model`, `state_schema`, optional `context` and `questions`. |
| `definitionSource` | `string` |  |
| `definitionSourceFormat` | `string`, one of `yaml`, `json` |  |
| `plan` | `object` | The compiled ExecutionPlan. Its shape is owned by |

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

### POST /v1/organisations/{org}/decisions/{slug}/versions/{number}/run

**Run a version.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |
| `number` | `integer` | 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/versions/3/run" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"<input>"}'
```

## Models

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

**Get the model status.**

Moving to a newer model: where the Decision's model stands (the release live in production, else the latest), a newer model to try and a retirement date.

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `model` | `string` | The model of the release live in production, else the latest release, else the draft. |
| `version` | `object or null` | That release; null when nothing is published. |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `retirement` | `object or null` | When a model retires, once the provider announces a date. |
| `retirement.date` | `string` | ISO date (YYYY-MM-DD) its calls stop. |
| `retirement.daysLeft` | `integer` | Whole days left; 0 once it has retired. |
| `newer` | `object or null` | The newest released model of the same family, when it is newer. |
| `newer.model` | `string` |  |
| `newer.released` | `string or null` | ISO date the provider released it; null when not recorded. |
| `latestTrial` | `object or null` | The latest trial of `newer`, so a choice to stay is remembered. |
| `latestTrial.id` | `string` |  |
| `latestTrial.fromModel` | `string` | The model the release tried was published with. |
| `latestTrial.model` | `string` | The model tried in its place. |
| `latestTrial.outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `latestTrial.releasedVersionId` | `string or null` | The version a release made. |
| `latestTrial.createdAt` | `string or null` |  |
| `latestTrial.decidedAt` | `string or null` |  |

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

### GET /v1/organisations/{org}/decisions/{slug}/model-trials

**List model trials.**

Newest first; `model` narrows to trials of one model.

**Path**

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

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | `string` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `trials` | `array` |  |

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

### POST /v1/organisations/{org}/decisions/{slug}/model-trials

**Start a model trial.**

Asks the Test set of the release live in production (or else the latest release) twice: as published and with only its model changed. The draft is untouched. `model` defaults to the newer model `GET …/model` names; only a newer, released model can be tried. 422 INVALID_MODEL, UNKNOWN_MODEL, NOT_NEWER, SAME_MODEL, MODEL_RETIRED, NO_CASES or INVALID_CASES; 409 NO_RELEASE. With X-TypeSafe-Key the trial runs on your own TypeSafe key.

**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 |
| --- | --- | --- | --- |
| `model` | `string` | Optional | An exact model version, as a Definition's `model` names one; the newer model by default. |

**Answer (201)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `fromModel` | `string` | The model the release tried was published with. |
| `model` | `string` | The model tried in its place. |
| `outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `releasedVersionId` | `string or null` | The version a release made. |
| `createdAt` | `string or null` |  |
| `decidedAt` | `string or null` |  |
| `version` | `object or null` | The release tried. |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `released` | `object or null` | The version a release made. |
| `released.number` | `integer` |  |
| `released.semanticVersion` | `string` |  |
| `baseline` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `baseline.testRunId` | `string` |  |
| `baseline.evaluationId` | `string or null` |  |
| `baseline.caseCount` | `integer` |  |
| `baseline.agreedCount` | `integer` |  |
| `baseline.errorCount` | `integer` |  |
| `baseline.latencyMs` | `integer` |  |
| `candidate` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `candidate.testRunId` | `string` |  |
| `candidate.evaluationId` | `string or null` |  |
| `candidate.caseCount` | `integer` |  |
| `candidate.agreedCount` | `integer` |  |
| `candidate.errorCount` | `integer` |  |
| `candidate.latencyMs` | `integer` |  |
| `changed` | `array` |  |
| `undecided` | `integer` | Changed cases not yet decided; releasing waits for none. |

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

### GET /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}

**Get a model trial.**

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `fromModel` | `string` | The model the release tried was published with. |
| `model` | `string` | The model tried in its place. |
| `outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `releasedVersionId` | `string or null` | The version a release made. |
| `createdAt` | `string or null` |  |
| `decidedAt` | `string or null` |  |
| `version` | `object or null` | The release tried. |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `released` | `object or null` | The version a release made. |
| `released.number` | `integer` |  |
| `released.semanticVersion` | `string` |  |
| `baseline` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `baseline.testRunId` | `string` |  |
| `baseline.evaluationId` | `string or null` |  |
| `baseline.caseCount` | `integer` |  |
| `baseline.agreedCount` | `integer` |  |
| `baseline.errorCount` | `integer` |  |
| `baseline.latencyMs` | `integer` |  |
| `candidate` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `candidate.testRunId` | `string` |  |
| `candidate.evaluationId` | `string or null` |  |
| `candidate.caseCount` | `integer` |  |
| `candidate.agreedCount` | `integer` |  |
| `candidate.errorCount` | `integer` |  |
| `candidate.latencyMs` | `integer` |  |
| `changed` | `array` |  |
| `undecided` | `integer` | Changed cases not yet decided; releasing waits for none. |

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

### POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/cases/{caseId}

**Decide a trial case.**

Which model was right about a case that changed. 404 CASE_NOT_FOUND; 409 NOT_CHANGED, CASE_CHANGED (its input was edited after the trial) or ALREADY_DECIDED; 422 CASE_INVALID.

**Path**

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

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `right` | `string`, one of `baseline`, `candidate` | Required | Which model answered the case rightly. "candidate" makes the case expect its answers. |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `fromModel` | `string` | The model the release tried was published with. |
| `model` | `string` | The model tried in its place. |
| `outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `releasedVersionId` | `string or null` | The version a release made. |
| `createdAt` | `string or null` |  |
| `decidedAt` | `string or null` |  |
| `version` | `object or null` | The release tried. |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `released` | `object or null` | The version a release made. |
| `released.number` | `integer` |  |
| `released.semanticVersion` | `string` |  |
| `baseline` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `baseline.testRunId` | `string` |  |
| `baseline.evaluationId` | `string or null` |  |
| `baseline.caseCount` | `integer` |  |
| `baseline.agreedCount` | `integer` |  |
| `baseline.errorCount` | `integer` |  |
| `baseline.latencyMs` | `integer` |  |
| `candidate` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `candidate.testRunId` | `string` |  |
| `candidate.evaluationId` | `string or null` |  |
| `candidate.caseCount` | `integer` |  |
| `candidate.agreedCount` | `integer` |  |
| `candidate.errorCount` | `integer` |  |
| `candidate.latencyMs` | `integer` |  |
| `changed` | `array` |  |
| `undecided` | `integer` | Changed cases not yet decided; releasing waits for none. |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/cases/<caseId>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"right":"baseline"}'
```

### POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/release

**Release the trial's model.**

Publishes the latest release with only its model changed (a minor release). 409 ALREADY_DECIDED, TRIAL_OUTDATED (a later release changed the Decision), ALREADY_ON_MODEL or NO_RELEASE; 422 CASES_UNDECIDED, MODEL_RETIRED, SOURCE_UNCHANGEABLE or COMPILE_FAILED.

**Path**

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

**Answer (201)**

| Name | Type | Description |
| --- | --- | --- |
| `trial` | `object` | A trial of another model: both sides' figures and the cases that changed. |
| `trial.id` | `string` |  |
| `trial.fromModel` | `string` | The model the release tried was published with. |
| `trial.model` | `string` | The model tried in its place. |
| `trial.outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `trial.releasedVersionId` | `string or null` | The version a release made. |
| `trial.createdAt` | `string or null` |  |
| `trial.decidedAt` | `string or null` |  |
| `trial.version` | `object or null` | The release tried. |
| `trial.released` | `object or null` | The version a release made. |
| `trial.baseline` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `trial.candidate` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `trial.changed` | `array` |  |
| `trial.undecided` | `integer` | Changed cases not yet decided; releasing waits for none. |
| `version` | `object` |  |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `version.releaseType` | `string`, one of `initial`, `major`, `minor`, `patch`, `none` |  |
| `draftMoved` | `boolean` | The draft followed, because it matched the latest release; otherwise it is left as it was. |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/release" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/decisions/{slug}/model-trials/{trialId}/stay

**Stay on the current model.**

Stays on the current model; kept, so the Summary stops asking. 409 ALREADY_DECIDED.

**Path**

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

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `fromModel` | `string` | The model the release tried was published with. |
| `model` | `string` | The model tried in its place. |
| `outcome` | `string or null`, one of `released`, `stayed` | Null until someone releases the new model or stays. |
| `releasedVersionId` | `string or null` | The version a release made. |
| `createdAt` | `string or null` |  |
| `decidedAt` | `string or null` |  |
| `version` | `object or null` | The release tried. |
| `version.number` | `integer` |  |
| `version.semanticVersion` | `string` |  |
| `released` | `object or null` | The version a release made. |
| `released.number` | `integer` |  |
| `released.semanticVersion` | `string` |  |
| `baseline` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `baseline.testRunId` | `string` |  |
| `baseline.evaluationId` | `string or null` |  |
| `baseline.caseCount` | `integer` |  |
| `baseline.agreedCount` | `integer` |  |
| `baseline.errorCount` | `integer` |  |
| `baseline.latencyMs` | `integer` |  |
| `candidate` | `object` | One side of a trial: the Test run on one model and its evaluation. |
| `candidate.testRunId` | `string` |  |
| `candidate.evaluationId` | `string or null` |  |
| `candidate.caseCount` | `integer` |  |
| `candidate.agreedCount` | `integer` |  |
| `candidate.errorCount` | `integer` |  |
| `candidate.latencyMs` | `integer` |  |
| `changed` | `array` |  |
| `undecided` | `integer` | Changed cases not yet decided; releasing waits for none. |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/model-trials/<trialId>/stay" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```
