Retry a deployment via API

This method retries a deployment by resetting it and re-queuing it. This is useful for retrying deployments that have failed or been aborted.

URL

/projects/<project>/deployments/<deployment>/retry

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

HTTP Method

POST

Retry Behavior

When you retry a deployment, DeployHQ resets the original deployment and queues it again:

• The deployment steps are rebuilt
• The deployment servers are re-assigned
• The deployment status is set back to pending
• Start and finish timestamps are cleared

Unlike rollback, retry does not create a new deployment. The original deployment is re-used.

Requirements

A deployment can only be retried if:

• It has a failed status
• It is not archived

Example cURL request

curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
https://test.deployhq.com/projects/my-project/deployments/6bd5cdc4-d652-92e8-322f-287929091f03/retry

Example Response

The response contains the retried deployment with its steps, in the same format as viewing a deployment:

{
  "identifier": "6bd5cdc4-d652-92e8-322f-287929091f03",
  "status": "pending",
  "branch": "main",
  "start_revision": {
    "ref": "abc123def456"
  },
  "end_revision": {
    "ref": "def456abc789"
  },
  "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"
  },
  "steps": []
}

Error Responses

If the deployment cannot be retried, you will receive a 422 status code with an error message:

{
  "error": "This deployment cannot be retried"
}

Common error messages:

• "Archived deployments cannot be retried"
• "This deployment cannot be retried because it is currently in progress"
• "This deployment cannot be retried"