API overview

The Keel dashboard and the CLI both use one HTTP API. This reference documents the endpoints as implemented in the application. There is no versioned public API yet, so paths and shapes can change between releases.

Base URL#

Every path starts with /api on your Keel origin:

https://keel.example.com/api

For local development this is http://localhost:3000/api. In the examples, $KEEL_URL is your origin and $KEEL_ACCESS_TOKEN is a CLI access token.

Authentication#

There are two ways to authenticate, and each endpoint accepts one or both:

Any request with a keel_ bearer token on an endpoint that does not accept CLI credentials gets 403 CLI credentials cannot be used for this operation. An invalid or expired CLI token gets 401 and never falls back to cookies.

There are no personal access tokens, API keys or service accounts. A CLI session is the only non-browser credential, and it is created by a person approving a device code. See Authentication endpoints.

Content types#

• Requests with a body must send Content-Type: application/json and a JSON object. Otherwise the API answers 415 or 400.
• Responses are JSON with Cache-Control: no-store.
• The one exception is a .env export, which is text/plain.

Response conventions#

• Successful responses wrap data in a named key, such as { "project": { ... } } or { "secrets": [ ... ] }.
• Actions without data return { "ok": true }.
• Timestamps are ISO 8601 strings in UTC.
• Errors use { "error": "message" }. See Error codes.
• Secret values appear only in the responses that are documented to return them. Lists contain metadata only.

Authorization model#

Project-scoped endpoints apply three checks in order:

1. Membership. You must be a member of the project. If not, the API answers 404 Project not found., the same as for an id that does not exist.
2. Permission. Your role must hold the required permission, or the API answers 403. See Projects and access control.
3. Environment access. For environment endpoints, owners and admins pass. Members and viewers need a grant, or the API answers 403 You do not have access to this environment.

All of this runs before any secret is read or decrypted.

Rate limits#

Limits are fixed windows of one minute, counted in server memory per instance. Exceeding one returns 429 with Too many requests. Try again in Ns.

Other endpoints are not rate limited by the application. Because counters are per instance, a multi-instance deployment multiplies these limits.

CORS#

No CORS headers are configured. The API is intended for same-origin use by the dashboard and for non-browser clients such as the CLI.

Endpoint index#

Next steps#

Start with Authentication endpoints.