API Conventions

Everything every endpoint shares, written once. Resource pages link here instead of repeating it.

Source of truth: src/lib/rate-limit.ts, lib/runtime.ts, lib/supabase/context.ts, proxy.ts, src/lib/approval-gate/index.ts, src/lib/telemetry/index.ts, src/lib/usage/meter.ts. When this page and the code disagree, the code wins — then fix this page.

0. The versioned surface: /api/v1 (added 2026-07-22)

Everything below documents the console surface (/api/* legacy routes) — human-triggered, {ok} envelopes, demo-tolerant. The programmatic surface is /api/v1/* and has its own, stricter contracts — full reference: resources/platform-api-v1.md (module + design record: src/lib/api/README.md, docs/discovery/2026-07-22-platform-api.md). The one-paragraph version:

• Errors are RFC 9457 application/problem+json with a machine code; success is the resource JSON directly (no {ok} wrapper). Wire DTOs live in src/lib/api/schemas.ts.
• Demo contract: credential-less keyless GETs serve labeled demo data ("mode": "demo" + x-p1-mode: demo header); any presented credential and every mutation → honest 503.
• Shared guard stack (IP limit → same-origin → body cap → auth → per-tenant limit); no CORS by design.
• Endpoints today: GET /api/v1/status | /approvals | /creatives | /videos | /performance | /positioning | /angles | /scripts | /landing-page | /brand; POST /api/v1/approvals/{id}/decision | /creatives/{id}/decision | /creatives/{id}/animate | /approvals/pause-request | /approvals/budget-request; PATCH /api/v1/angles/{id}.
• openapi.yaml covers v1 (the v1 tag); v1 paths are part of the definition of done for any v1 endpoint change, same as the console surface.

1. Base URL & transport

• All endpoints are same-origin routes of the Next.js app (/api/*, plus a few page-level routes documented in public-pages and auth).
• JSON in / JSON out unless a page says otherwise. Public form endpoints (/api/leads, /api/interest, /api/bookings, /api/auth/login) also accept form posts (application/x-www-form-urlencoded / multipart/form-data); anything that isn't application/json is parsed as form data. /api/onboarding is JSON-only — it calls req.json() with no form fallback, so a form-encoded body is silently read as empty and answers 400 (it was previously listed here in error).
• Only /api/bookings sends CORS headers (its form lives on published client pages that may sit on another origin). Every other route is same-origin.
• Every response carries the security headers set in next.config.mjs (issue #114): HSTS, Content-Security-Policy: frame-ancestors 'self'; object-src 'none'; base-uri 'self', X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy (camera/mic/geolocation/topics off); X-Powered-By is removed. None of these change request semantics — listed so header-diffing clients aren't surprised.

2. Operating modes: demo vs live

The platform runs in one of two modes, decided per capability by environment variables (lib/runtime.ts):

The pattern (uniform across ~15 routes): live logic sits behind a guarded dynamic import; if the predicate is false (keyless), the route serves a deterministic demo response of the same JSON shape, tagged "mode": "demo". Flipping to live is a config change, not an API change.

What this means for callers:

• Always check for "mode": "demo" on success responses. In demo mode nothing was persisted, no email was sent, no model was called.
• Live failures are never masked (updated 2026-07-22, "API slice 0"): when the platform is configured and the live handler throws, EVERY route answers an honest 500 { "ok": false, "error": ... } — including the acknowledgment paths (leads, interest, bookings, brand-assets, approvals) that previously fell back to a demo-success ack. Demo responses now mean exactly one thing: the platform is keyless. Decision paths additionally fail closed on input (approvals reject anything but a literal "approve"/"reject"; /api/cron with no CRON_SECRET authorizes nobody).

3. Authentication

Three tiers. Each resource page states which one applies.

Notes:

• Session cookies (sb-*) are set HttpOnly; SameSite=Lax, plus Secure in production (WSTG-SESS-02) — uniformly across login, server components, and the middleware refresh.
• Session verification is memoized per request (one JWKS verify per navigation), and the JWKS itself is fetched once per process (or read from the SUPABASE_JWKS env var when set).
• proxy.ts (Next's middleware convention) only runs on session-bearing surfaces — public APIs and marketing pages are deliberately excluded so the CDN can serve them without a function invocation.

4. Rate limiting

checkRateLimit(key, {limit, windowMs}) — sliding window, keyed "<route>:<clientIp>" where the client IP comes from x-nf-client-connection-ip (Netlify), else the first x-forwarded-for hop, else "unknown".

Over the limit → 429 with header retry-after: 60 and body:

{ "ok": false, "error": "Too many requests — give it a minute and try again." }

Current rules (per client IP unless noted):

Honest scope: the limiter is per-process memory. On serverless, each warm instance counts separately — treat it as abuse friction, not a security boundary. Real protections are validation, RLS, HMAC tokens, and anti-enumeration.

5. Body-size limits

Routes that parse bodies call enforceBodyLimit(req, maxBytes) before reading the body:

• Missing/unparseable Content-Length → 411 { "ok": false, "error": "A Content-Length header is required." } (chunked transfer would bypass a header check, so a measurable length is required — always send Content-Length).
• Content-Length over the cap → 413 { "ok": false, "error": "Request body too large." }

Caps: 1 MB default (conductor, leads, interest, videos, bookings, approvals, creatives, bookings/mark); 6 MB where base64 files ride in the body (media, onboarding, brand-assets).

6. Error & response envelopes

The dominant convention is { "ok": boolean, ... }:

Known exceptions (documented on their pages): /api/conductor uses { reply, mode } / { error } without ok; /api/auth/login answers with 303 redirects, never JSON; /api/cron returns plain text on auth failure.

7. The approval gate (why mutations feel indirect)

Real-world actions (publish, launch, budget, account creation, brand/positioning/angle activation) never happen directly from a request. The flow:

1. An agent calls createApproval(...) → a pending approvals row with a plain-language summary and a payload_hash (SHA-256 over key-sorted JSON).
2. The client decides via POST /api/approvals. An approval past its expiry window is rejected at decision time (WSTG-BUSL-01): the row flips to expired and no token is minted — expiry is not deferred to consume time.
3. On approve, the server mints a one-time capability token (32 random bytes; only its HMAC is stored — secret APPROVAL_TOKEN_SECRET, server-held). The token never reaches the browser.
4. The executing agent calls verifyAndConsume(...), which checks — in order — existence, instance, status, expiry (7-day default), token HMAC, payload hash, and action type before atomically consuming. What was approved is exactly what runs; it cannot quietly become something else.

Failure vocabulary (reason strings): approval not found, instance mismatch, status is <s>, expired, bad token, payload mismatch, action mismatch: …, already consumed.

8. Telemetry & metering (what gets logged about your calls)

• Features only, never content: telemetry rows carry booleans/counts/enum labels — no message text, no creative copy, no emails. See src/lib/telemetry/index.ts header for the rule.
• LLM calls record llm_usage events ({task, model, token counts} only) via AsyncLocalStorage context — the source of truth for the 1.5× billable preview in getUsageSummary.
• A per-instance rolling-24h token budget (LLM_DAILY_TOKEN_BUDGET, off unless set) can park generation; the pipeline keeps observing but won't call the model until the window clears.

9. Environment variables (complete list)

Video generation is a distinct backend with its own provider integration — see video-generation-provider.md for the full Gemini/Veo contract, lifecycle, and VERIFY-AT-LIVE caveats.

(requireSecret floor: secrets must be ≥16 chars and not match placeholder patterns — deploys with changeme fail loudly.)

10. Idempotency cheat-sheet