API Documentation

Dokku Pro exposes all of it's functionality behind a restful API using the json-api specification. The OpenAPI spec is exposed via swagger integration for ease of development.

A copy of the OpenAPI specification is available here.

To apply many changes in a single request - for example saving all of an app's environment variables at once - see Batch Operations.

App-scoped endpoints

Resources that belong to an app - environment variables, domains, formations, buildpacks, resources, certificates, letsencrypt, http auth, maintenance mode, the GitHub webhook configuration, and the builder and scheduler settings - are managed under the owning app at /apps/{appId}/.... For example, create an environment variable with POST /apps/{appId}/envs and remove one with DELETE /apps/{appId}/envs/{envId}, so the app is a path parameter rather than a request body attribute.

The equivalent top-level routes (POST /envs, DELETE /envs/{envId}, and the like) remain available but are deprecated in favor of the nested routes.

Authentication

Dokku uses Token-based Authentication to exchange user credentials for an expiring JWT token. The JWT token can then be used to access any internal Dokku api endpoints.

The following is an example of authenticating via curl:

username="root"
password="root-token"

curl --silent \
     -u "${username}:${password}" \
     -H "Content-Type: application/json" \
     -d '{"data": {"type": "tokens"}}' \
     --output token.json \
     "https://admin.dokku.me/@api/tokens"

# the jwt token is in the response
cat token.json | jq -r '.data.id'

The JWT token is then used for Bearer authentication to other API endpoints:

jwt_token="$(cat token.json | jq -r '.data.id')"

curl -H 'Authorization: Bearer ${jwt_token}' \
     -H "Content-Type: application/json" \
     "https://admin.dokku.me/@api/apps"