---
title: "Promote deployment"
method: POST
path: "/v2/deployments.promoteDeployment"
tags: ["deployments"]
---

# Promote deployment

`POST /v2/deployments.promoteDeployment`

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)

## Request body

- V2DeploymentsPromoteDeploymentRequestBody — Promote a ready deployment to become the current deployment for its environment.
  - `deploymentId` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `202`

Promotion accepted. Poll `getDeployment` to observe the result.

- V2DeploymentsPromoteDeploymentResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required — Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not Found - The deployment does not exist in your workspace, or your root key lacks the `promote_deployment` permission for it. Both cases return the same response, so deployment existence is never revealed.
- `412` — Precondition failed - The deployment is not ready, is shutting down, is already the current deployment (and the app is not in a rolled-back state), does not belong to the production environment, or its app has no current deployment to promote over.
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)