Reference
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
POST /v1/{org}/{decision}
Call a Decision
Answers one call with the release your accepts range or version chooses, and records it.
Headers
AuthorizationRequiredstringThe runtime key, asBearer <key>. It decides which environment answers.X-TypeSafe-KeyOptionalstringYour TypeSafe key, for a BYOK environment with no key stored. Leave it out for a Managed environment, and never send it on Relay.Idempotency-KeyOptionalstringAnswers a call once: a retry with the same key gets the first answer.X-Correlation-IdOptionalstringTies the call to the rest of your request, ascorrelationIddoes.
Body
inputRequiredstring or array or objectThe input your Definition'sstate_schemadescribes.versionOptionalintegerat least 1An exact revision to answer with. Sendversionoraccepts, not both.acceptsOptionalstringat most 40 charactersThe releases you accept, such as^1.0.0. A caller that accepts^1gets a 1.x release or 409 INCOMPATIBLE_VERSION, never 2.x.subjectOptionalstring1 to 200 charactersA stable id for the thing being decided, so a canary gives it the same release every time.referenceOptionalobjectYour own record this call is about, such as{ "type": "order", "id": "A-1042" }.reference.typeRequiredstring1 to 40 charactersWhat kind of record it is.reference.idRequiredstring1 to 200 charactersIts id.correlationIdOptionalstring1 to 200 charactersAn id that ties the call to the rest of your request.
Answer
runIdstringThe call's run, in the Decision log.decisionstringThe Decision's name.identifierstringThe Decision's identifier, organisation/name.environmentstringThe environment that answered.versionnumberThe exact revision that answered.semanticVersionstringIts semantic release.rolestringHow the release was served: primary, or a canary's variant.answersobjectThe native answers, by question name.latencyMsnumberHow long the call took, in milliseconds.
Headers it answers with
Retry-AfterstringAfter a 429 or a 503: how many seconds to wait before trying again.X-RateLimit-LimitstringHow many calls your organisation may make this minute.X-RateLimit-RemainingstringHow many of them are left.
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
AuthorizationRequiredstringThe runtime key, asBearer <key>. It decides which environment answers.
Answer
decisionstringThe Decision's name.identifierstringThe Decision's identifier, organisation/name.environmentstringThe environment that answered.versionnumberThe exact revision that answered.semanticVersionstringIts semantic release.planHashstringA fingerprint of the primary release's compiled plan.versionsarrayEvery release deployed in the environment, with its role and weight.modelstringThe model the primary release is pinned to.state_schemaobjectThe input the primary release takes.questionsobjectThe questions the primary release answers.
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
AuthorizationRequiredstringThe runtime key, asBearer <key>. It decides which environment answers.
Body
inputRequiredstring or array or objectThe input your Definition'sstate_schemadescribes.versionOptionalintegerat least 1An exact revision to answer with. Sendversionoraccepts, not both.acceptsOptionalstringat most 40 charactersThe releases you accept, such as^1.0.0. A caller that accepts^1gets a 1.x release or 409 INCOMPATIBLE_VERSION, never 2.x.subjectOptionalstring1 to 200 charactersA stable id for the thing being decided, so a canary gives it the same release every time.referenceOptionalobjectYour own record this call is about, such as{ "type": "order", "id": "A-1042" }.reference.typeRequiredstring1 to 40 charactersWhat kind of record it is.reference.idRequiredstring1 to 200 charactersIts id.correlationIdOptionalstring1 to 200 charactersAn id that ties the call to the rest of your request.
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
AuthorizationRequiredstringThe runtime key, asBearer <key>. It decides which environment answers.
Body
tokenRequiredstring1 to 8,192 charactersThe token prepare answered with. It can be used once, within 10 minutes.responseRequired{ "status": integer, "body": string, "requestId": string or null, "sentAt": integer, "receivedAt": integer, "requestHash": string } or { "error": "network", "message": string, "requestHash": string }TypeSafe's response as your app received it: its status, its body as text, unparsed, and itsx-typesafe-request-idheader asrequestId. When TypeSafe couldn't be reached,{ "error": "network" }instead.
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
INVALID_IDEMPOTENCY_KEY400The Idempotency-Key header is too long.INVALID_INPUT400The input doesn't fit the state schema;errorssays where.TYPESAFE_KEY_NOT_SENT400A relayed call sent X-TypeSafe-Key to TypeFuse; leave it out.TYPESAFE_KEY_NOT_USED400A Managed environment was sent a TypeSafe key; leave it out.TYPESAFE_KEY_REQUIRED400A BYOK call with no TypeSafe key, where none is stored for the environment.VALIDATION_ERROR400The body isn't one the runtime takes:input, andversionoracceptsbut not both.errorssays what is wrong.TOKEN_INVALID401The relay token isn't one TypeFuse made.UNAUTHORIZED401The runtime key is missing or wrong.PLAN_LIMIT402Your plan doesn't serve this call;limitsays which part of the plan. See Plans and usage.OLD_KEYS_STOPPED403The Decision moved to another organisation, which no longer takes the old organisation's keys; call it with a key from its new organisation.TOKEN_MISMATCH403The relay token was prepared for another key or Decision.NOT_DEPLOYED404Nothing is deployed in the key's environment.NOT_FOUND404No such Decision for this key.VERSION_NOT_DEPLOYED404That revision isn't deployed in the key's environment;versionslists the ones that are.IDEMPOTENCY_IN_PROGRESS409A call with the same Idempotency-Key is still being answered; try again in a moment.INCOMPATIBLE_VERSION409No deployed release is in the range you accept;acceptsrepeats your range andversionslists the releases deployed.PLAN_NOT_AVAILABLE409The release a relayed call was prepared on is no longer deployed; prepare it again.RELAY_REQUIRED409The environment takes only relayed calls.ROUTE_NOT_ENABLED409The environment doesn't take relayed calls.TOKEN_USED409The relay token has already been used.TOKEN_EXPIRED410The relay token is more than 10 minutes old; prepare the call again.TOO_LARGE413The request, or the response it reports, is too large.DAILY_LIMIT429Your organisation has made its calls for today; calls resume at midnight UTC, andretryAfterSecondssays when.RATE_LIMITED429Your organisation has made its plan's calls for this minute, across all its keys; wait for Retry-After.retryAfterSecondsandlimitsay the same.TOO_MANY_PENDING429This key has too many prepared calls waiting; complete them or let them expire.retryAfterSecondssays when to try again.INTERNAL500Something went wrong on TypeFuse's side; try again.PROVIDER_CREDENTIAL_REJECTED502TypeSafe refused the key stored for the environment. An owner or admin can replace it; meanwhile, send a key in X-TypeSafe-Key.PROVIDER_ERROR502TypeSafe couldn't answer; the call is still recorded.NOT_RECORDED503With Record before answering on, the call couldn't be recorded, so no answer was sent; try again.PAUSED503Calls to this Decision are paused for now; wait for Retry-After, also given asretryAfterSeconds.PROVIDER_CREDENTIAL_UNAVAILABLE503The 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_UNAVAILABLE503Something TypeFuse depends on failed for a moment; try again.requestIdnames the request if you write to us.