Deployments

Deployments represent the process of building and deploying your projects to servers. Each deployment contains information about the build status, logs, and timing. On this page, we will dive into the different deployment endpoints you can use to manage deployments programmatically.

AUTH Authorization: Bearer {API_KEY} Create a token →
POST/api/v1/deployments

Create deployment #

This endpoint allows you to trigger deployments for multiple projects at once. This is useful for deploying related projects simultaneously. You can also trigger a deployment for a single project.

Attributes for creating a deployment #

project_ids array
An array of project IDs to deploy. Example: [1, 2, 3].
POST /api/v1/deployments Request
Multiple projects
curl https://app.depfloy.com/api/v1/deployments \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": [1, 2, 3]
  }'
Single project
curl https://app.depfloy.com/api/v1/deployments \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": [1]
  }'
Response
{
    "message": "Deployment queued successfully.",
    "status": "success"
}
GET/api/v1/projects/:id/deployments

List project deployments #

This endpoint allows you to retrieve a paginated list of all deployments for a specific project.

Optional attributes #

per_page integer

Limit the number of deployments returned per page. Default is 15.

page integer

The page number to retrieve.

GET /api/v1/projects/1/deployments Request
cURL
curl -G https://app.depfloy.com/api/v1/projects/1/deployments \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
With pagination
curl -G https://app.depfloy.com/api/v1/projects/1/deployments \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json" \
  -d per_page=5 \
  -d page=1
Response
{
    "current_page": 1,
    "data": [
        {
            "id": 5,
            "tenant_id": 1,
            "project_id": 1,
            "initiated_by": 1,
            "git_branch": "master",
            "commit_id": null,
            "commit_url": null,
            "description": "Deployment started from API",
            "status": 0,
            "duration": 0,
            "created_at": "2026-01-17T13:55:31.000000Z",
            "updated_at": "2026-01-17T13:55:31.000000Z"
        },
        {
            "id": 1,
            "tenant_id": 1,
            "project_id": 1,
            "initiated_by": 1,
            "git_branch": "master",
            "commit_id": null,
            "commit_url": null,
            "description": "Deployment started by Maggy",
            "status": 1,
            "duration": 100,
            "created_at": "2025-05-26T06:59:26.000000Z",
            "updated_at": "2025-05-26T10:29:20.000000Z"
        }
    ],
    "per_page": 10,
    "total_items": 2,
    "total_pages": 1
}
GET/api/v1/deployments/:id

Retrieve a deployment #

This endpoint allows you to retrieve a specific deployment by its ID. This includes the full build log.

GET /api/v1/deployments/:id Request
cURL
curl https://app.depfloy.com/api/v1/deployments/5334 \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
{
    "id": 1,
    "project_id": 1,
    "initiated_by": 1,
    "git_branch": "master",
    "commit_id": null,
    "commit_url": null,
    "description": "Deployment started by Maggy",
    "status": 1,
    "duration": 100,
    "created_at": "2025-05-26T06:59:26.000000Z",
    "updated_at": "2025-05-26T10:29:20.000000Z",
    "output": {
        "process_type": "build",
        "client_payload": [
            // ... client payload
            "✓ 1 asset moved from React Router server build to client assets.",
            "✓ built in 23.73s\n",
            "07:01:09 - ✓ Deployment completed."
        ],
        "system_payload": [
          // ... system payload
        ]
    }
}
POST/api/v1/deployments/:id/rerun

Rerun a deployment #

Queue a new deployment that targets the same commit as a previous one. Useful when a deployment failed because of a transient cause (a flaky test, a registry timeout, a one-off environment glitch) and you want to retry the exact same code.

Only failed deployments can be rerun. The new deployment is a separate record — your history grows by one entry rather than overwriting the failed deployment.

POST /api/v1/deployments/5334/rerun Request
cURL
curl -X POST https://app.depfloy.com/api/v1/deployments/5334/rerun \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "message": "Rerun queued.",
  "deployment_id": 5340
}
POST/api/v1/deployments/:id/cancel

Cancel a deployment #

Stop a deployment that has not gone live yet. A queued deployment stops at once; one that is building stops at its next checkpoint and the half-finished release is thrown away. The release currently serving is untouched.

Answers 202 with a state of either cancelled — it stopped before anything claimed it — or cancelling, meaning the running job will stop at its next checkpoint. Poll Retrieve a deployment for the final status. Cancelling one that is already being cancelled answers 409.

A deployment that has already switched over cannot be cancelled; use Rollback to return to the previous release. A project that still deploys in place rather than using zero-downtime releases can only cancel a queued deployment.

POST /api/v1/deployments/5334/cancel Request
cURL
curl -X POST https://app.depfloy.com/api/v1/deployments/5334/cancel \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "message": "Cancelling the deployment. The running version keeps serving until it stops.",
  "deployment_id": 5334,
  "state": "cancelling"
}
POST/api/v1/projects/:id/recycle

Recycle a project’s process #

Replace a Node project’s running process with a fresh one from the release already live. Nothing is fetched or built, so the commit the site serves does not change. Depfloy runs the same switch a deployment does — new process on the standby port, health check, soak, nginx upstream switch, then the old process is drained — so the site answers throughout.

Queues the work and returns a deployment_id; follow it with Retrieve a deployment.

Refused for projects served by PHP-FPM, for projects not on zero-downtime releases, for a project not yet installed on its server, and while another deployment is running or queued.

POST /api/v1/projects/42/recycle Request
cURL
curl -X POST https://app.depfloy.com/api/v1/projects/42/recycle \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "deployment_id": 5341,
  "project_id": 42
}
GET/api/v1/projects/:id/rollback-candidates

List rollback candidates #

Return the previous successful deployments you can roll back to. Each entry has a commit ID and is not the currently active deployment.

GET /api/v1/projects/14532/rollback-candidates Request
cURL
curl https://app.depfloy.com/api/v1/projects/14532/rollback-candidates \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
[
  {
    "id": 5212,
    "commit_id": "abc1234",
    "git_branch": "main",
    "description": "Deployment started by Maggy",
    "created_at": "2026-05-08T08:14:00.000000Z"
  }
]
POST/api/v1/deployments/:id/rollback

Rollback to a deployment #

Roll back to a previous successful deployment. Depfloy queues a new deployment that targets the same commit as the chosen deployment — your history is preserved; the rollback appears as a new deployment.

The target deployment must be in Success status, have a recorded commit ID, and not be the currently active deployment. Use List rollback candidates to find eligible deployments.

POST /api/v1/deployments/5212/rollback Request
cURL
curl -X POST https://app.depfloy.com/api/v1/deployments/5212/rollback \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"
Response
{
  "status": "success",
  "message": "Rollback queued.",
  "deployment_id": 5341
}