Endpoints

Webhook Listener

The application listens for incoming webhooks on the /v1/webhook endpoint with the port specified by the HTTP_PORT environment variable, see App Settings. The webhook payload is expected to be in JSON format and must contain the payload from a supported the Git provider, see Supported Git Providers.

With custom Target

You can specify multiple deployment target configurations in a mono-repo style setup using the application's dynamic webhook path. This allows you to deploy to different targets/locations from a single repository.

If a webhook payload gets sent to a custom path suffix /v1/webhook/<custom_name>, the application will look for a deployment configuration file with the same pattern in its name .doco-cd.<custom_name>.yaml.

Examples

Webhook Target	Deployment Config File
/v1/webhook	.doco-cd.yaml
/v1/webhook/gitea	.doco-cd.gitea.yaml
/v1/webhook/paperless-ngx	.doco-cd.paperless-ngx.yaml
/v1/webhook/my.server.com	.doco-cd.my.server.com.yaml

Query Parameters

wait

Webhooks trigger deployments asynchronously by default, meaning the application will respond immediately to the webhook request and process the deployment in the background. Use the wait=true query parameter to make the application wait for the deployment to finish before responding. This may increase response time, and some Git/SCM providers might time out the request if the deployment takes too long. Even if the request times out, the deployment will still continue.

Example: /v1/webhook?wait=true

REST API

The application exposes a RESTful API at the /v1/api endpoint.

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

Endpoints

Compose Projects

Endpoint	Method	Description	Query Parameters
/v1/api/projects	GET	List all deployed compose projects	- all (boolean, default: false): Return all projects including inactive ones.
/v1/api/project/{projectName}	GET	Get details of a project
/v1/api/project/{projectName}	DELETE	Remove a project	- volumes (boolean, default: true): remove all associated volumes. - images (boolean, default: true): remove all associated images.
/v1/api/project/{projectName}/start	POST	Start a project
/v1/api/project/{projectName}/stop	POST	Stop a project
/v1/api/project/{projectName}/restart	POST	Restart a project

Swarm Stacks

Endpoint	Method	Description	Query Parameters
/v1/api/stacks	GET	List all deployed Swarm stacks
/v1/api/stack/{stackName}	GET	Get details of a Swarm stack
/v1/api/stack/{stackName}	DELETE	Remove a Swarm stack
/v1/api/stack/{stackName}/scale	POST	Rescale a Swarm stack or service	- replicas (integer): Scale to n replicas. - service (string, optional): Name of service to scale. - wait (boolean, default: true): Wait for service to be running/healthy
/v1/api/stack/{stackName}/restart	POST	Restart/Redeploy a Swarm stack or service	- service (string, optional): Name of service to restart.
/v1/api/stack/{stackName}/run	POST	Trigger one or all jobs in stack	- service (string, optional): Name of the job service to run.

Global Query Parameters

Query Parameter	Type	Description
timeout	integer	Timeout in seconds (default: 30).

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"

Health Check

The application 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"
}

Prometheus Metrics

The application exposes Prometheus metrics at the /metrics endpoint. This endpoint provides various metrics about the application's performance and health, which can be scraped by a Prometheus server for monitoring purposes.

By default, this endpoint is available on Port 9120, but can be configured using the METRICS_PORT environment variable, see App Settings.

Grafana Dashboard

An example for a Grafana Dashboard can be found at Grafana Dashboard #583.