# 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`](https://api.keel.run/openapi.json), generated from the server code
- **Interactive reference:** [`https://api.keel.run/docs`](https://api.keel.run/docs)

## Authentication

Send a token as a bearer token:

```bash
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](https://www.rfc-editor.org/rfc/rfc9457) problem details (`Content-Type: application/problem+json`) with a stable, machine-readable `code` and a `hint` that says what to do next:

```json
{
  "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](https://html.spec.whatwg.org/multipage/server-sent-events.html):

```bash
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](https://api.keel.run/openapi.json) has every field, every parameter and every error code.
