API
Everything in keel.run is available through a REST API with JSON. The dashboard, the CLI and the MCP server use the same public API, so anything you can do there, you can do with the API.
- Base URL:
https://api.keel.run/v1 - OpenAPI 3.1 document:
https://api.keel.run/openapi.json, generated from the server code - Interactive reference:
https://api.keel.run/docs
Authentication
Send a token as a bearer token:
curl https://api.keel.run/v1/me -H "Authorization: Bearer $KEEL_TOKEN"
| Token | Prefix | For | Created |
|---|---|---|---|
| Personal | keel_pat_… |
you, in the CLI and scripts | by keel login, or in the dashboard |
| Service | keel_svc_… |
CI pipelines | in the dashboard or with keel tokens create --kind svc |
| Agent | keel_agent_… |
coding agents (MCP) | by the MCP OAuth flow, or in the dashboard; always expire |
- A token belongs to one workspace and can be limited to some projects.
- A token never has more rights than the person who created it, and it ends when that person loses access to the workspace.
- Agent and service tokens cannot create other tokens. A personal token with
admincan; the new token expires no later than its parent and is revoked with it. - Tokens are stored only as hashes. A new token is shown once.
Revoke a token in the dashboard (Settings → Tokens), with keel tokens revoke, or with POST /v1/oauth/revoke.
Scopes
| Scope | Allows |
|---|---|
read |
read projects, services, deployments and settings |
logs:read |
build and runtime logs |
deploy |
deploy, roll back, restart |
config:write |
change configuration and variables, reveal secret values, start runs and (with logs:read) read their output |
databases:read |
databases and their connection URLs (with password) |
databases:write |
create and change databases |
databases:query |
read-only SQL |
domains:write |
add and remove domains |
dns:write |
keel DNS: create and change zones and records (deleting a zone needs admin) |
billing:read |
billing and usage |
admin |
everything, including deletion and token management |
Members of a workspace (role member) cannot grant admin or billing:read.
Errors
Errors are RFC 9457 problem details (Content-Type: application/problem+json) with a stable, machine-readable code and a hint that says what to do next:
{
"title": "Forbidden",
"status": 403,
"code": "missing_scope",
"detail": "Redeploying needs the deploy scope.",
"hint": "Send redeploy=false or use a token with deploy."
}
- Unknown and forbidden resources both answer
404, so a token cannot probe what exists in other workspaces. 402withcode: billing_requiredorspend_limit_reachedmeans the action costs money and the workspace has no active plan or reached its spend limit.422(invalid) carries anerrorslist with the fields that failed validation.5xxresponses never contain internals. Every response has anX-Request-Idheader; include it when you contact support.
Idempotency
Send an Idempotency-Key header (up to 200 characters, e.g. a UUID) with every POST. If you repeat the request with the same key – after a timeout, say – the API returns the first response instead of doing the work twice, with the header Idempotent-Replayed: true.
- The same key with a different body or path answers
422 idempotency_mismatch. - Responses that contained a secret (a new token) are never stored. Repeating such a request answers
409 idempotency_replay_unavailable: list the resource to see what the first request created. 429and5xxanswers are not stored, so retry them with the same key.
The CLI sends idempotency keys and retries network errors, 429 and 502–504 automatically.
Pagination
Lists that can grow (deployments, audit log) are sorted newest first and take limit and before: pass the ID of the oldest item you have as before to get the next page. A page shorter than limit is the last one. (The MCP tools wrap this as cursor and next_cursor.)
Streams
Logs are Server-Sent Events:
curl -N "https://api.keel.run/v1/services/svc_…/logs?since=1h&follow=true" -H "Authorization: Bearer $KEEL_TOKEN"
curl -N "https://api.keel.run/v1/deployments/dpl_…/logs?follow=true" -H "Authorization: Bearer $KEEL_TOKEN"
event: logwith{"ts", "stream", "instance", "line"}for each line.event: endwhen a finished deployment's log is complete.- A
: pingcomment every 15 seconds keeps proxies from closing the connection. - Runtime logs take
since(e.g.10m,1h,2d; at most 7 days),tail(lines per instance, at most 1000),deploymentandinstance. - Streams end after 30 minutes; reconnect if you need more. At most 5 streams per token at a time.
Rate limits
Reads are limited per token (20 per second, bursts up to 200); writes have a stricter limit. Over the limit, the API answers 429 with code: rate_limited; wait and retry.
Main resources
| Resource | Endpoints |
|---|---|
| Me, workspaces | GET /v1/me, GET/PATCH /v1/workspaces/{id}, GET /v1/workspaces/{id}/audit |
| Projects | GET/POST /v1/workspaces/{id}/projects, GET/PATCH/DELETE /v1/projects/{id} |
| Environments | GET/POST /v1/projects/{id}/environments, GET/DELETE /v1/environments/{id} |
| Services | GET/POST /v1/environments/{id}/services, GET/PATCH/DELETE /v1/services/{id}, GET /v1/services/{id}/status, GET /v1/services/{id}/metrics, POST /v1/services/{id}/restart |
| Deployments | GET/POST /v1/services/{id}/deployments, GET /v1/deployments/{id}, POST /v1/deployments/{id}/rollback |
| Variables | GET/PATCH /v1/environments/{id}/variables (service_id for a service's own) |
| Databases | GET/POST /v1/environments/{id}/databases, GET/PATCH/DELETE /v1/databases/{id}, GET /v1/databases/{id}/credentials, POST /v1/databases/{id}/link, POST /v1/databases/{id}/rotate-password, POST /v1/databases/{id}/query, GET /v1/databases/{id}/backups, POST /v1/databases/{id}/restore |
| Domains | GET/POST /v1/services/{id}/domains, GET/DELETE /v1/domains/{id}, POST /v1/domains/{id}/verify |
| Tokens | GET/POST /v1/workspaces/{id}/tokens, DELETE /v1/workspaces/{id}/tokens/{token_id} |
| Billing | GET /v1/workspaces/{id}/billing, GET /v1/workspaces/{id}/usage, PUT /v1/workspaces/{id}/billing/spend-limit |
The OpenAPI document has every field, every parameter and every error code.