Rollback deployment via API

Last updated on 12th November 2025

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

URL

/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

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)

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)

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:

{
  "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)

{
  "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:

{
  "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"