Skip to content

Reference

API: Deployments

Environments and what each serves: deploy, check, cancel and remove releases.

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

Environments

GET /v1/organisations/{org}/environments

List environments

Path

  • orgRequiredstring

Answer (200)

  • environmentsarray
  • requirePassingTestsboolean
    The organisation's "Require a passing Test set" rule.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/environments" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

Deployments

GET /v1/organisations/{org}/deployments

List the organisation's deployments

What is live where, across the organisation's decisions.

Path

  • orgRequiredstring

Answer (200)

  • deploymentsarray
  • environmentsarray
  • requirePassingTestsboolean
    The organisation's "Require a passing Test set" rule.
  • productionRoutestring
    How a new production environment's callers reach TypeSafe when its creator does not choose: passthrough (BYOK) for self-serve organisations, proxy (Managed) on Enterprise.One of proxy, passthrough, relay
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/deployments" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

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

List a Decision's deployments

Path

  • orgRequiredstring
  • slugRequiredstring

Answer (200)

  • currentarray
    The active deployment per environment, if any.
  • pendingarray
    Requests waiting for approval or a scheduled time: deploys, removals (action "remove") and line retirements (retires).
  • historyarray
    Every deployment, newest first.
  • environmentsarray
  • callsarray of { "environment": string, "versionNumber": integer, "semanticVersion": string, "last24h": integer, "last7d": integer }
    Calls answered per environment and release in the last 7 days (shadow runs left out), so the callers still using an older major line are visible before it is retired.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/deployments

Deploy a version

Pins a version to an environment and publishes the record the runtime reads.

Path

  • orgRequiredstring
  • slugRequiredstring

Body

  • environmentRequiredstring
  • versionNumberRequiredinteger
  • variantsOptionalarray of { "versionNumber": integer, "role": string, "weight": number }
    Canaries and shadows to run beside the primary; variant weights must sum to under 1.
  • noteOptionalstring or null
  • scheduledForOptionalstring or null
    ISO time at least a minute ahead; the deployment waits until then.
  • retireLinesOptionalboolean
    Default false: the newest release of every other major line serving here stays live for callers that accept it. True retires them with this deploy.

Answer (200)

  • idstring
  • actionstring
    What the row asks for. "deploy" puts versionId into service; "remove" takes the decision out of the environment. A pending "remove" is a removal request ("Removal requested"); once carried out its status is "removed", versionId is the primary it took out of service and variants lists the compatibility lines it kept available (empty when they were retired). A line retirement is a "deploy" row with retires set.One of deploy, remove
  • environmentstring
  • versionIdstring
  • versionNumberinteger
  • semanticVersionstring
  • variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }
  • notestring or null
  • statusstring
    One of pending, scheduled, active, superseded, removed, rejected, cancelled
  • kindstring
    One of manual, api, scheduled, release
  • deployedByinteger or null
    The person who asked, or null when a deploy token did.
  • tokenobject or null
    The deploy token that asked, if one did.
  • token.idstring
  • token.namestring
  • requestedViaobject or null
    The agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.
  • requestedVia.kindstring
    "token": a personal access token (an agent or a script); "connection": an app connected in the browser.One of token, connection
  • requestedVia.namestring
    The token's or the app's name, such as "Claude Code".
  • onBehalfOfinteger or null
    The person the request counts as coming from: deployedBy, or the maker of the deploy token.
  • scheduledForstring or null
    When it goes (or went) live, if it was scheduled.
  • deployedAtstring
  • endedAtstring or null
  • approvedByinteger or null
  • approvedAtstring or null
  • approvalNotestring or null
  • removalobject or null
    The options a removal was asked with; null on deploy rows.
  • removal.cancelRequestsboolean
    Also cancel the environment's other pending and scheduled requests for this decision.
  • removal.retireLinesboolean
    Retire the lines that were serving: they do not come back as compatibility lanes when a later deployment of another major goes live.
  • retireLinesboolean
    On a deploy: it was asked to retire the older major lines, so none was carried over and only this release (with its canary or shadow) serves once it is live.
  • retiresobject or null
    Set on a line retirement: the older major line it takes out of service. Waiting, it is a request to retire that line; live, it is what served before, less that line (versionId and variants are what serves).
  • retires.versionNumberinteger
  • retires.semanticVersionstring
  • releaseobject or null
    The release this row is a member of, if any.
  • release.numberinteger
  • release.deploymentIdstring
  • canApproveboolean
    Whether the caller may approve or reject this request.
  • canCancelboolean
    Whether the caller may cancel it before it goes live.
  • approvalobject or null
    On a request waiting for approval: why the caller can or cannot approve it, and who can.
  • approval.reasonstring
    One plain sentence: why the caller can or cannot approve.
  • approval.requiresSecondApproverboolean
    The environment needs a second person: the requester (and their agents and tokens) never approve.
  • approval.approversarray of integer
    Everyone who could approve it now, by user id.
  • approval.nobodyCanApproveboolean
    Nobody can approve it: an owner or admin turns the second person off, or names an approver.
  • outcomestring
    On the response to a deploy request only: what happened and why, and where to act next.
  • warningsarray of string
    On the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.
  • duplicateboolean
    On the response to a deploy request only: true when the same release was already waiting for approval here, so no second request was made and this is that request.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment":"production","versionNumber":1}'

GET /v1/organisations/{org}/decisions/{slug}/deployments/check

Check a deployment

What a deploy of this release here would do, without doing it: approval, a request already waiting, warnings.

Path

  • orgRequiredstring
  • slugRequiredstring

Query

  • environmentRequiredstring
  • versionNumberRequiredinteger

Answer (200)

  • environmentstring
  • semanticVersionstring
  • requiresApprovalboolean
    The caller's deploy here waits for a person to approve it (the environment's approval mode, and who is asking).
  • requiresSecondApproverboolean
    A deploy here waits for a second person: the caller cannot approve their own request.
  • warningsarray of string
    What looks unwise but is allowed; the same warnings the deploy would carry.
  • waitingobject or null
    A request for this release already waiting for approval here; deploying again returns it.
  • waiting.idstring
  • waiting.actionstring
    What the row asks for. "deploy" puts versionId into service; "remove" takes the decision out of the environment. A pending "remove" is a removal request ("Removal requested"); once carried out its status is "removed", versionId is the primary it took out of service and variants lists the compatibility lines it kept available (empty when they were retired). A line retirement is a "deploy" row with retires set.One of deploy, remove
  • waiting.environmentstring
  • waiting.versionIdstring
  • waiting.versionNumberinteger
  • waiting.semanticVersionstring
  • waiting.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }
  • waiting.notestring or null
  • waiting.statusstring
    One of pending, scheduled, active, superseded, removed, rejected, cancelled
  • waiting.kindstring
    One of manual, api, scheduled, release
  • waiting.deployedByinteger or null
    The person who asked, or null when a deploy token did.
  • waiting.tokenobject or null
    The deploy token that asked, if one did.
  • waiting.requestedViaobject or null
    The agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.
  • waiting.onBehalfOfinteger or null
    The person the request counts as coming from: deployedBy, or the maker of the deploy token.
  • waiting.scheduledForstring or null
    When it goes (or went) live, if it was scheduled.
  • waiting.deployedAtstring
  • waiting.endedAtstring or null
  • waiting.approvedByinteger or null
  • waiting.approvedAtstring or null
  • waiting.approvalNotestring or null
  • waiting.removalobject or null
    The options a removal was asked with; null on deploy rows.
  • waiting.retireLinesboolean
    On a deploy: it was asked to retire the older major lines, so none was carried over and only this release (with its canary or shadow) serves once it is live.
  • waiting.retiresobject or null
    Set on a line retirement: the older major line it takes out of service. Waiting, it is a request to retire that line; live, it is what served before, less that line (versionId and variants are what serves).
  • waiting.releaseobject or null
    The release this row is a member of, if any.
  • waiting.canApproveboolean
    Whether the caller may approve or reject this request.
  • waiting.canCancelboolean
    Whether the caller may cancel it before it goes live.
  • waiting.approvalobject or null
    On a request waiting for approval: why the caller can or cannot approve it, and who can.
  • waiting.outcomestring
    On the response to a deploy request only: what happened and why, and where to act next.
  • waiting.warningsarray of string
    On the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.
  • waiting.duplicateboolean
    On the response to a deploy request only: true when the same release was already waiting for approval here, so no second request was made and this is that request.
  • evidenceobject
    The release's latest completed Evaluation (its plan's, draft or release).
  • evidence.statestring
    One of none, passed, mixed, failing
  • evidence.agreedinteger
  • evidence.casesinteger
  • passingTestsRequiredboolean
    The environment requires a passing Test set (every case agreed in the latest Evaluation). A release without one is refused by the check itself, with the deploy's 409 PASSING_TESTS_REQUIRED.
Terminal
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments/check?environment=production&versionNumber=1" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/deployments/republish

Republish a Decision's runtime records

Rewrites the decision's runtime records from the database; idempotent. Owners and admins.

Path

  • orgRequiredstring
  • slugRequiredstring

Answer (200)

  • publishedarray of string
    Environments whose runtime record was rewritten.
  • clearedarray of string
    Environments with nothing live, whose runtime record was deleted.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments/republish" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/deployments/{deploymentId}/cancel

Cancel a deployment request

Withdraws a pending or scheduled deployment before it goes live.

Path

  • orgRequiredstring
  • slugRequiredstring
  • deploymentIdRequiredstring

Answer (200)

  • idstring
  • actionstring
    What the row asks for. "deploy" puts versionId into service; "remove" takes the decision out of the environment. A pending "remove" is a removal request ("Removal requested"); once carried out its status is "removed", versionId is the primary it took out of service and variants lists the compatibility lines it kept available (empty when they were retired). A line retirement is a "deploy" row with retires set.One of deploy, remove
  • environmentstring
  • versionIdstring
  • versionNumberinteger
  • semanticVersionstring
  • variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }
  • notestring or null
  • statusstring
    One of pending, scheduled, active, superseded, removed, rejected, cancelled
  • kindstring
    One of manual, api, scheduled, release
  • deployedByinteger or null
    The person who asked, or null when a deploy token did.
  • tokenobject or null
    The deploy token that asked, if one did.
  • token.idstring
  • token.namestring
  • requestedViaobject or null
    The agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.
  • requestedVia.kindstring
    "token": a personal access token (an agent or a script); "connection": an app connected in the browser.One of token, connection
  • requestedVia.namestring
    The token's or the app's name, such as "Claude Code".
  • onBehalfOfinteger or null
    The person the request counts as coming from: deployedBy, or the maker of the deploy token.
  • scheduledForstring or null
    When it goes (or went) live, if it was scheduled.
  • deployedAtstring
  • endedAtstring or null
  • approvedByinteger or null
  • approvedAtstring or null
  • approvalNotestring or null
  • removalobject or null
    The options a removal was asked with; null on deploy rows.
  • removal.cancelRequestsboolean
    Also cancel the environment's other pending and scheduled requests for this decision.
  • removal.retireLinesboolean
    Retire the lines that were serving: they do not come back as compatibility lanes when a later deployment of another major goes live.
  • retireLinesboolean
    On a deploy: it was asked to retire the older major lines, so none was carried over and only this release (with its canary or shadow) serves once it is live.
  • retiresobject or null
    Set on a line retirement: the older major line it takes out of service. Waiting, it is a request to retire that line; live, it is what served before, less that line (versionId and variants are what serves).
  • retires.versionNumberinteger
  • retires.semanticVersionstring
  • releaseobject or null
    The release this row is a member of, if any.
  • release.numberinteger
  • release.deploymentIdstring
  • canApproveboolean
    Whether the caller may approve or reject this request.
  • canCancelboolean
    Whether the caller may cancel it before it goes live.
  • approvalobject or null
    On a request waiting for approval: why the caller can or cannot approve it, and who can.
  • approval.reasonstring
    One plain sentence: why the caller can or cannot approve.
  • approval.requiresSecondApproverboolean
    The environment needs a second person: the requester (and their agents and tokens) never approve.
  • approval.approversarray of integer
    Everyone who could approve it now, by user id.
  • approval.nobodyCanApproveboolean
    Nobody can approve it: an owner or admin turns the second person off, or names an approver.
  • outcomestring
    On the response to a deploy request only: what happened and why, and where to act next.
  • warningsarray of string
    On the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.
  • duplicateboolean
    On the response to a deploy request only: true when the same release was already waiting for approval here, so no second request was made and this is that request.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments/<deploymentId>/cancel" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

DELETE /v1/organisations/{org}/decisions/{slug}/deployments/{environment}

Take a Decision out of an environment

Takes the decision out of an environment with the default options (cancel waiting requests, keep compatibility lines). 204 when done; 202 with the removal request where the environment requires approval and the caller cannot approve.

Path

  • orgRequiredstring
  • slugRequiredstring
  • environmentRequiredstring

Answer (200)

  • statusstring
    "removed" when it took effect (200); "pending" when it waits for approval (202).One of removed, pending
  • deploymentobject
    The removal row (action "remove").
  • deployment.idstring
  • deployment.actionstring
    What the row asks for. "deploy" puts versionId into service; "remove" takes the decision out of the environment. A pending "remove" is a removal request ("Removal requested"); once carried out its status is "removed", versionId is the primary it took out of service and variants lists the compatibility lines it kept available (empty when they were retired). A line retirement is a "deploy" row with retires set.One of deploy, remove
  • deployment.environmentstring
  • deployment.versionIdstring
  • deployment.versionNumberinteger
  • deployment.semanticVersionstring
  • deployment.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }
  • deployment.notestring or null
  • deployment.statusstring
    One of pending, scheduled, active, superseded, removed, rejected, cancelled
  • deployment.kindstring
    One of manual, api, scheduled, release
  • deployment.deployedByinteger or null
    The person who asked, or null when a deploy token did.
  • deployment.tokenobject or null
    The deploy token that asked, if one did.
  • deployment.requestedViaobject or null
    The agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.
  • deployment.onBehalfOfinteger or null
    The person the request counts as coming from: deployedBy, or the maker of the deploy token.
  • deployment.scheduledForstring or null
    When it goes (or went) live, if it was scheduled.
  • deployment.deployedAtstring
  • deployment.endedAtstring or null
  • deployment.approvedByinteger or null
  • deployment.approvedAtstring or null
  • deployment.approvalNotestring or null
  • deployment.removalobject or null
    The options a removal was asked with; null on deploy rows.
  • deployment.retireLinesboolean
    On a deploy: it was asked to retire the older major lines, so none was carried over and only this release (with its canary or shadow) serves once it is live.
  • deployment.retiresobject or null
    Set on a line retirement: the older major line it takes out of service. Waiting, it is a request to retire that line; live, it is what served before, less that line (versionId and variants are what serves).
  • deployment.releaseobject or null
    The release this row is a member of, if any.
  • deployment.canApproveboolean
    Whether the caller may approve or reject this request.
  • deployment.canCancelboolean
    Whether the caller may cancel it before it goes live.
  • deployment.approvalobject or null
    On a request waiting for approval: why the caller can or cannot approve it, and who can.
  • deployment.outcomestring
    On the response to a deploy request only: what happened and why, and where to act next.
  • deployment.warningsarray of string
    On the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.
  • deployment.duplicateboolean
    On the response to a deploy request only: true when the same release was already waiting for approval here, so no second request was made and this is that request.
  • cancelledarray
    The waiting requests the removal cancelled.
Terminal
curl -X DELETE "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments/production" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"

POST /v1/organisations/{org}/decisions/{slug}/deployments/{environment}/remove

Take a Decision out of an environment, with options

Takes the decision out of an environment with the options chosen. 200 when done; 202 when it waits for approval. 503 RUNTIME_SYNC_FAILED when saved but the runtime was not updated (republish to repair).

Path

  • orgRequiredstring
  • slugRequiredstring
  • environmentRequiredstring

Body

  • cancelRequestsOptionalboolean
    Default true.
  • retireLinesOptionalboolean
    Default false: older major lines stay available to callers that accept them.
  • noteOptionalstring or null

Answer (200)

  • statusstring
    "removed" when it took effect (200); "pending" when it waits for approval (202).One of removed, pending
  • deploymentobject
    The removal row (action "remove").
  • deployment.idstring
  • deployment.actionstring
    What the row asks for. "deploy" puts versionId into service; "remove" takes the decision out of the environment. A pending "remove" is a removal request ("Removal requested"); once carried out its status is "removed", versionId is the primary it took out of service and variants lists the compatibility lines it kept available (empty when they were retired). A line retirement is a "deploy" row with retires set.One of deploy, remove
  • deployment.environmentstring
  • deployment.versionIdstring
  • deployment.versionNumberinteger
  • deployment.semanticVersionstring
  • deployment.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }
  • deployment.notestring or null
  • deployment.statusstring
    One of pending, scheduled, active, superseded, removed, rejected, cancelled
  • deployment.kindstring
    One of manual, api, scheduled, release
  • deployment.deployedByinteger or null
    The person who asked, or null when a deploy token did.
  • deployment.tokenobject or null
    The deploy token that asked, if one did.
  • deployment.requestedViaobject or null
    The agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.
  • deployment.onBehalfOfinteger or null
    The person the request counts as coming from: deployedBy, or the maker of the deploy token.
  • deployment.scheduledForstring or null
    When it goes (or went) live, if it was scheduled.
  • deployment.deployedAtstring
  • deployment.endedAtstring or null
  • deployment.approvedByinteger or null
  • deployment.approvedAtstring or null
  • deployment.approvalNotestring or null
  • deployment.removalobject or null
    The options a removal was asked with; null on deploy rows.
  • deployment.retireLinesboolean
    On a deploy: it was asked to retire the older major lines, so none was carried over and only this release (with its canary or shadow) serves once it is live.
  • deployment.retiresobject or null
    Set on a line retirement: the older major line it takes out of service. Waiting, it is a request to retire that line; live, it is what served before, less that line (versionId and variants are what serves).
  • deployment.releaseobject or null
    The release this row is a member of, if any.
  • deployment.canApproveboolean
    Whether the caller may approve or reject this request.
  • deployment.canCancelboolean
    Whether the caller may cancel it before it goes live.
  • deployment.approvalobject or null
    On a request waiting for approval: why the caller can or cannot approve it, and who can.
  • deployment.outcomestring
    On the response to a deploy request only: what happened and why, and where to act next.
  • deployment.warningsarray of string
    On the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.
  • deployment.duplicateboolean
    On the response to a deploy request only: true when the same release was already waiting for approval here, so no second request was made and this is that request.
  • cancelledarray
    The waiting requests the removal cancelled.
Terminal
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/deployments/production/remove" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'