Skip to content

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

  • AuthorizationRequiredstring
    The runtime key, as Bearer <key>. It decides which environment answers.
  • X-TypeSafe-KeyOptionalstring
    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-KeyOptionalstring
    Answers a call once: a retry with the same key gets the first answer.
  • X-Correlation-IdOptionalstring
    Ties the call to the rest of your request, as correlationId does.

Body

  • inputRequiredstring or array or object
    The input your Definition's state_schema describes.
  • versionOptionalintegerat least 1
    An exact revision to answer with. Send version or accepts, not both.
  • acceptsOptionalstringat most 40 characters
    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.
  • subjectOptionalstring1 to 200 characters
    A stable id for the thing being decided, so a canary gives it the same release every time.
  • referenceOptionalobject
    Your own record this call is about, such as { "type": "order", "id": "A-1042" }.
  • reference.typeRequiredstring1 to 40 characters
    What kind of record it is.
  • reference.idRequiredstring1 to 200 characters
    Its id.
  • correlationIdOptionalstring1 to 200 characters
    An id that ties the call to the rest of your request.

Answer

  • runIdstring
    The call's run, in the Decision log.
  • decisionstring
    The Decision's name.
  • identifierstring
    The Decision's identifier, organisation/name.
  • environmentstring
    The environment that answered.
  • versionnumber
    The exact revision that answered.
  • semanticVersionstring
    Its semantic release.
  • rolestring
    How the release was served: primary, or a canary's variant.
  • answersobject
    The native answers, by question name.
  • latencyMsnumber
    How long the call took, in milliseconds.

Headers it answers with

  • Retry-Afterstring
    After a 429 or a 503: how many seconds to wait before trying again.
  • X-RateLimit-Limitstring
    How many calls your organisation may make this minute.
  • X-RateLimit-Remainingstring
    How many of them are left.
Terminal
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

  • AuthorizationRequiredstring
    The runtime key, as Bearer <key>. It decides which environment answers.

Answer

  • decisionstring
    The Decision's name.
  • identifierstring
    The Decision's identifier, organisation/name.
  • environmentstring
    The environment that answered.
  • versionnumber
    The exact revision that answered.
  • semanticVersionstring
    Its semantic release.
  • planHashstring
    A fingerprint of the primary release's compiled plan.
  • versionsarray
    Every release deployed in the environment, with its role and weight.
  • modelstring
    The model the primary release is pinned to.
  • state_schemaobject
    The input the primary release takes.
  • questionsobject
    The questions the primary release answers.
Terminal
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

  • AuthorizationRequiredstring
    The runtime key, as Bearer <key>. It decides which environment answers.

Body

  • inputRequiredstring or array or object
    The input your Definition's state_schema describes.
  • versionOptionalintegerat least 1
    An exact revision to answer with. Send version or accepts, not both.
  • acceptsOptionalstringat most 40 characters
    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.
  • subjectOptionalstring1 to 200 characters
    A stable id for the thing being decided, so a canary gives it the same release every time.
  • referenceOptionalobject
    Your own record this call is about, such as { "type": "order", "id": "A-1042" }.
  • reference.typeRequiredstring1 to 40 characters
    What kind of record it is.
  • reference.idRequiredstring1 to 200 characters
    Its id.
  • correlationIdOptionalstring1 to 200 characters
    An id that ties the call to the rest of your request.
Terminal
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

  • AuthorizationRequiredstring
    The runtime key, as Bearer <key>. It decides which environment answers.

Body

  • tokenRequiredstring1 to 8,192 characters
    The 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 its x-typesafe-request-id header as requestId. When TypeSafe couldn't be reached, { "error": "network" } instead.
Terminal
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_KEY400
    The Idempotency-Key header is too long.
  • INVALID_INPUT400
    The input doesn't fit the state schema; errors says where.
  • TYPESAFE_KEY_NOT_SENT400
    A relayed call sent X-TypeSafe-Key to TypeFuse; leave it out.
  • TYPESAFE_KEY_NOT_USED400
    A Managed environment was sent a TypeSafe key; leave it out.
  • TYPESAFE_KEY_REQUIRED400
    A BYOK call with no TypeSafe key, where none is stored for the environment.
  • VALIDATION_ERROR400
    The body isn't one the runtime takes: input, and version or accepts but not both. errors says what is wrong.
  • TOKEN_INVALID401
    The relay token isn't one TypeFuse made.
  • UNAUTHORIZED401
    The runtime key is missing or wrong.
  • PLAN_LIMIT402
    Your plan doesn't serve this call; limit says which part of the plan. See Plans and usage.
  • OLD_KEYS_STOPPED403
    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_MISMATCH403
    The relay token was prepared for another key or Decision.
  • NOT_DEPLOYED404
    Nothing is deployed in the key's environment.
  • NOT_FOUND404
    No such Decision for this key.
  • VERSION_NOT_DEPLOYED404
    That revision isn't deployed in the key's environment; versions lists the ones that are.
  • IDEMPOTENCY_IN_PROGRESS409
    A call with the same Idempotency-Key is still being answered; try again in a moment.
  • INCOMPATIBLE_VERSION409
    No deployed release is in the range you accept; accepts repeats your range and versions lists the releases deployed.
  • PLAN_NOT_AVAILABLE409
    The release a relayed call was prepared on is no longer deployed; prepare it again.
  • RELAY_REQUIRED409
    The environment takes only relayed calls.
  • ROUTE_NOT_ENABLED409
    The environment doesn't take relayed calls.
  • TOKEN_USED409
    The relay token has already been used.
  • TOKEN_EXPIRED410
    The relay token is more than 10 minutes old; prepare the call again.
  • TOO_LARGE413
    The request, or the response it reports, is too large.
  • DAILY_LIMIT429
    Your organisation has made its calls for today; calls resume at midnight UTC, and retryAfterSeconds says when.
  • RATE_LIMITED429
    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_PENDING429
    This key has too many prepared calls waiting; complete them or let them expire. retryAfterSeconds says when to try again.
  • INTERNAL500
    Something went wrong on TypeFuse's side; try again.
  • PROVIDER_CREDENTIAL_REJECTED502
    TypeSafe refused the key stored for the environment. An owner or admin can replace it; meanwhile, send a key in X-TypeSafe-Key.
  • PROVIDER_ERROR502
    TypeSafe couldn't answer; the call is still recorded.
  • NOT_RECORDED503
    With Record before answering on, the call couldn't be recorded, so no answer was sent; try again.
  • PAUSED503
    Calls to this Decision are paused for now; wait for Retry-After, also given as retryAfterSeconds.
  • PROVIDER_CREDENTIAL_UNAVAILABLE503
    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_UNAVAILABLE503
    Something TypeFuse depends on failed for a moment; try again. requestId names the request if you write to us.