REST API

The platform exposes a REST API at https://api.run-zero.de. The Web Dashboard and the MCP server use it. Anything they do, you can do with curl.

Authentication

All non-public endpoints require a Bearer token in the Authorization header. The token is either an API key (machine use) or a JWT from Keycloak (browser sessions). For automation always use an API key.

Generate an API key

Sign in to dashboard.run-zero.de.
Open your profile (top-right avatar) → API Keys.
Click Create. The key is shown once, so copy it immediately.

Keys have the prefix runzero_ followed by 64 hex characters. They're stored hashed; if you lose one, generate a new one. Keys created before the rename start with itdone_ and keep working.

Use the key

bash

export RUNZERO_API_KEY=runzero_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer $RUNZERO_API_KEY" \
     https://api.run-zero.de/apps

App manifest

An app with several services or with addons describes them in run-zero.yaml at the repo root. A deploy reads it and creates the services and addons. Repos with an itdone.yaml keep working with the same format; if both files exist, run-zero.yaml wins.

Resources

Standard CRUD endpoints. Names are app-name-scoped: /apps/:name/services etc.

Resource	Path
Apps	`/apps`, `/apps/:name`
Services	`/apps/:name/services`
Service logs	`/apps/:name/services/:service/logs`
Secrets	`/apps/:name/services/:service/secrets`
Domains	`/apps/:name/services/:service/domains`
Addons	`/apps/:name/addons`
Builds	`/apps/:name/builds`
Deploys	`POST /apps/:name/deploy`
Current user	`/me`

Examples

List your apps

bash

curl -H "Authorization: Bearer $RUNZERO_API_KEY" \
     https://api.run-zero.de/apps

Create an app linked to a repo

bash

curl -X POST https://api.run-zero.de/apps \
  -H "Authorization: Bearer $RUNZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "repo": "https://github.com/org/my-app",
    "branch": "main"
  }'

Add a service

bash

curl -X POST https://api.run-zero.de/apps/my-app/services \
  -H "Authorization: Bearer $RUNZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "path": "",
    "port": 8080
  }'

Tail logs

bash

curl -H "Authorization: Bearer $RUNZERO_API_KEY" \
     "https://api.run-zero.de/apps/my-app/services/web/logs?tail=200"

Set environment variables

bash

curl -X POST https://api.run-zero.de/apps/my-app/services/web/secrets \
  -H "Authorization: Bearer $RUNZERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "STRIPE_KEY": "sk_live_…", "FEATURE_FLAG": "on" }'

Deploy

bash

curl -X POST https://api.run-zero.de/apps/my-app/deploy \
  -H "Authorization: Bearer $RUNZERO_API_KEY"

Responses

All responses are JSON. Errors follow the format { "statusCode": 4xx, "message": "…", "error": "…" } with a matching HTTP status. 401 = missing/invalid token, 403 = not your resource, 404 = not found.

Rate limits

No hard rate limits today; abuse will be throttled per-key. If you need a higher-throughput integration, get in touch.