Get started

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.

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 admin can; 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.
  • 402 with code: billing_required or spend_limit_reached means the action costs money and the workspace has no active plan or reached its spend limit.
  • 422 (invalid) carries an errors list with the fields that failed validation.
  • 5xx responses never contain internals. Every response has an X-Request-Id header; 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.
  • 429 and 5xx answers 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: log with {"ts", "stream", "instance", "line"} for each line.
  • event: end when a finished deployment's log is complete.
  • A : ping comment 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), deployment and instance.
  • 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.

View as Markdown