HTTP API
The web interface uses this API; you can use it too. All paths are under /api, JSON in and out.
Conventions
- Session: sign in with
POST /api/auth/login (cookie dp_session). With two-factor, the session is
MFA pending until POST /api/auth/mfa.
- CSRF: every non-GET request needs the header
X-CSRF-Token equal to the dp_csrf cookie, and an Origin
matching the public URL when present.
- Errors:
{"error": "message"} with 400/401/403/404/409/422/429/500. 422 is a validation problem the person
can fix; 409 means another run is in progress.
- Runs: long operations answer
202 {"runId": n}; follow GET /api/runs/{id}/events (Server-Sent Events:
line events {seq, step, level, text}, then one end event with the run).
Public
| Method |
Path |
Description |
| GET |
/health |
{"status":"ok"} |
| GET |
/setup/status |
first-run state, whether OIDC sign-in is enabled |
| POST |
/setup |
first administrator {token, email, name, password, oidc?} |
| GET |
/auth/me |
current user, or 401 |
| POST |
/auth/login |
{email, password} → {mfaRequired} |
| POST |
/auth/mfa |
{code} |
| POST |
/auth/logout |
|
| GET |
/auth/oidc/start, /auth/oidc/callback |
sign-in through the configured identity provider |
| GET |
/autologin/{name} |
used by nginx only (loopback and per-app token) |
Signed in (any role)
| Method |
Path |
Description |
| POST |
/account/password |
change password |
| POST |
/account/totp/setup, /enable, /disable |
two-factor |
| PUT |
/account/profile |
name |
| GET |
/dashboard |
counts, recent runs |
| GET |
/apps, /apps/{name} |
apps (the app includes identity: account method, options with evidence, values) |
| GET |
/apps/{name}/status |
containers, HTTP probe, certificate |
| GET |
/apps/{name}/logs?tail= |
container logs |
| GET |
/apps/{name}/runs, /runs/{id}, /runs/{id}/events |
history and live logs |
| GET |
/apps/{name}/files |
files on disk (secrets masked for viewers) |
| GET |
/catalog |
templates |
| GET |
/hub/search?q=&page=&sort=&official=, /hub/tags?repo=, /hub/inspect?ref= |
Docker Hub |
| GET |
/system |
integrations, tool versions, conventions |
Editors
| Method |
Path |
Description |
| POST |
/apps/check |
{name} → availability (DNS, folder, site, container, certificate) |
| POST |
/apps |
create a draft {name, templateId \| image, tag?, title?} |
| PUT |
/apps/{name}/draft |
save {title, compose, secrets, composeEditor, nginx, nginxEditor, auth, account, adminUser, samlAcs, samlAudience, sharedUser, sharedPassword, step} (all optional) → {app, identity} |
| POST |
/apps/{name}/preview |
plan, files, lint, availability |
| POST |
/apps/{name}/deploy |
{acceptRisks} → run |
| POST |
/apps/{name}/action |
{action: restart \| stop \| start} → run |
| PUT |
/apps/{name}/compose |
update {mode, spec \| text, secrets, acceptRisks} → run |
| PUT |
/apps/{name}/nginx |
update {mode, spec \| text} → run |
| PUT |
/apps/{name}/access |
{groups:[{pk,name}]} (immediate) |
| POST |
/apps/{name}/sso |
change the account method {account, adminUser?, samlAcs?, sharedUser?, sharedPassword?}; empty body = apply the recipe → run |
| POST |
/apps/{name}/recipe |
save the app's setup as a recipe {keys, steps, notes} |
| POST |
/compose/render, /compose/parse, /compose/validate |
compose model ⇄ YAML, lint + docker compose config |
| POST |
/nginx/render, /nginx/parse, /nginx/validate |
nginx model ⇄ text, isolated nginx -t |
| GET |
/authentik/groups |
groups with members, suggestions, app access |
| GET |
/authentik/users |
Authentik users (admin picker) |
| GET |
/sso/detect?image= |
single sign-on evidence for an image |
| GET |
/secrets/generate?kind= |
a random value (password, hex16, hex32) |
Account values: recipe, oidc, saml, header, none, basic, autologin, own (empty = the app's
default).
Admins
| Method |
Path |
Description |
| DELETE |
/apps/{name} |
delete {confirm: name, deleteData, removeDns, removeCert, removeAccess, removeVolumes, removeImages, removeArchives, includePreexisting, forgetHistory} → run |
| GET, POST |
/admin/users |
list, create |
| PUT, DELETE |
/admin/users/{id} |
update (role, disabled, password reset, TOTP reset), delete |
| GET, PUT |
/admin/oidc, POST /admin/oidc/test |
Deployer's own sign-in through an identity provider |
| GET |
/admin/audit |
audit log |
| GET, PUT |
/admin/authentik |
connection, outpost and flows |
| POST |
/admin/authentik/discover |
test a URL/token and list outposts and flows |
| POST |
/admin/authentik/bootstrap |
"Connect automatically" |
| DELETE |
/admin/authentik/token |
disconnect |
Example
B=https://deploy.example.com/api
curl -s -c j -b j $B/auth/me >/dev/null # get the CSRF cookie
T=$(awk '$6=="dp_csrf"{print $7}' j)
curl -s -c j -b j -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
-d '{"email":"me@example.com","password":"…"}' $B/auth/login
curl -s -b j -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
-d '{"name":"notes","templateId":"memos"}' $B/apps