API reference

Base URL (local): http://localhost:8080. All requests and responses are JSON. The pages below this one are generated from openapi-v1.yaml by npm run gen:api (see how this stays in sync) — this page is the only hand-written one in the section.

Authentication

Send Authorization: Bearer <token> — an API key (sk_...) or, for browser-facing endpoints, a widget JWT. See Authentication.

Error envelope

Every error looks like:

{ "error": { "code": "string", "message": "human readable" } }

code is an open string set. Quota errors (402) also carry limit, plan, and upgrade_url. Internal errors return a generic message with a correlation ref — details are logged server-side, never returned.

Conventions

• Idempotency — send an Idempotency-Key header on creates to make retries safe (accepted; honored where supported).
• Pagination — list endpoints accept limit; results are tenant-scoped.
• Versioning — the surface is under /v1. Additive-only within a version — see the changelog.

Keeping this in sync

app/openapi-v1.yaml is the single source of truth for the wire contract — docs, SDKs, and request validation all derive from it. This section is regenerated with:

cd app/web
npm run gen:api

CI (.github/workflows/docs.yml) lints the spec, regenerates this section, and fails the build if the committed pages have drifted from the spec (git diff --exit-code) — so an endpoint change without a regeneration can't merge silently out of date.