HTTP API

The dashboard, the CLI and the MCP server are three clients of one HTTP API. Nothing else reaches the database. Every endpoint is described once in packages/api-contracts (endpoints registry: method, path template, params, query, body, response, success status, auth mode and required permission), the NestJS controllers are decorated from those entries, apps/api/test/openapi-contracts.spec.ts fails when the OpenAPI document and the registry disagree in either direction, and packages/api-client is generated from the same registry. Add an endpoint by adding a registry entry; the controller, the drift test and the client follow.

OpenAPI is served at /openapi.json and Swagger UI at /docs outside production.

Authentication

Every request outside /health, /hooks and /v1/public carries Authorization: Bearer <token>.

API key scopes and the permissions they grant:

Roles map to permissions as follows: owner has everything; admin has everything except org.manage and billing.manage; member has agents.*, runs.*, secrets.*, sites.*, builds.write, callbacks.manage, data_stores.read and data_stores.write; viewer has agents.read, runs.read, sites.read, secrets.read_names and data_stores.read. data_stores.connect (revealing a connection URL) and secrets.reveal (exporting an agent's environment with its secret values) belong to owners and admins only and no API key scope grants them.

No scope grants org.manage, members.manage, billing.manage or api_keys.manage: keys cannot manage the organization, its members, its signing secrets or other keys. Those stay with signed-in owners and admins.

Clients discover the identity provider without configuration: GET /v1/auth/config is public and answers { issuer, projectId, cliClientId, dashboardClientId, mcpClientId } from AUTH_ISSUER_URL, AUTH_AUDIENCE and the AUTH_*_CLIENT_ID variables (a client id is null until its variable is set).

Organization context

Organization scoped routes need a tenant. Keel-Organization: <organization id or slug> selects it. A user who belongs to exactly one organization can omit the header; one who belongs to several gets 400 organization_required with the candidates. API keys ignore the header unless it names their own organization. GET /v1/organizations and POST /v1/organizations work without a tenant.

Conventions

• JSON in and out. Dates are ISO 8601 strings in UTC.
• Path ids are UUIDs; Keel-Organization also accepts the slug.
• Every response carries x-request-id; send your own ([A-Za-z0-9._:-]{1,128}) to correlate.
• Bodies are validated with the contract schemas; a mismatch is 400 validation_failed with errors: [{ path, message }].
• Request bodies are limited to 1 MiB (413 body_too_large).

Pagination

List endpoints take limit (default 20, max 100; steps default 100, max 500; audit log default 50, max 200) and cursor, and answer { items, nextCursor }. nextCursor is opaque; pass it back as cursor until it is null. A cursor that was not produced by Keel answers 400 invalid_cursor. The client's paginate(client.runs.list, { query }) async iterator does this for you.

Problems

Errors are application/problem+json (RFC 9457):

{
  "type": "urn:keel:problem:callbacks_not_in_plan",
  "title": "Feature not in plan",
  "status": 409,
  "detail": "the current plan does not include outbound callbacks",
  "instance": "/v1/agents/8f3a.../runs",
  "requestId": "3b1c..."
}

type is urn:keel:problem:<kind> for every mapped error and about:blank otherwise. Extra fields carry the error's details (for example organizations on organization_required, limit on agent_limit_reached). Kinds you will meet:

Endpoints

Permission membership means any member of the organization (or any API key of it). Public routes take no token.

Health and auth discovery

Organizations, members, usage, signing secrets

Billing

Self-serve billing for card organizations (Billing). Owners only: no API key scope grants billing.manage.

API keys and audit log

Every successful mutating request (POST, PUT, PATCH, DELETE) inside an organization writes one audit entry: actor (user id or apikey:<id>), action (METHOD /path/template), target (the created or addressed resource id) and metadata (principal, requestId, path, params). Failed requests are not recorded. The MCP server writes through the same AuditWriter, and records its read tools through POST /v1/audit-log/events.

Agents and revisions

Services and ingress

An agent in service mode is kept up by the platform: start creates a run with triggerSource: service, ceilingSeconds: 0 and deadlineAt: null (it runs until the service stops, so no deadline is ever computed for it), a crash ends that run and the platform starts the next one, and the hours a replica is up are billed per replica-month at the price of the agent's serviceKind (see services on the usage endpoint and Billing). A ServiceStatus is { agentId, state, currentRunId, restarts, lastExitCode, lastExitAt, nextRestartAt, upSince, updatedAt } with state one of stopped, starting, up, restarting, crash_looping, stopping.

The API keeps every service and ingress call behind two ports (apps/api/src/services/ports.ts: ServicesPort, IngressPort) that the composition root binds to the application's service and ingress use cases; an environment without them answers 501 not_configured for writes and empty statuses for reads.

Custom domains

A custom domain (Custom domains) is { id, hostname, target: { kind: "service", agentId } | { kind: "site", siteId }, status, platformHostname, dnsRecords, lastCheckedAt, lastError, verifiedAt, nextCheckAt, createdAt, updatedAt }. status is pending_verification, verifying, active or failed; dnsRecords lists { type, name, value, purpose } with purpose ownership (the TXT record), routing (the CNAME) or routing_apex (A/AAAA alternatives from INGRESS_PUBLIC_ADDRESSES). Hostnames are lower-cased and IDNA-encoded on input; wildcards, IP literals, single labels and anything under the platform domain are refused.

Without INGRESS_PUBLIC_DOMAIN every domain endpoint answers 501 not_configured.

Static sites

Serving, storage and the CLI are described in Static sites.

Runs

Triggers and inbound webhooks

Public marketing forms

Three endpoints exist for the marketing site (apps/web, keelhosting.dev) so that a lead lands on our own Frankfurt host rather than in a third-party database. The site posts only to POST /v1/public/sales-inquiries; the waitlist and enterprise routes stay for the rows already collected under them. They are unauthenticated and rate limited, and they are the only unauthenticated writes on the API besides the Stripe webhook and the ingest routes.

Both bodies are strict: an unknown field is 400 validation_failed, and no error ever echoes a submitted value. The route cap is 32 KiB (413 body_too_large) on top of the 1 MiB global limit. Rate limits are a token bucket on the client address (LEAD_RATE_LIMIT_PER_IP, default 5 per 10 minutes) and one on the email address (LEAD_RATE_LIMIT_PER_EMAIL, default 3 per hour), each answering 429 rate_limited with Retry-After in problem+json. The client address is request.ip, which fastify reads from the X-Forwarded-For header Caddy sets in front of the API, the same header the ingress relay forwards.

Rows go to the platform tables sales_inquiries, waitlist_signups and enterprise_inquiries, which carry no organization id and no row level security and are reachable only through the keel_platform role. No audit entry is written, because a public submission has no actor; each accepted submission writes one structured log line instead. the operations notes has the SQL to read them.

Builds and images

Builds that nobody polls are picked up by the in-process build poller (REAPER=inprocess) or, in production, by the worker.

Secrets

Secrets live in the organization's tenant secret store. Locally SECRET_VAULT=file keeps them under SECRET_VAULT_ROOT and creates the store on first use. Without a store the answer is 409 secrets_not_provisioned. Names containing / are reserved for the platform (webhook secrets, per-agent environment secrets under agent/<agentId>/<NAME>) and never listed.

Per-agent environment variables

Precedence, restart semantics and the dotenv grammar are in Environment and secrets.

Data stores

See Databases. GET /v1/organizations/me/usage carries dataStores.postgres and dataStores.valkey with hours, active, projectedCents and pricePerMonthCents.

Ingest

/ingest/v1/attempts/{attemptId}/... routes are for the supervisor and authenticate with the run token; they are documented in the local development notes. /ingest/v1/blobs/{token} serves the local payload store and is not part of the public contract.

POST /ingest/v1/attempts/{attemptId}/heartbeat accepts an optional workspaceBytes (the bytes used under the workspace mount) which is recorded for the service that owns the run and shown as workspace.bytes on GET /v1/agents/{id}/service, and an optional ready: boolean (readiness on the heartbeat contract): the supervisor's verdict from the health check or the ingress port probe. It is stored per attempt (run_attempts.ready_at is set when the replica becomes ready and cleared when it stops being ready, last_ready_at remembers that it was ready once) and drives the rollout, the replica list and service_status.readyReplicas. A heartbeat without ready counts as ready while the agent container runs, so older supervisors keep working.

POST /ingest/v1/attempts/{attemptId}/logs takes { lines: [{ ts, stream: stdout | stderr, line }] }, at most 500 lines, 8 KB per line and 1 MB of text per batch, already redacted by the supervisor. Each batch becomes one gzip chunk runs/{org}/{run}/attempts/{n}/logs/{sequence}.ndjson.gz in the payload store plus a run_log_chunks row (organization, run, attempt, sequence, object key, bytes, line count, first and last timestamp). The same transaction also indexes every line of the batch into the log_lines hot table that backs search and the tail for seven days (Logs). The answer is { sequence, totalBytes, limitReached }; past 50 MB per attempt the platform answers limitReached: true and stores nothing more. Batches are only accepted while the run is running (409 run_not_active otherwise).

Run logs

GET /v1/runs/{id}/logs answers { attemptNumber, lines, lastChunk, nextAfterChunk, active }. Lines are { ts, stream, line } in the order the supervisor shipped them (per stream the order is the container's; across stdout and stderr it is the capture order, which is what docker logs gives too). The cursor is the chunk sequence: pass afterChunk=<lastChunk> (or nextAfterChunk) to continue, attempt= to read an earlier attempt (404 run_attempt_not_found for an unknown one), and limit= (default 2000, max 10000) for the number of lines per page; a page always carries whole chunks, at least one, and at most 5 MB of text decompressed server side. active is true while the run is still running its latest attempt, so a client that reaches nextAfterChunk: null with active: true should keep polling or switch to the event stream. A queued run without an attempt answers attemptNumber: null and no lines.

With any of q, from, to, levels, replica, stream or cursor the endpoint searches the run's lines in the 7 day hot table instead (Logs for the semantics): attempt still selects the attempt (404 for an unknown one) and the answer keeps the shape above with lastChunk: 0 and nextAfterChunk: null, lines newest first carrying id, level and replicaIndex, plus nextCursor (pass it back as cursor=) and retainedFrom; limit is capped at 500. Clients that never send a filter see no change.

Run events (SSE)

GET /v1/runs/{id}/events answers text/event-stream and polls the database every RUN_EVENTS_POLL_INTERVAL_MS (default 2000) until the run is terminal. This is what keel run --follow and the dashboard live view use.

event: status
id: status:running:1
data: {"event":"status","run":{...}}

event: step
id: 3
data: {"event":"step","step":{...}}

event: end
id: end:succeeded
data: {"event":"end","run":{...}}

• status fires once per status change (including the first snapshot), step once per new step in sequence order, log with { attemptNumber, chunk, lines } for every batch of new container log chunks while the run is active (at most 2000 lines or 1 MB per event), end once with the terminal run, after which the server closes the stream.
• When the run belongs to a service (triggerSource: service) the stream also carries service events with { event: "service", service: ServiceStatus } whenever the service state, restart count or current run changes (event id service:<state>:<updatedAt ms>). A crash ends the run (end with failed) after a service event with state: restarting; read GET /v1/agents/{id}/service for the next currentRunId and open its stream to keep following.
• Step event ids are the step sequence, log event ids are log:<chunk>. Reconnect with Last-Event-ID: <sequence> or Last-Event-ID: log:<chunk> (or ?afterSequence= and ?afterLogChunk=) to resume without replaying; status is always resent. ?logs=false leaves the log events out.
• Each poll reads only the steps above the last sequence it sent (the repository's afterSequence), so the cost of a poll is bounded by the new steps, not the trace length.
• A : keepalive comment is written every RUN_EVENTS_KEEPALIVE_MS (default 15 s) so idle proxies do not drop the connection.
• Every RUN_EVENTS_ACCESS_RECHECK_MS (default 60 s) the server checks that the caller still has runs.read in the organization (membership still present with a role that allows it, or the API key still active). If not, it sends event: access_revoked with {"event":"access_revoked"} and closes the stream; a revoked member or key stops receiving data within a minute instead of at reconnect.
• At most RUN_EVENT_STREAMS_PER_ORGANIZATION (default 20) streams may be open per organization; the next one answers 429 too_many_streams with limit.
• The client exposes it as for await (const event of client.runs.events({ params: { id } })).

Client

@keel/api-client (packages/api-client) is generated from the registry at build time (pnpm --filter @keel/api-client generate; the test suite fails when the committed output is stale).

import { createKeelClient, KeelApiError, paginate } from "@keel/api-client";

const client = createKeelClient({ baseUrl: "https://api.keel.dev", auth: { apiKey: process.env.KEEL_API_KEY }, organization: "acme" });

const agent = await client.agents.create({ body: { name: "Nightly digest" } });
const run = await client.agents.trigger({ params: { id: agent.id }, body: { payload: { date: "2026-09-16" } } });

const detail = await client.runs.get({ params: { id: run.id } });
console.log(detail.usage?.weightedMinutes ?? "not metered yet", detail.resumable);

const tail = await client.runs.listSteps({ params: { id: run.id }, query: { order: "desc", limit: 50 } });
const step = await client.runs.getStep({ params: { id: run.id, sequence: tail.items[0]?.sequence ?? 1 } });
console.log(step.inputPayload === "expired" ? "input payload expired" : (step.payloads.input?.url ?? "no input payload"));

const plan = await client.organizations.plan();
console.log(plan.limits.maxMemoryMb, plan.verifiedEndpointListVersion);

await client.auditLog.record({ body: { source: "cli", action: "runs inspect", target: run.id } });

for await (const event of client.runs.events({ params: { id: run.id } })) {
  console.log(event.event, event.data);
}

for await (const item of paginate(client.runs.list, { query: { agentId: agent.id, limit: 50 } })) {
  console.log(item.id, item.status);
}

try {
  await client.agents.get({ params: { id: "missing" } });
} catch (error) {
  if (error instanceof KeelApiError && error.is("agent_not_found")) {
    console.log(error.status, error.requestId);
  }
}

Every method takes { params, query, body } as the registry declares and an optional { signal, headers, organization }; auth is { bearer } for Zitadel tokens or { apiKey }; fetch is injectable for tests; responses are validated against the contract unless validateResponses: false. JSON requests abort after timeoutMs (default 30 seconds, defaultRequestTimeoutMs) with a TimeoutError; a caller's signal is combined with the timeout so either ends the request. Event streams have no default timeout, only the caller's signal.