Manage Applications

Start Application

Start a stopped application.

Endpoint

POST /application.start

Request Body

applicationId

string

required

ID of the application to start

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.start \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Example Response

{
  "applicationId": "app_def456",
  "name": "My Web App",
  "appName": "my-web-app",
  "applicationStatus": "done"
}

Stop Application

Stop a running application.

Endpoint

POST /application.stop

Request Body

applicationId

string

required

ID of the application to stop

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.stop \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Example Response

{
  "applicationId": "app_def456",
  "name": "My Web App",
  "appName": "my-web-app",
  "applicationStatus": "idle"
}

Reload Application

Reload the application container configuration without rebuilding.

Endpoint

POST /application.reload

Request Body

applicationId

string

required

ID of the application to reload

appName

string

required

Internal application name

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.reload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "appName": "my-web-app"
  }'

Example Response

{
  "success": true
}

Delete Application

Permanently delete an application and all its resources.

Endpoint

POST /application.delete

Request Body

applicationId

string

required

ID of the application to delete

This action is irreversible. All application data, deployments, and configurations will be permanently deleted.

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.delete \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Example Response

{
  "applicationId": "app_def456",
  "name": "My Web App",
  "appName": "my-web-app"
}

Mark Application as Running

Manually mark an application’s status as running.

Endpoint

POST /application.markRunning

Request Body

applicationId

string

required

ID of the application

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.markRunning \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Move Application

Move an application to a different environment.

Endpoint

POST /application.move

Request Body

applicationId

string

required

ID of the application to move

targetEnvironmentId

string

required

ID of the destination environment

Response

Returns the updated application object with the new environment ID.

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.move \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "targetEnvironmentId": "env_xyz789"
  }'

Example Response

{
  "applicationId": "app_def456",
  "name": "My Web App",
  "environmentId": "env_xyz789",
  "createdAt": "2024-03-06T10:30:00.000Z"
}

Refresh Token

Generate a new refresh token for the application.

Endpoint

POST /application.refreshToken

Request Body

applicationId

string

required

ID of the application

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.refreshToken \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Example Response

{
  "success": true
}

Traefik Configuration

Read Traefik Config

Retrieve the Traefik configuration for an application.

Endpoint

GET /application.readTraefikConfig

Query Parameters

applicationId

string

required

ID of the application

Example Request

curl -X GET "https://your-dokploy-instance.com/api/application.readTraefikConfig?applicationId=app_def456" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

http:
  routers:
    my-web-app:
      rule: "Host(`app.example.com`)"
      service: my-web-app
      entryPoints:
        - web
        - websecure
      tls:
        certResolver: letsencrypt
  services:
    my-web-app:
      loadBalancer:
        servers:
          - url: "http://my-web-app:3000"

Update Traefik Config

Update the Traefik configuration for an application.

Endpoint

POST /application.updateTraefikConfig

Request Body

applicationId

string

required

ID of the application

traefikConfig

string

required

New Traefik configuration in YAML format

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.updateTraefikConfig \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456",
    "traefikConfig": "http:\n  routers:\n    my-web-app:\n      rule: \"Host(`app.example.com`)\"\n      service: my-web-app"
  }'

Example Response

{
  "success": true
}

Monitoring

Read Application Monitoring

Retrieve monitoring statistics and metrics for an application.

Endpoint

GET /application.readAppMonitoring

Query Parameters

appName

string

required

Internal name of the application

This endpoint is only available in self-hosted deployments, not in the cloud version.

Example Request

curl -X GET "https://your-dokploy-instance.com/api/application.readAppMonitoring?appName=my-web-app" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "cpu": {
    "usage": 45.2,
    "limit": 100
  },
  "memory": {
    "usage": 512000000,
    "limit": 1073741824,
    "percentage": 47.7
  },
  "network": {
    "rx": 1024000,
    "tx": 2048000
  },
  "containers": [
    {
      "id": "abc123",
      "name": "my-web-app",
      "status": "running",
      "uptime": 3600
    }
  ]
}

Build Management

Kill Build

Terminate an ongoing build process.

Endpoint

POST /application.killBuild

Request Body

applicationId

string

required

ID of the application

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.killBuild \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Clean Queues

Clear the deployment queue for an application.

Endpoint

POST /application.cleanQueues

Request Body

applicationId

string

required

ID of the application

Example Request

curl -X POST https://your-dokploy-instance.com/api/application.cleanQueues \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_def456"
  }'

Example Response

{
  "success": true
}

Best Practices

Resource Management

Set Resource Limits: Always configure memory and CPU limits to prevent resource exhaustion:

{
  "memoryLimit": "1g",
  "memoryReservation": "512m",
  "cpuLimit": "1",
  "cpuReservation": "0.5"
}

Use Health Checks: Configure health checks to ensure proper application monitoring and automatic recovery.
Clean Old Deployments: Regularly use clearDeployments to free up disk space.

Deployment Strategy

Use Descriptive Titles: Provide meaningful titles and descriptions for deployments to maintain clear audit trails.
Test Before Production: Use preview deployments or separate environments before deploying to production.
Enable Auto Deploy Carefully: Only enable autoDeploy after thorough testing of your CI/CD pipeline.

Security

Protect Secrets: Use buildSecrets for sensitive build-time data instead of buildArgs.
Use Private Registries: For proprietary applications, always use private Docker registries with authentication.
Rotate Tokens: Regularly use the refreshToken endpoint to rotate application tokens.

Monitoring

Check Status Regularly: Monitor applicationStatus to detect issues early.
Use Monitoring Endpoint: Leverage readAppMonitoring to track resource usage and performance.
Configure Alerts: Set up alerts based on memory and CPU thresholds.

Troubleshooting

Deployment Stuck

If a deployment is stuck in running status:

Check the deployment logs
Use killBuild to terminate the build
Use cleanQueues to clear the queue
Retry with redeploy

Application Won’t Start

If an application fails to start:

Check Traefik configuration with readTraefikConfig
Verify resource limits are not too restrictive
Check environment variables are properly configured
Review container logs for errors

Git Provider Issues

If you have Git provider access issues:

Check hasGitProviderAccess in the application response
Reconnect the Git provider if needed
Verify webhook configuration in your Git repository
Ensure the Git provider token hasn’t expired

Getting Started

Applications

Databases

Docker

Projects & Deployments

Monitoring

Administration

​Start Application

​Endpoint

​Request Body

​Example Request

​Example Response

​Stop Application

​Endpoint

​Request Body

​Example Request

​Example Response

​Reload Application

​Endpoint

​Request Body

​Example Request

​Example Response

​Delete Application

​Endpoint

​Request Body

​Example Request

​Example Response

​Mark Application as Running

​Endpoint

​Request Body

​Example Request

​Move Application

​Endpoint

​Request Body

​Response

​Example Request

​Example Response

​Refresh Token

​Endpoint

​Request Body

​Example Request

​Example Response

​Traefik Configuration

​Read Traefik Config

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Update Traefik Config

​Endpoint

​Request Body

​Example Request

​Example Response

​Monitoring

​Read Application Monitoring

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Build Management

​Kill Build

​Endpoint

​Request Body

​Example Request

​Clean Queues

​Endpoint

​Request Body

​Example Request

​Example Response

​Best Practices

​Resource Management

​Deployment Strategy

​Security

​Monitoring

​Troubleshooting

​Deployment Stuck

​Application Won’t Start

​Git Provider Issues

Build docs developers (and LLMs) love

Start Application

Endpoint

Request Body

Example Request

Example Response

Stop Application

Endpoint

Request Body

Example Request

Example Response

Reload Application

Endpoint

Request Body

Example Request

Example Response

Delete Application

Endpoint

Request Body

Example Request

Example Response

Mark Application as Running

Endpoint

Request Body

Example Request

Move Application

Endpoint

Request Body

Response

Example Request

Example Response

Refresh Token

Endpoint

Request Body

Example Request

Example Response

Traefik Configuration

Read Traefik Config

Endpoint

Query Parameters

Example Request

Example Response

Update Traefik Config

Endpoint

Request Body

Example Request

Example Response

Monitoring

Read Application Monitoring

Endpoint

Query Parameters

Example Request

Example Response

Build Management

Kill Build

Endpoint

Request Body

Example Request

Clean Queues

Endpoint

Request Body

Example Request

Example Response

Best Practices

Resource Management

Deployment Strategy

Security

Monitoring

Troubleshooting

Deployment Stuck

Application Won’t Start

Git Provider Issues