Skip to content
HD ServicesHDDeploy Help

The REST API

For scripts and CI pipelines your server has a REST API with the same permissions and the same audit trail as the portal.
Base address https://<your-server>.hddeploy3000.nl/api/v1
Description OpenAPI 3.1 at /api/v1/openapi.json, available without a token
Sign in header Authorization: Bearer hdd_... (see API tokens and scopes)
Errors application/problem+json with a readable detail
Limit 120 requests per minute per token (uploads excepted); 429 above that

How it works

Section titled “How it works”

Long actions return a job. A deploy, stop or backup answers 202 Accepted with a job id. Wait for it with GET /jobs/{id}/wait?timeout=120; the answer holds the status and the output. If done is not yet true, call again.

Writes carry the revision. Whoever changes the compose file, the variables or the settings sends the revision number the change is based on: header If-Match: "7" (with quotes) or the field revision in the body. If the stack changed in the meantime, the answer is 412 Precondition Failed: read the stack again and retry.

A refused compose file gives 422. The answer holds one line in errors[] per broken platform rule. See Compose files and platform rules.

A missing scope gives 403, a wrong or expired token 401.

Endpoints

Section titled “Endpoints”
Method and path Does
GET /me Who you are and which scopes the token carries
GET /overview Attention items and summary
GET /stacks, GET /stacks/{name} Stacks and one stack
GET/PUT /stacks/{name}/compose Read and replace the compose file
POST /stacks/{name}/validate Check a compose file without saving
GET/PUT /stacks/{name}/env Read and change the variables
PUT /stacks/{name}/settings Change the template settings
POST /stacks/{name}/deploy, .../stop, .../pull Deploy, stop, pull images (202 + job)
PUT /stacks/{name}/autoupdate Nightly update on or off
GET /stacks/{name}/revisions, GET .../revisions/{id}, POST .../revisions/{id}/restore Read and restore revisions
GET/PUT /stacks/{name}/source, POST .../source/check, .../pin, .../unpin The git source
PUT /stacks/{name}/source/upload Upload the source tree as an archive (see Uploading files)
GET/POST /stacks/{name}/access The access list
POST/DELETE /stacks/{name}/webhooks/deploy Enable, rotate or disable the deploy webhook
GET /containers, POST /containers/{id}/start, .../stop, .../restart, GET .../logs Containers
GET /jobs, GET /jobs/{id}, GET /jobs/{id}/wait Jobs
GET /sites, GET /sites/{name}, PUT /sites/{name} Sites; PUT creates an upload-only site
POST /sites/{name}/check, POST /sites/{name}/restore Check the source, restore a previous version
PUT /sites/{name}/content Upload an archive
GET/PUT /sites/{name}/draft/files, POST .../draft/publish, DELETE .../draft The draft
GET /sites/{name}/files, GET /sites/{name}/file?path= Read files
GET /backups, GET /backups/{name}/files, POST /backups/{name}/run Backups
GET /alerts, GET/POST /alerts/channels, DELETE /alerts/channels/{id}, POST /alerts/test Alerts
GET /certificates, POST /certificates/request, POST /certificates/upload, DELETE /certificates/{name} Certificates
GET/POST /registries, DELETE /registries/{host} Registry logins

The exact fields of every request and response are in the OpenAPI document; most API tools (Postman, Bruno, the OpenAPI generators) read it directly.

Examples

Section titled “Examples”
Terminal window
# Who am I?
curl -H "Authorization: Bearer hdd_..." \
     https://<your-server>.hddeploy3000.nl/api/v1/me


# Deploy a stack and wait for the job
curl -X POST -H "Authorization: Bearer hdd_..." \
     https://<your-server>.hddeploy3000.nl/api/v1/stacks/myapp/deploy
curl -H "Authorization: Bearer hdd_..." \
     "https://<your-server>.hddeploy3000.nl/api/v1/jobs/j-.../wait?timeout=120"


# Change variables, based on revision 7
curl -X PUT -H "Authorization: Bearer hdd_..." -H 'If-Match: "7"' \
     -H "Content-Type: application/json" \
     -d '{"values": {"PHP_MEMORY_LIMIT": "512M"}}' \
     https://<your-server>.hddeploy3000.nl/api/v1/stacks/myapp/env


# Check a compose file without saving
curl -X POST -H "Authorization: Bearer hdd_..." \
     -H "Content-Type: application/json" \
     -d '{"content": "services:\n  web:\n    image: nginx:stable\n"}' \
     https://<your-server>.hddeploy3000.nl/api/v1/stacks/myapp/validate

Webhooks are something else

Section titled “Webhooks are something else”

The API above works with your personal token and can do everything you can. For a CI pipeline that only needs to deploy or to have a site synced, there are separate webhooks with their own token that allows exactly one action on one stack or site.