Reference

API

Everything the panel and agents do, over HTTP.

The panel serves the runner's API at /api, for agents with a zk_ token. The runner itself listens on port 8081, for the app that manages it, with the root token. Both take the same requests. The same API is an MCP server at /mcp, with the same tokens: see MCP.

Authentication

Every request takes a bearer token:

http

Authorization: Bearer zk_...

Token
Root	From `ZEROKO_TOKEN`, for the app that manages the runner.
`zk_…`	Made with `POST /api/tokens` or in the panel, for agents. Full access to every service; expires after up to 3650 days, or never. The runner stores only its hash and shows it once.

http

GET    /api/tokens        → [{id, name, prefix, created_at, last_used_at, expires_at}]
POST   /api/tokens        {"name": "...", "expires_in_days": 30} → 201 {secret, token}; 0 days: never
DELETE /api/tokens/<id>   → 204, revoked

Errors

Errors are JSON, with a code and a message for people:

json

{ "error": { "code": "not_found", "message": "Not found." } }

Services

http

GET    /api/services?period=24h                  → [{name, url, status, traffic, ...}]
POST   /api/services                             {"name": "..."} → a service with no deployment
GET    /api/services/<name>                      → status, deployment, bindings, usage, quota, process
PATCH  /api/services/<name>                      {"name": "...", "egress": [...], "disk_mb": 2048}: any of them
POST   /api/services/<name>/stop | /start
DELETE /api/services/<name>

Deployments

http

POST /api/services/<name>/deployments                  → 201, or 422 with the error
GET  /api/services/<name>/deployments                  → newest first, the last 10
POST /api/services/<name>/deployments/<id>/activate    → roll back or forward
GET  /api/services/<name>/deployments/<id>/source      → {main, files}
GET  /api/services/<name>/deployments/<id>/bundle      → the body that deploys it again

See Deploy.

Configuration

http

GET|PUT|DELETE /api/services/<name>/secrets[/<NAME>]
GET|PUT|DELETE /api/services/<name>/vars[/<NAME>]

See Vars and secrets.

Logs and metrics

http

GET /api/services/<name>/logs?limit=200
GET /api/services/<name>/logs?after=<id>&wait=30
GET /api/services/<name>/metrics?period=24h        → 1h, 24h, 7d or 30d

Data

http

POST           /api/services/<name>/db/<BINDING>/query
GET            /api/services/<name>/db/<BINDING>/tables
GET            /api/services/<name>/files/<BINDING>?prefix=
GET|PUT|DELETE /api/services/<name>/files/<BINDING>/file?key=<key>
GET            /api/services/<name>/jobs?status=dead
POST           /api/services/<name>/jobs
DELETE         /api/services/<name>/jobs/<id>
POST           /api/services/<name>/jobs/<id>/retry
POST           /api/services/<name>/crons/run
POST           /api/services/<name>/realtime/publish
GET            /api/services/<name>/storage
DELETE         /api/services/<name>/storage/<type>/<BINDING>
GET            /api/services/<name>/export
POST           /api/services/<name>/import

The runner

http

GET   /api/settings
PATCH /api/settings         → 202; the runner restarts in place
GET   /api/system           → version, workerd, started, services, processes, disk
GET   /api/system/logs      → the runner's own log, 5,000 lines
GET   /api/system/backup    → the whole instance as .tar.gz
POST  /api/system/restore   → 202; the runner restarts on the backup

See Runner settings and Backups.

PreviousBackups and upgrades NextLimits