Platform API
Everything the web console does goes through this HTTP API; you can script all of it.
The interactive reference (every endpoint, every field, try-it-out) is served by your installation at /docs (Swagger UI), and the raw schema at /openapi.json.
This page is the short guide to the platform API of your own installation: authentication, conventions, and the calls people use most.
Examples use $BASE (for example https://dsp.example.com) and $TOKEN (an API token).
Authentication
Send Authorization: Bearer $TOKEN. Tokens are created in the console (Tokens) or with POST /api/tokens; the secret is shown once.
| Role | What it can do |
|---|---|
admin |
everything |
devops |
read, deploy, roll back, manage secrets, read audit and license |
developer |
read, deploy, list secret names (never values) |
viewer |
read only |
Create a token for CI (admin token required):
curl -s -X POST $BASE/api/tokens -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' \
-d '{"name":"ci-shop","role":"developer"}'
# {"id":"…","name":"ci-shop","role":"developer","token":"…"} <- store it now
Console users sign in with a username and password (POST /api/auth/login, optional TOTP). Browser sessions are separate from API tokens.
Conventions
- JSON in, JSON out. Names (
slug, namespace, deployment) are lowercase DNS names. - Errors:
401no or bad credentials,403your role lacks the permission or the plan limit is reached,404not found,409conflict,422invalid input (thedetailfield says what is wrong). - Secret values are write-only: no endpoint returns them.
- Every change is written to the audit log (
GET /api/audit).
Deploy and roll back
# build from the branch and roll out (needs `deploy`)
curl -s -X POST "$BASE/api/projects/shop/redeploy?environment=prod" -H "Authorization: Bearer $TOKEN"
# releases of a project, newest first
curl -s "$BASE/api/projects/shop/releases?environment=prod" -H "Authorization: Bearer $TOKEN"
# roll back without a rebuild (needs `rollback`); `to=<release id>` picks a specific release, otherwise the previous one
curl -s -X POST "$BASE/api/projects/shop/rollback?environment=prod" -H "Authorization: Bearer $TOKEN"
# state in the cluster: replicas, pods, conditions
curl -s "$BASE/api/projects/shop/runtime?environment=prod" -H "Authorization: Bearer $TOKEN"
environment is a query parameter (default prod). A push to the connected branch deploys automatically through the Git webhook (POST /webhook/{provider}/{slug}); see GET /api/projects/{slug}/webhook for the URL and how to register it.
If the new version does not become ready, the rollout is reported as failed and the previous version stays in place.
Projects and environments
| Call | Purpose |
|---|---|
GET /api/projects, POST /api/projects |
list / create (with its environments) |
PATCH / DELETE /api/projects/{slug} |
change / delete |
GET, POST /api/projects/{slug}/environments |
environments |
PATCH, DELETE /api/projects/{slug}/environments/{name} |
branch, auto_deploy, require_approval, cluster, server |
GET, PUT, DELETE /api/projects/{slug}/members[/{username}] |
project members and roles |
Create a project:
curl -s -X POST $BASE/api/projects -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' -d '{
"slug":"shop","repo_full_name":"acme/shop",
"environments":[{"name":"prod","namespace":"shop","deployment_name":"shop","container_name":"shop"}]}'
Secrets
Values are encrypted at rest, versioned, and never returned.
curl -s -X PUT $BASE/api/projects/shop/secrets/DATABASE_URL -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"value":"postgres://…","rotation_days":90}'
curl -s $BASE/api/projects/shop/secrets -H "Authorization: Bearer $TOKEN" # names, versions, expiry only
curl -s -X POST $BASE/api/projects/shop/secrets/sync -H "Authorization: Bearer $TOKEN" # push to the cluster
POST …/secrets/import accepts the text of a .env file. GET …/secrets/{key}/versions and POST …/secrets/{key}/restore give history and restore.
Custom domain and certificate
curl -s -X PUT $BASE/api/projects/shop/environments/prod/domain -H "Authorization: Bearer $ADMIN" \
-H 'Content-Type: application/json' -d '{"host":"shop.example.com"}' # HTTPS via Let's Encrypt
# your own certificate (PEM chain: server certificate first; unencrypted private key)
curl -s -X PUT $BASE/api/projects/shop/environments/prod/domain/certificate -H "Authorization: Bearer $ADMIN" \
-H 'Content-Type: application/json' \
-d "$(jq -n --rawfile c fullchain.pem --rawfile k privkey.pem '{certificate:$c,private_key:$k}')"
The certificate is validated (key matches, host name covered, not expired). DELETE …/domain/certificate returns to automatic certificates.
Connection check (external database, cache, storage)
From the platform's own network, with step-by-step results (DNS, TCP, TLS, login):
curl -s -X POST $BASE/api/projects/shop/connections/probe -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"targets":[{"kind":"postgres","host":"db.internal","port":5432,"tls":"verify-full"}]}'
kind: postgres, mysql, redis, s3, https, tcp. tls: off, prefer, require, verify-ca, verify-full; ca_pem may carry your CA.
Credentials, if given, are used for this one check and are not stored. Private and metadata addresses are refused, and checks are rate-limited.
Event Explorer
GET /api/explorer/events (needs audit:read). Parameters: q, range (1h, 24h, 7d, 30d, 90d) or start/end (ISO time, up to 366 days), limit (≤ 200), offset.
Query language: space-separated conditions, all must match.
| Syntax | Meaning |
|---|---|
action:deploy* |
field equals value; * is a wildcard (case-insensitive) |
-actor:ci-bot |
exclude |
result:failed |
ok or failed (actions containing failed, denied, error, rejected, forbidden) |
timeout |
free text in action, actor and details |
"two words" |
quotes for values with spaces |
Fields: action, actor, project, result. OR is not supported. A bad query returns 422 with the reason.
The response has total, the page of events, a histogram (buckets with n and failed) and fields (top values with counts).
curl -s -G $BASE/api/explorer/events -H "Authorization: Bearer $TOKEN" \
--data-urlencode 'q=project:shop result:failed' --data-urlencode 'range=7d'
Audit and integrity
GET /api/audit?project=&action=&limit= lists events; GET /api/audit/verify checks the tamper-evident chain and returns the head hash. Record the head hash somewhere outside the platform to prove later that history was not rewritten.
Approvals
Environments with require_approval queue deployments: GET /api/approvals, then POST /api/approvals/{id}/approve or /deny. The author cannot approve their own request.
License and plan
GET /api/license returns the plan, limits, features and the installation ID to quote when ordering a key. Limits are enforced on creation: you get 403 with the limit named when a plan maximum is reached.
| Plan | Projects | Environments / project | Users |
|---|---|---|---|
| Community | 1 | 1 | 1 |
| Lite | 5 | 3 | 3 |
| Pro | 25 | 10 | 10 |
| Max | unlimited | unlimited | unlimited |
Other endpoints, grouped: notifications (/api/notifications/*), SIEM destinations (/api/siem/*), clusters (/api/clusters), servers (/api/servers), previews (/api/projects/{slug}/previews), users (/api/users), onboarding wizard (/api/onboarding/*), overview figures (/api/overview), health (/health). Clusters, servers, SIEM and previews come with the paid module.