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)
environmentsarrayrequirePassingTestsbooleanThe organisation's "Require a passing Test set" rule.
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)
deploymentsarrayenvironmentsarrayrequirePassingTestsbooleanThe organisation's "Require a passing Test set" rule.productionRoutestringHow 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 ofproxy,passthrough,relay
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
orgRequiredstringslugRequiredstring
Answer (200)
currentarrayThe active deployment per environment, if any.pendingarrayRequests waiting for approval or a scheduled time: deploys, removals (action "remove") and line retirements (retires).historyarrayEvery deployment, newest first.environmentsarraycallsarray 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.
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
orgRequiredstringslugRequiredstring
Body
environmentRequiredstringversionNumberRequiredintegervariantsOptionalarray of { "versionNumber": integer, "role": string, "weight": number }Canaries and shadows to run beside the primary; variant weights must sum to under 1.noteOptionalstring or nullscheduledForOptionalstring or nullISO time at least a minute ahead; the deployment waits until then.retireLinesOptionalbooleanDefault 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)
idstringactionstringWhat 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 withretiresset.One ofdeploy,removeenvironmentstringversionIdstringversionNumberintegersemanticVersionstringvariantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }notestring or nullstatusstringOne ofpending,scheduled,active,superseded,removed,rejected,cancelledkindstringOne ofmanual,api,scheduled,releasedeployedByinteger or nullThe person who asked, or null when a deploy token did.tokenobject or nullThe deploy token that asked, if one did.token.idstringtoken.namestringrequestedViaobject or nullThe 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 oftoken,connectionrequestedVia.namestringThe token's or the app's name, such as "Claude Code".onBehalfOfinteger or nullThe person the request counts as coming from: deployedBy, or the maker of the deploy token.scheduledForstring or nullWhen it goes (or went) live, if it was scheduled.deployedAtstringendedAtstring or nullapprovedByinteger or nullapprovedAtstring or nullapprovalNotestring or nullremovalobject or nullThe options a removal was asked with; null on deploy rows.removal.cancelRequestsbooleanAlso cancel the environment's other pending and scheduled requests for this decision.removal.retireLinesbooleanRetire the lines that were serving: they do not come back as compatibility lanes when a later deployment of another major goes live.retireLinesbooleanOn 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 nullSet 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.versionNumberintegerretires.semanticVersionstringreleaseobject or nullThe release this row is a member of, if any.release.numberintegerrelease.deploymentIdstringcanApprovebooleanWhether the caller may approve or reject this request.canCancelbooleanWhether the caller may cancel it before it goes live.approvalobject or nullOn a request waiting for approval: why the caller can or cannot approve it, and who can.approval.reasonstringOne plain sentence: why the caller can or cannot approve.approval.requiresSecondApproverbooleanThe environment needs a second person: the requester (and their agents and tokens) never approve.approval.approversarray of integerEveryone who could approve it now, by user id.approval.nobodyCanApprovebooleanNobody can approve it: an owner or admin turns the second person off, or names an approver.outcomestringOn the response to a deploy request only: what happened and why, and where to act next.warningsarray of stringOn the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.duplicatebooleanOn 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.
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
orgRequiredstringslugRequiredstring
Query
environmentRequiredstringversionNumberRequiredinteger
Answer (200)
environmentstringsemanticVersionstringrequiresApprovalbooleanThe caller's deploy here waits for a person to approve it (the environment's approval mode, and who is asking).requiresSecondApproverbooleanA deploy here waits for a second person: the caller cannot approve their own request.warningsarray of stringWhat looks unwise but is allowed; the same warnings the deploy would carry.waitingobject or nullA request for this release already waiting for approval here; deploying again returns it.waiting.idstringwaiting.actionstringWhat 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 withretiresset.One ofdeploy,removewaiting.environmentstringwaiting.versionIdstringwaiting.versionNumberintegerwaiting.semanticVersionstringwaiting.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }waiting.notestring or nullwaiting.statusstringOne ofpending,scheduled,active,superseded,removed,rejected,cancelledwaiting.kindstringOne ofmanual,api,scheduled,releasewaiting.deployedByinteger or nullThe person who asked, or null when a deploy token did.waiting.tokenobject or nullThe deploy token that asked, if one did.waiting.requestedViaobject or nullThe agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.waiting.onBehalfOfinteger or nullThe person the request counts as coming from: deployedBy, or the maker of the deploy token.waiting.scheduledForstring or nullWhen it goes (or went) live, if it was scheduled.waiting.deployedAtstringwaiting.endedAtstring or nullwaiting.approvedByinteger or nullwaiting.approvedAtstring or nullwaiting.approvalNotestring or nullwaiting.removalobject or nullThe options a removal was asked with; null on deploy rows.waiting.retireLinesbooleanOn 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 nullSet 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 nullThe release this row is a member of, if any.waiting.canApprovebooleanWhether the caller may approve or reject this request.waiting.canCancelbooleanWhether the caller may cancel it before it goes live.waiting.approvalobject or nullOn a request waiting for approval: why the caller can or cannot approve it, and who can.waiting.outcomestringOn the response to a deploy request only: what happened and why, and where to act next.waiting.warningsarray of stringOn the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.waiting.duplicatebooleanOn 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.evidenceobjectThe release's latest completed Evaluation (its plan's, draft or release).evidence.statestringOne ofnone,passed,mixed,failingevidence.agreedintegerevidence.casesintegerpassingTestsRequiredbooleanThe 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.
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
orgRequiredstringslugRequiredstring
Answer (200)
publishedarray of stringEnvironments whose runtime record was rewritten.clearedarray of stringEnvironments with nothing live, whose runtime record was deleted.
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
orgRequiredstringslugRequiredstringdeploymentIdRequiredstring
Answer (200)
idstringactionstringWhat 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 withretiresset.One ofdeploy,removeenvironmentstringversionIdstringversionNumberintegersemanticVersionstringvariantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }notestring or nullstatusstringOne ofpending,scheduled,active,superseded,removed,rejected,cancelledkindstringOne ofmanual,api,scheduled,releasedeployedByinteger or nullThe person who asked, or null when a deploy token did.tokenobject or nullThe deploy token that asked, if one did.token.idstringtoken.namestringrequestedViaobject or nullThe 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 oftoken,connectionrequestedVia.namestringThe token's or the app's name, such as "Claude Code".onBehalfOfinteger or nullThe person the request counts as coming from: deployedBy, or the maker of the deploy token.scheduledForstring or nullWhen it goes (or went) live, if it was scheduled.deployedAtstringendedAtstring or nullapprovedByinteger or nullapprovedAtstring or nullapprovalNotestring or nullremovalobject or nullThe options a removal was asked with; null on deploy rows.removal.cancelRequestsbooleanAlso cancel the environment's other pending and scheduled requests for this decision.removal.retireLinesbooleanRetire the lines that were serving: they do not come back as compatibility lanes when a later deployment of another major goes live.retireLinesbooleanOn 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 nullSet 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.versionNumberintegerretires.semanticVersionstringreleaseobject or nullThe release this row is a member of, if any.release.numberintegerrelease.deploymentIdstringcanApprovebooleanWhether the caller may approve or reject this request.canCancelbooleanWhether the caller may cancel it before it goes live.approvalobject or nullOn a request waiting for approval: why the caller can or cannot approve it, and who can.approval.reasonstringOne plain sentence: why the caller can or cannot approve.approval.requiresSecondApproverbooleanThe environment needs a second person: the requester (and their agents and tokens) never approve.approval.approversarray of integerEveryone who could approve it now, by user id.approval.nobodyCanApprovebooleanNobody can approve it: an owner or admin turns the second person off, or names an approver.outcomestringOn the response to a deploy request only: what happened and why, and where to act next.warningsarray of stringOn the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.duplicatebooleanOn 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.
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
orgRequiredstringslugRequiredstringenvironmentRequiredstring
Answer (200)
statusstring"removed" when it took effect (200); "pending" when it waits for approval (202).One ofremoved,pendingdeploymentobjectThe removal row (action "remove").deployment.idstringdeployment.actionstringWhat 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 withretiresset.One ofdeploy,removedeployment.environmentstringdeployment.versionIdstringdeployment.versionNumberintegerdeployment.semanticVersionstringdeployment.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }deployment.notestring or nulldeployment.statusstringOne ofpending,scheduled,active,superseded,removed,rejected,cancelleddeployment.kindstringOne ofmanual,api,scheduled,releasedeployment.deployedByinteger or nullThe person who asked, or null when a deploy token did.deployment.tokenobject or nullThe deploy token that asked, if one did.deployment.requestedViaobject or nullThe agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.deployment.onBehalfOfinteger or nullThe person the request counts as coming from: deployedBy, or the maker of the deploy token.deployment.scheduledForstring or nullWhen it goes (or went) live, if it was scheduled.deployment.deployedAtstringdeployment.endedAtstring or nulldeployment.approvedByinteger or nulldeployment.approvedAtstring or nulldeployment.approvalNotestring or nulldeployment.removalobject or nullThe options a removal was asked with; null on deploy rows.deployment.retireLinesbooleanOn 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 nullSet 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 nullThe release this row is a member of, if any.deployment.canApprovebooleanWhether the caller may approve or reject this request.deployment.canCancelbooleanWhether the caller may cancel it before it goes live.deployment.approvalobject or nullOn a request waiting for approval: why the caller can or cannot approve it, and who can.deployment.outcomestringOn the response to a deploy request only: what happened and why, and where to act next.deployment.warningsarray of stringOn the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.deployment.duplicatebooleanOn 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.cancelledarrayThe waiting requests the removal cancelled.
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
orgRequiredstringslugRequiredstringenvironmentRequiredstring
Body
cancelRequestsOptionalbooleanDefault true.retireLinesOptionalbooleanDefault 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 ofremoved,pendingdeploymentobjectThe removal row (action "remove").deployment.idstringdeployment.actionstringWhat 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 withretiresset.One ofdeploy,removedeployment.environmentstringdeployment.versionIdstringdeployment.versionNumberintegerdeployment.semanticVersionstringdeployment.variantsarray of { "versionNumber": integer, "semanticVersion": string, "role": string, "weight": number }deployment.notestring or nulldeployment.statusstringOne ofpending,scheduled,active,superseded,removed,rejected,cancelleddeployment.kindstringOne ofmanual,api,scheduled,releasedeployment.deployedByinteger or nullThe person who asked, or null when a deploy token did.deployment.tokenobject or nullThe deploy token that asked, if one did.deployment.requestedViaobject or nullThe agent or app the person asked through ("Claude Code, acting for Dana"); null in the app.deployment.onBehalfOfinteger or nullThe person the request counts as coming from: deployedBy, or the maker of the deploy token.deployment.scheduledForstring or nullWhen it goes (or went) live, if it was scheduled.deployment.deployedAtstringdeployment.endedAtstring or nulldeployment.approvedByinteger or nulldeployment.approvedAtstring or nulldeployment.approvalNotestring or nulldeployment.removalobject or nullThe options a removal was asked with; null on deploy rows.deployment.retireLinesbooleanOn 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 nullSet 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 nullThe release this row is a member of, if any.deployment.canApprovebooleanWhether the caller may approve or reject this request.deployment.canCancelbooleanWhether the caller may cancel it before it goes live.deployment.approvalobject or nullOn a request waiting for approval: why the caller can or cannot approve it, and who can.deployment.outcomestringOn the response to a deploy request only: what happened and why, and where to act next.deployment.warningsarray of stringOn the response to a deploy request only: what looks unwise but is allowed, such as a release going to production without an Evaluation.deployment.duplicatebooleanOn 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.cancelledarrayThe waiting requests the removal cancelled.
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 '{}'