This method will create a rollback deployment for a previously completed deployment.

## URL

```text
/projects/<project>/deployments/<deployment>/rollback
```

Replace `<project>` with either the `permalink` or `identifier` of the project, and `<deployment>` with the `identifier` of the deployment you want to rollback.

## HTTP Method

```text
POST
```

## Rollback Behavior

When you rollback a deployment, DeployHQ creates a new deployment that reverses the changes from the target deployment:

* Files added in the deployment will be removed
* Files deleted in the deployment will be restored
* Files modified in the deployment will be reverted to their previous versions

The rollback deployment uses:
* **Start revision**: The end revision of the latest deployment on the server
* **End revision**: The end revision of the deployment being rolled back to (this reverts all changes made after this deployment)

## Supported Parameters

* `mode` - The deployment mode, can be `queue` or `preview` (default: `queue`)
* `copy_config_files` - If config files should be copied during the rollback, either `true` or `false` (default: `true`)
* `run_build_commands` - If you want to run build commands during the rollback, either `true` or `false` (default: `true`)

## Requirements

A deployment can only be rolled back if:

* It is not a config-files-only deployment
* It has a parent server or server group
* It is not the latest deployment for that server

## Example cURL request (Queue mode)

```bash
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{"mode": "queue", "copy_config_files": true, "run_build_commands": true}' \
https://test.deployhq.com/projects/my-project/deployments/6bd5cdc4-d652-92e8-322f-287929091f03/rollback
```

## Example cURL request (Preview mode)

```bash
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{"mode": "preview"}' \
https://test.deployhq.com/projects/my-project/deployments/6bd5cdc4-d652-92e8-322f-287929091f03/rollback
```

## Example Response (Queue mode)

The response will contain the newly created rollback deployment:

```json
{
  "identifier": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "status": "pending",
  "start_revision": "def456abc789",
  "end_revision": "abc123def456",
  "branch": "main",
  "configuration": {
    "copy_config_files": true,
    "run_build_commands": true
  },
  "timestamps": {
    "queued_at": "2025-10-27T10:00:00Z"
  },
  "servers": [
    {
      "name": "Production Server",
      "identifier": "7563d091-ca73-588e-cfe2-e4936f190145",
      "protocol_type": "ssh"
    }
  ],
  "project": {
    "name": "My Project",
    "permalink": "my-project"
  }
}
```

## Example Response (Preview mode)

```json
{
  "identifier": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "status": "preview_pending"
}
```

When creating a preview rollback, you can poll the `/projects/<project>/deployments/<uuid>/preview` endpoint to see its progress and a list of potential file changes once the preview has been fully generated.

## Error Responses

If the deployment cannot be rolled back, you'll receive a 422 status code with an error message:

```json
{
  "error": "Cannot rollback the latest deployment"
}
```

Common error messages:

* "Cannot rollback a config files deployment"
* "Deployment has no parent server"
* "Cannot rollback the latest deployment"
* "Deployment cannot be rolled back"