Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
deployments

Promote deployment

Promote a deployment to become the current deployment for its environment. All sticky domains are reassigned from the current deployment to the promoted one, and the previous deployment is scheduled for standby.

The deployment must be ready, not already shutting down, belong to the production environment, and its app must already have a current deployment. Promoting the deployment that is already current fails, unless the app is in a rolled-back state, in which case promoting the current deployment confirms the rollback and re-enables automatic promotion of future deployments.

Promotion runs as a durable workflow: this endpoint returns once the promotion is accepted. Poll getDeployment or listDeployments to observe the result.

Required Permissions

Your root key must have one of the following permissions:

  • environment.*.promote_deployment (to promote deployments in any environment)
  • environment.<environment_id>.promote_deployment (to promote deployments in a specific environment)
post/v2/deployments.promoteDeployment

Request body

deploymentIdstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Example request

{
  "deploymentId": "proj_1234abcd"
}

Response

Promotion accepted. Poll getDeployment to observe the result.

dataEmptyResponse required

Empty response object by design. A successful response indicates this operation was successfully executed.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}