---
title: "Rollback deployment"
method: POST
path: "/v2/deployments.rollbackDeployment"
tags: ["deployments"]
---

# Rollback deployment

`POST /v2/deployments.rollbackDeployment`

Roll live traffic back to a previous deployment. `deploymentId` is the
deployment to roll back TO; the app's current deployment is used as
the rollback source automatically.

The target deployment must be ready, not already shutting down, belong to
the production environment, and must not itself be the current deployment.

After a rollback the app is marked as rolled back, which prevents new
deployments from automatically taking over live traffic. Promote the
rolled-back deployment (or a newer one) to clear this state.

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

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.rollback_deployment` (to roll back deployments in any environment)
- `environment.<environment_id>.rollback_deployment` (to roll back deployments in a specific environment)

## Request body

- V2DeploymentsRollbackDeploymentRequestBody — Roll live traffic back to a previous deployment.
  - `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`

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

- V2DeploymentsRollbackDeploymentResponseBody
  - `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 `rollback_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, does not belong to the production environment, or the app has no current deployment to roll back from.
- `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)