API reference

The public /api/v1 REST surface — bearer auth, scopes, rate limits, and one error envelope.

The starter ships a small public REST API at /api/v1, meant for machine integrations that authenticate with a bearer API key rather than a user session. Each endpoint page below is generated from a hand-authored OpenAPI 3.1 document (apps/docs/openapi.json); a coverage test pins that document to the real route tree, so the reference cannot silently drift from the code.

GET /api/v1/me

Resolve the authenticated key and its owning organization.

GET /api/v1/organization

Read the authenticated organization's general settings.

Authentication

Every request must carry an API key as a bearer token:

GET /api/v1/me HTTP/1.1
Authorization: Bearer sk_live_...

Keys are minted in Account settings → API keys; the full secret is shown once, at creation. The scheme match is case-insensitive, but the token is taken verbatim. A missing, malformed, unknown, revoked, or expired key is rejected with one indistinguishable 401 — a probe cannot tell those cases apart.

Scopes

A key is granted the coarse read or write scope (v1). write implies read, so a write key satisfies a read requirement. Both endpoints here require read; a key without it gets a 403.

Rate limiting

Requests are counted per key against a per-minute limit. A capped key's responses (both the served response and a 429) carry:

Header	Meaning
`X-RateLimit-Limit`	The per-minute ceiling.
`X-RateLimit-Remaining`	Requests left in the window.
`X-RateLimit-Reset`	Whole seconds until the window resets.
`Retry-After`	Sent only on a `429`: seconds to wait.

An uncapped key carries none of these headers. Over the limit, the request short-circuits with a 429 before the handler runs.

Errors

Every failure serializes to one envelope:

{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key." } }

Status	`code`	When
`401`	`UNAUTHORIZED`	Missing / invalid / revoked / expired key.
`403`	`FORBIDDEN`	Key lacks the required scope.
`404`	`NOT_FOUND`	The requested resource does not exist.
`429`	`RATE_LIMITED`	Per-minute limit exceeded.
`500`	`INTERNAL`	Unexpected server fault (opaque; correlate via `X-Request-Id`).

Request correlation

Every response echoes an X-Request-Id header (an inbound x-request-id is honored, otherwise one is generated). Include it when reporting an issue so the request can be traced in the logs.