Skip to main content

​
Overview

The Deployments API provides endpoints to list, monitor, and manage deployments across your applications, compose services, and servers. Each deployment represents a build and deploy operation with logs, status, and metadata.

​
Endpoints

​
List Application Deployments

Retrieve all deployments for a specific application. 
curl -X GET "https://your-dokploy-instance.com/api/deployment.all?applicationId=app_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
applicationId
string
required
The unique identifier of the application to retrieve deployments for.

​
Response

Returns an array of deployment objects ordered by creation date (most recent first).
​
deploymentId
string
Unique identifier for the deployment.
​
title
string
Deployment title or description.
​
description
string
Additional deployment description.
​
status
string
Current deployment status. One of: pending, running, done, error.
​
applicationId
string
Associated application ID.
​
logPath
string
Path to deployment logs.
​
pid
number
Process ID of the running deployment (if applicable).
​
createdAt
string
ISO 8601 timestamp of deployment creation.
​
rollback
object
Rollback deployment information (if this deployment was rolled back).

​
List Compose Deployments

Retrieve all deployments for a Docker Compose service. 
curl -X GET "https://your-dokploy-instance.com/api/deployment.allByCompose?composeId=compose_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
composeId
string
required
The unique identifier of the compose service to retrieve deployments for.

​
Response

Returns an array of deployment objects for the compose service.

​
List Server Deployments

Retrieve all deployments for a specific server. 
curl -X GET "https://your-dokploy-instance.com/api/deployment.allByServer?serverId=server_def456" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
serverId
string
required
The unique identifier of the server to retrieve deployments for.

​
Response

Returns an array of all deployment operations on the specified server.

​
List Deployments by Type

Retrieve deployments filtered by service type and ID. 
curl -X GET "https://your-dokploy-instance.com/api/deployment.allByType?id=app_abc123&type=application" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Query Parameters

​
id
string
required
The unique identifier of the service.
​
type
string
required
The type of service. One of:
  • application - Standard application deployment
  • compose - Docker Compose service
  • server - Server deployment
  • schedule - Scheduled deployment
  • previewDeployment - Preview deployment
  • backup - Backup operation
  • volumeBackup - Volume backup operation

​
Response

Returns an array of deployments matching the specified type and ID, including rollback information.
​
deployments
array
Array of deployment objects.

​
Kill Deployment Process

Terminate a running deployment by killing its process. 
curl -X POST https://your-dokploy-instance.com/api/deployment.killProcess \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "deploy_ghi789"
  }'

​
Request Body

​
deploymentId
string
required
The ID of the deployment process to terminate.

​
Response

The deployment status will be updated to error and the process will be killed using kill -9.
Killing a deployment process may leave your application in an inconsistent state. Use this endpoint only when a deployment is stuck or unresponsive.
If the deployment is running on a remote server, the kill command will be executed remotely via SSH.

​
Remove Deployment

Permanently delete a deployment record. 
curl -X POST https://your-dokploy-instance.com/api/deployment.removeDeployment \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "deploy_ghi789"
  }'

​
Request Body

​
deploymentId
string
required
The ID of the deployment to remove.
Removing a deployment only deletes the deployment record and logs. It does not affect the running application or service.

​
Deployment States

Deployments transition through the following states:
  1. pending - Deployment is queued and waiting to start
  2. running - Deployment is currently in progress
  3. done - Deployment completed successfully
  4. error - Deployment failed or was terminated

​
Monitoring Deployments

You can monitor deployment progress by:
  1. Polling the deployment endpoints to check status changes
  2. Reading deployment logs from the logPath field
  3. Monitoring the pid field for running deployments
  4. Checking the createdAt timestamp to track deployment duration