Skip to content

API Documentation

Dokku Pro exposes all of its functionality behind a RESTful API that follows the JSON:API specification, so anything you can do in the UI you can also automate. Every route lives under the /@api/ prefix (for example https://admin.dokku.me/@api/apps), and the interactive Swagger UI lets you explore it in the browser.

A copy of the OpenAPI specification is also available here for reference; a running server serves its own live spec at /swagger/openapi.yml.

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

Note

The admin.dokku.me host used in the examples on this page is the public demo server. Replace it with your own Dokku Pro address.

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 /@api/apps/{appId}/.... For example, create an environment variable with POST /@api/apps/{appId}/envs and remove one with DELETE /@api/apps/{appId}/envs/{envId}, so the app is a path parameter rather than a request-body attribute.

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

Authentication

Dokku Pro uses token-based authentication: exchange a user's credentials for an expiring JWT, then send that token on subsequent requests. Request a token by authenticating with basic auth against the tokens endpoint:

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'

Send the JWT as a Bearer token on every other endpoint:

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"