REST API¶

Doco-CD exposes a RESTful API at the /v1/api endpoint. Set both HTTP_TLS_CERT_FILE and HTTP_TLS_KEY_FILE if you want doco-cd itself to serve the API over HTTPS.

Authentication¶

Set the API_SECRET or API_SECRET_FILE environment variable in the container to enable the API, see App Settings.

Use the x-api-key header to authenticate requests to the API using the secret value.

Example:

curl -H "x-api-key: your_api_key" http://example.com/v1/api/projects

Query Parameters¶

Management endpoints support these common query parameters:

Docker context selection¶

Project, stack, and scheduled-job endpoints accept one optional context query parameter. If it is omitted or set to default, the endpoint uses the default Docker context. Named contexts must exist in the Docker CLI context store available to doco-cd.

These endpoints return the selected external context name in the X-Doco-CD-Context response header. Their JSON response shapes do not change.

curl -i -H "x-api-key: your_api_key" \
  "http://example.com/v1/api/projects?context=remote"

Endpoints¶

Health Check¶

Doco-CD exposes a health check endpoint at /v1/health that, if the application is healthy, returns a 200 status code and the following JSON response:

{
  "details": "healthy"
}

If the application is not healthy, the endpoint returns a 503 status code and the following JSON response:

{
  "details": "unhealthy",
  "error": "some error message"
}

Deployment Runs¶

The API tracks deployment-related runs (for example webhook-triggered deployments and API-triggered poll runs) in memory. Use these endpoints to inspect the current status and recent history by job_id. Each run's deployments collection reports the resolved stack and Docker context targets. A single poll or webhook run can contain targets from multiple contexts.

Example Requests¶

curl --request GET \
  --url 'https://cd.example.com/v1/api/runs?status=running&limit=20' \
  --header 'x-api-key: your-api-key'

curl --request GET \
  --url 'https://cd.example.com/v1/api/run/550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-api-key: your-api-key'

Polling¶

The request body must be a JSON array of poll configurations, each containing at least a url field containing the Git clone URL to the repository.

The fields run_once and interval will be ignored for poll runs triggered via the API, as they are only relevant for the scheduled poll runs.

Example Request¶

Minimal example using the default settings:

curl --request POST \
  --url 'https://cd.example.com/v1/api/poll/run?wait=true' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your-api-key' \
  --data '[
  {
    "url": "https://github.com/your/repo.git",
  }
]'

Example with custom reference and inline deployment configuration:

curl --request POST \
  --url 'https://cd.example.com/v1/api/poll/run?wait=true' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your-api-key' \
  --data '[
  {
    "url": "https://github.com/your/repo.git",
    "reference": "dev",
    "deployments": [
      {
        "name": "my-app",
        "working_dir": "/app",
        "env_files": [
          ".env"
        ]
      }
    ]
  }
]'

Scheduled Jobs¶

• If multiple jobs share the same jobName, provide stack to disambiguate for the run endpoint.
• If the same job and stack names exist on multiple Docker contexts, provide context.
• If the matched job is disabled, the run endpoint returns a conflict response.

Common run endpoint outcomes

• 200 OK: run triggered and completed (wait=true).
• 202 Accepted: run accepted and running in background (wait=false).
• 404 Not Found: no scheduled job matched jobName (and optional stack).
• 409 Conflict: matched job is disabled or the selection is ambiguous.

Example Request¶

curl --request POST \
  --url 'https://cd.example.com/v1/api/job/my-stack-backup-1/run?wait=true' \
  --header 'x-api-key: your-api-key'

curl --request POST \
  --url 'https://cd.example.com/v1/api/job/backup/run?stack=my-stack&wait=true' \
  --header 'x-api-key: your-api-key'

curl --request GET \
  --url 'https://cd.example.com/v1/api/jobs?stack=my-stack' \
  --header 'x-api-key: your-api-key'

Compose Projects¶

Swarm Stacks¶

Example Request¶

List all deployed compose projects¶

curl -H "x-api-key: your_api_key" "http://example.com/v1/api/projects?all=true"

Remove a specific project without removing associated volumes¶

curl -X DELETE -H "x-api-key: your_api_key" "http://example.com/v1/api/project/my_project?volumes=false"

Restart a specific project with a custom timeout¶

curl -X POST -H "x-api-key: your_api_key" "http://example.com/v1/api/project/my_project/restart?timeout=60"