# Runtime API

Call a deployed Decision over HTTP: the request, its headers, the answer and every error code.

Your software calls a deployed Decision at `https://run.typefuse.dev`, the runtime, with a runtime key for one environment: the key decides which environment answers. The input is checked, the release chosen and the call recorded on TypeFuse's servers, so your code sends the input and reads the answers.

Every request carries the key as `Authorization: Bearer <key>`. Bodies and answers are JSON.

- [Calling a Decision](https://typefuse.dev/guides/calling)
- [Versions and releases](https://typefuse.dev/guides/versions)

## Calling

### POST /v1/{org}/{decision}

**Call a Decision.**

Answers one call with the release your `accepts` range or `version` chooses, and records it.

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Required | The runtime key, as `Bearer <key>`. It decides which environment answers. |
| `X-TypeSafe-Key` | `string` | Optional | Your TypeSafe key, for a BYOK environment with no key stored. Leave it out for a Managed environment, and never send it on Relay. |
| `Idempotency-Key` | `string` | Optional | Answers a call once: a retry with the same key gets the first answer. |
| `X-Correlation-Id` | `string` | Optional | Ties the call to the rest of your request, as `correlationId` does. |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | `string or array or object` | Required | The input your Definition's `state_schema` describes. |
| `version` | `integer`, at least 1 | Optional | An exact revision to answer with. Send `version` or `accepts`, not both. |
| `accepts` | `string`, at most 40 characters | Optional | The releases you accept, such as `^1.0.0`. A caller that accepts `^1` gets a 1.x release or 409 INCOMPATIBLE_VERSION, never 2.x. |
| `subject` | `string`, 1 to 200 characters | Optional | A stable id for the thing being decided, so a canary gives it the same release every time. |
| `reference` | `object` | Optional | Your own record this call is about, such as `{ "type": "order", "id": "A-1042" }`. |
| `reference.type` | `string`, 1 to 40 characters | Required | What kind of record it is. |
| `reference.id` | `string`, 1 to 200 characters | Required | Its id. |
| `correlationId` | `string`, 1 to 200 characters | Optional | An id that ties the call to the rest of your request. |

**Answer**

| Name | Type | Description |
| --- | --- | --- |
| `runId` | `string` | The call's run, in the Decision log. |
| `decision` | `string` | The Decision's name. |
| `identifier` | `string` | The Decision's identifier, organisation/name. |
| `environment` | `string` | The environment that answered. |
| `version` | `number` | The exact revision that answered. |
| `semanticVersion` | `string` | Its semantic release. |
| `role` | `string` | How the release was served: primary, or a canary's variant. |
| `answers` | `object` | The native answers, by question name. |
| `latencyMs` | `number` | How long the call took, in milliseconds. |

**Headers it answers with**

| Name | Type | Description |
| --- | --- | --- |
| `Retry-After` | `string` | After a 429 or a 503: how many seconds to wait before trying again. |
| `X-RateLimit-Limit` | `string` | How many calls your organisation may make this minute. |
| `X-RateLimit-Remaining` | `string` | How many of them are left. |

```sh
curl https://run.typefuse.dev/v1/acme/refunds \
  -H "Authorization: Bearer $TYPEFUSE_KEY" \
  -H "X-TypeSafe-Key: $TYPESAFE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"request": "Arrived damaged", "days_since_delivery": 12}, "accepts": "^1.0.0"}'
```

### GET /v1/{org}/{decision}

**Describe what is deployed.**

What the key's environment serves: every release deployed there, and the primary release's model, state schema and questions.

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Required | The runtime key, as `Bearer <key>`. It decides which environment answers. |

**Answer**

| Name | Type | Description |
| --- | --- | --- |
| `decision` | `string` | The Decision's name. |
| `identifier` | `string` | The Decision's identifier, organisation/name. |
| `environment` | `string` | The environment that answered. |
| `version` | `number` | The exact revision that answered. |
| `semanticVersion` | `string` | Its semantic release. |
| `planHash` | `string` | A fingerprint of the primary release's compiled plan. |
| `versions` | `array` | Every release deployed in the environment, with its role and weight. |
| `model` | `string` | The model the primary release is pinned to. |
| `state_schema` | `object` | The input the primary release takes. |
| `questions` | `object` | The questions the primary release answers. |

```sh
curl https://run.typefuse.dev/v1/acme/refunds \
  -H "Authorization: Bearer $TYPEFUSE_KEY"
```

## Relay

For a TypeSafe key that must never leave your systems: TypeFuse prepares the request, your app sends it to TypeSafe with its own key, then hands the response back.

### POST /v1/{org}/{decision}/prepare

**Prepare a relayed call.**

Takes the ordinary call body and answers with a `token`, the release that will answer, and `call`: the `url`, `method`, `headers` and `body` to send to TypeSafe with your own key. When there is nothing to ask, `call` is null and the answers are already there.

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Required | The runtime key, as `Bearer <key>`. It decides which environment answers. |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | `string or array or object` | Required | The input your Definition's `state_schema` describes. |
| `version` | `integer`, at least 1 | Optional | An exact revision to answer with. Send `version` or `accepts`, not both. |
| `accepts` | `string`, at most 40 characters | Optional | The releases you accept, such as `^1.0.0`. A caller that accepts `^1` gets a 1.x release or 409 INCOMPATIBLE_VERSION, never 2.x. |
| `subject` | `string`, 1 to 200 characters | Optional | A stable id for the thing being decided, so a canary gives it the same release every time. |
| `reference` | `object` | Optional | Your own record this call is about, such as `{ "type": "order", "id": "A-1042" }`. |
| `reference.type` | `string`, 1 to 40 characters | Required | What kind of record it is. |
| `reference.id` | `string`, 1 to 200 characters | Required | Its id. |
| `correlationId` | `string`, 1 to 200 characters | Optional | An id that ties the call to the rest of your request. |

```sh
curl https://run.typefuse.dev/v1/acme/refunds/prepare \
  -H "Authorization: Bearer $TYPEFUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"request": "Arrived damaged", "days_since_delivery": 12}, "accepts": "^1.0.0"}'
```

### POST /v1/{org}/{decision}/complete

**Complete a relayed call.**

Hands back TypeSafe's response to a prepared call, and answers in the ordinary shape. Repeating the same completion is safe and gets the same answer.

**Headers**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Required | The runtime key, as `Bearer <key>`. It decides which environment answers. |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `string`, 1 to 8,192 characters | Required | The token prepare answered with. It can be used once, within 10 minutes. |
| `response` | `{ "status": integer, "body": string, "requestId": string or null, "sentAt": integer, "receivedAt": integer, "requestHash": string } or { "error": "network", "message": string, "requestHash": string }` | Required | TypeSafe's response as your app received it: its status, its body as text, unparsed, and its `x-typesafe-request-id` header as `requestId`. When TypeSafe couldn't be reached, `{ "error": "network" }` instead. |

```sh
curl https://run.typefuse.dev/v1/acme/refunds/complete \
  -H "Authorization: Bearer $TYPEFUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "<token>", "response": {"status": 200, "body": "<TypeSafe'"'"'s response>", "requestId": "<x-typesafe-request-id>"}}'
```

## Errors

A refusal answers with its HTTP status and `{ "code", "message" }`. Some carry more fields beside them, which each code's line names; the two Idempotency-Key refusals put the code and message under `error`.

### codes

**Every code a call can be refused with, by status.**

**Codes**

| Name | Type | Description |
| --- | --- | --- |
| `INVALID_IDEMPOTENCY_KEY` | `400` | The Idempotency-Key header is too long. |
| `INVALID_INPUT` | `400` | The input doesn't fit the state schema; `errors` says where. |
| `TYPESAFE_KEY_NOT_SENT` | `400` | A relayed call sent X-TypeSafe-Key to TypeFuse; leave it out. |
| `TYPESAFE_KEY_NOT_USED` | `400` | A Managed environment was sent a TypeSafe key; leave it out. |
| `TYPESAFE_KEY_REQUIRED` | `400` | A BYOK call with no TypeSafe key, where none is stored for the environment. |
| `VALIDATION_ERROR` | `400` | The body isn't one the runtime takes: `input`, and `version` or `accepts` but not both. `errors` says what is wrong. |
| `TOKEN_INVALID` | `401` | The relay token isn't one TypeFuse made. |
| `UNAUTHORIZED` | `401` | The runtime key is missing or wrong. |
| `PLAN_LIMIT` | `402` | Your plan doesn't serve this call; `limit` says which part of the plan. See Plans and usage. |
| `OLD_KEYS_STOPPED` | `403` | The Decision moved to another organisation, which no longer takes the old organisation's keys; call it with a key from its new organisation. |
| `TOKEN_MISMATCH` | `403` | The relay token was prepared for another key or Decision. |
| `NOT_DEPLOYED` | `404` | Nothing is deployed in the key's environment. |
| `NOT_FOUND` | `404` | No such Decision for this key. |
| `VERSION_NOT_DEPLOYED` | `404` | That revision isn't deployed in the key's environment; `versions` lists the ones that are. |
| `IDEMPOTENCY_IN_PROGRESS` | `409` | A call with the same Idempotency-Key is still being answered; try again in a moment. |
| `INCOMPATIBLE_VERSION` | `409` | No deployed release is in the range you accept; `accepts` repeats your range and `versions` lists the releases deployed. |
| `PLAN_NOT_AVAILABLE` | `409` | The release a relayed call was prepared on is no longer deployed; prepare it again. |
| `RELAY_REQUIRED` | `409` | The environment takes only relayed calls. |
| `ROUTE_NOT_ENABLED` | `409` | The environment doesn't take relayed calls. |
| `TOKEN_USED` | `409` | The relay token has already been used. |
| `TOKEN_EXPIRED` | `410` | The relay token is more than 10 minutes old; prepare the call again. |
| `TOO_LARGE` | `413` | The request, or the response it reports, is too large. |
| `DAILY_LIMIT` | `429` | Your organisation has made its calls for today; calls resume at midnight UTC, and `retryAfterSeconds` says when. |
| `RATE_LIMITED` | `429` | Your organisation has made its plan's calls for this minute, across all its keys; wait for Retry-After. `retryAfterSeconds` and `limit` say the same. |
| `TOO_MANY_PENDING` | `429` | This key has too many prepared calls waiting; complete them or let them expire. `retryAfterSeconds` says when to try again. |
| `INTERNAL` | `500` | Something went wrong on TypeFuse's side; try again. |
| `PROVIDER_CREDENTIAL_REJECTED` | `502` | TypeSafe refused the key stored for the environment. An owner or admin can replace it; meanwhile, send a key in X-TypeSafe-Key. |
| `PROVIDER_ERROR` | `502` | TypeSafe couldn't answer; the call is still recorded. |
| `NOT_RECORDED` | `503` | With Record before answering on, the call couldn't be recorded, so no answer was sent; try again. |
| `PAUSED` | `503` | Calls to this Decision are paused for now; wait for Retry-After, also given as `retryAfterSeconds`. |
| `PROVIDER_CREDENTIAL_UNAVAILABLE` | `503` | The TypeSafe key stored for the environment can't be used. Send a key in X-TypeSafe-Key, or ask an owner or admin to store a new one. |
| `TEMPORARILY_UNAVAILABLE` | `503` | Something TypeFuse depends on failed for a moment; try again. `requestId` names the request if you write to us. |
