Abort an in-flight rollout

POST

/api/v1/deployments/{id}/rollback

curl --request POST \
  --url http://localhost:3000/api/v1/deployments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/rollback \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "reason": "Canary devices reported repeated container crashes" }'

• Development
• Production

Aborts the in-flight rollout and marks it rolled back. This does not redeploy a previous application version. The effect depends on the deployment history. A rollout of the first revision withdraws the deployment from every device it was released to, and the devices uninstall it. A rollout that follows a re-deploy (POST /deployments/{id}/redeploy) does not withdraw anything: devices that already run the new revision move back to the revision they ran before, and devices that still wait for their batch keep running it. The deployment stays in every device manifest. A device that ran nothing before the re-deploy is withdrawn as for a first revision. A rolled-back deployment can be re-deployed again.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

id

required

string format: uuid

Deployment UUID

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Body^required

Media typeapplication/json

object

reason

Operator-supplied reason for the rollback, recorded in the audit trail

string

<= 500 characters

Example

Canary devices reported repeated container crashes

Responses

200

Rollback triggered successfully

Media typeapplication/json

object

phase

required

string

Allowed values: PENDING CANARY_DEPLOYING CANARY_VALIDATING CANARY_PROMOTED ROLLING_IN_PROGRESS PAUSED COMPLETED ROLLED_BACK

strategy

required

string

Allowed values: IMMEDIATE CANARY ROLLING

totalInstances

required

number

pendingInstances

required

number

deployingInstances

required

number

runningInstances

required

number

failedInstances

required

number

currentBatch

required

number

totalBatches

required

number

canaryInstances

required

number

productionInstances

required

number

failureRate

required

Share of failed instances

number

isRollbackTriggered

required

boolean

canarySuccessWindowMinutes

Canary success window in minutes. Only for a CANARY rollout in CANARY_DEPLOYING or CANARY_VALIDATING.

number

canarySuccessWindowRemainingMinutes

Minutes left in the canary success window; 0 once it has elapsed. Absent while the rollout has not started.

number

Example

{
  "phase": "PENDING",
  "strategy": "IMMEDIATE"
}

403

Forbidden — caller lacks required permission

404

Deployment not found