Dokploy API from the CLI

Operate Dokploy entirely from curl when the dashboard isn't practical (scripting, agents, headless ops).

Auth

Generate an API token in dashboard → Profile → API. Pass on every request:

-H "x-api-key: $TOKEN"

Other auth headers (Authorization: Bearer …) return 401 Unauthorized. There is no public OpenAPI/swagger endpoint — discover routes by probing.

Endpoint Catalog (verified)

All endpoints are under https://<dokploy-host>/api/<router>.<procedure>. Reads are GET with query params, writes are POST with JSON body.

Discovery

Endpoint	Notes
GET /api/project.all	List projects
GET /api/project.one?projectId=<id>	Project + nested environments[].{applications, mongo, postgres, redis, compose}
GET /api/postgres.one?postgresId=<id>	Includes appName (internal hostname), databasePassword, externalPort
GET /api/application.one?applicationId=<id>	Includes env (multiline string), sourceType, dockerImage, customGitUrl
GET /api/compose.one?composeId=<id>	Includes composeFile, sourceType
GET /api/deployment.all?applicationId=<id>	Deploy history (most recent first); composeId works too
GET /api/docker.getContainersByAppNameMatch?appName=<appName>	Live container state — use to check actual run status

Postgres

Endpoint	Required body
POST /api/postgres.create	{name, appName, databaseName, databaseUser, databasePassword, dockerImage, environmentId}
POST /api/postgres.update	{postgresId, ...fields-to-change} (e.g. externalPort: 5433 or null)
POST /api/postgres.deploy	{postgresId} — required after update to apply port/image changes

Compose (one-shot or long-running stacks)

Endpoint	Required body
POST /api/compose.create	{name, appName, environmentId, composeType: "docker-compose"}
POST /api/compose.update	{composeId, name, description, env, composeFile, sourceType: "raw", composeType, autoDeploy, command} — full replace, all fields required
POST /api/compose.deploy	{composeId}
POST /api/compose.stop	{composeId}
POST /api/compose.delete	{composeId} — also removes containers

Application (long-running services)

Endpoint	Required body
POST /api/application.saveDockerProvider	{applicationId, dockerImage, username, password, registryUrl} (use empty strings for public images)
POST /api/application.saveGitProvider	{applicationId, customGitUrl, customGitBranch, customGitBuildPath, watchPaths, customGitSSHKeyId}
POST /api/application.saveBuildType	{applicationId, buildType: "dockerfile"|"nixpacks"|"heroku"|…, dockerfile, dockerContextPath, dockerBuildStage, herokuVersion, railpackVersion}
POST /api/application.saveEnvironment	{applicationId, env, buildArgs, buildSecrets, createEnvFile} (env is the entire multiline KEY=VALUE string)
POST /api/application.deploy	{applicationId}

Critical Gotcha: deploy status ≠ container status

deployment.all returns status: "done" as soon as Dokploy's outer compose-up exits successfully. The actual workload container may still be initializing, building, or even crashed afterwards.

For a true pass/fail signal, poll docker.getContainersByAppNameMatch and watch the container's state (running → exited) and status text.

# Wrong: only watches deploy step
poll deployment.all → done = ❌ may still be building inside

# Right: watch the actual container
poll docker.getContainersByAppNameMatch → state=running → state=exited → check exit code

Switching application source: docker registry ↔ git build

Useful when the registry image is outdated (e.g., you need today's master before tagging a release):

1. application.saveGitProvider — point at the repo + branch
2. application.saveBuildType — set buildType: "dockerfile", dockerfile: "<path>" (e.g. dockerfile)
3. application.deploy — Dokploy clones, builds, swaps service

To switch back after the image is published:

1. application.saveDockerProvider — set dockerImage: "<repo>:<tag>", registryUrl: "index.docker.io"
2. application.deploy — pulls and swaps

sourceType and related fields update automatically based on which save*Provider you called last.

Probing for unknown endpoint shapes

POST with empty body to discover the required fields via the Zod error response:

curl -sS -X POST -H "x-api-key: $TOKEN" -H "content-type: application/json" \
  "https://<host>/api/postgres.create" -d '{}'
# → {"zodError":{"fieldErrors":{"name":[...],"databaseName":[...],...}}}

This is faster than guessing and works for every mutation route.

Common Mistakes

Mistake	Fix
Trusting deployment.all status alone	Cross-check docker.getContainersByAppNameMatch
Calling compose.deploy with stale exited containers from a prior run	ssh host docker rm -f <appName>-<service>-1 first, or compose.stop then compose.deploy
Hostname mismatch when service names contain hyphens	Use the auto-generated appName (e.g. mx-space-pg-7pacdz), not the user-friendly name
Updating compose YAML and expecting current container to reflect it	YAML applies on next deploy; running container keeps the YAML it started with
Updating externalPort without redeploy	Must call postgres.deploy (or equivalent) to apply port mapping