API conventions

Every JSON response — success or failure — is:

Read this before adding or changing a /v1 route. These are the rules the Headless CRM epics (HL-A/B/C) build on. They are enforced where a test can enforce them; the rest is review. converged the surface onto them.

1. One envelope

Every JSON response — success or failure — is:

{ "success": true,  "data": { … }, "meta": { "request_id": "uuid", "timestamp": "ISO 8601" } }
{ "success": false, "error": { "code": "…", "message": "…", "details": … }, "meta": { … } }

• Build it with apiSuccess / apiError from _shared/response.ts. Never hand-roll a Response for JSON.
• meta.request_id is also the X-Request-Id header. Both are always present.
• Named payloads, not bare arrays: data.leads, data.subscriptions, data.record. A bare array cannot grow a sibling field (like next_cursor) later without breaking.
• The one exception: POST /v1/check-email also carries a top-level exists beside the envelope, for a server-side caller coded against the pre-envelope body. It is marked deprecated in the spec; new callers read data.exists. Do not add a second exception.

2. Errors

error.code is the contract — branch on it, never on message. The catalogue is ErrorCodes in _shared/errors.ts, mirrored by the ErrorCode enum in the spec and locked by error-catalogue.test.ts. Full list and meanings: errors.md.

Situation	Status	Code
Bad input, bad cursor, unknown field	400	VALIDATION_ERROR
No / invalid credential	401	AUTH_INVALID_KEY (or MISSING_API_KEY)
Credential lacks the scope	403	FORBIDDEN_SCOPE
Not this tenant’s, or does not exist — same answer	404	NOT_FOUND
Duplicate / state conflict	409	CONFLICT / ALREADY_EXISTS
Rate limited	429	RATE_LIMIT_EXCEEDED
Over monthly quota / no subscription	429 / 402	QUOTA_EXCEEDED
Anything we cannot explain	500	INTERNAL_ERROR (message is generic)

A cross-tenant id is a 404, never a 403: a distinct answer confirms the id exists.

3. Pagination

Cursor pagination, everywhere. Every list endpoint accepts the same two query parameters and returns the same two fields next to its named array:

GET /v1/webhooks?limit=25&cursor=eyJ0Ijoi…
→ { "success": true, "data": { "subscriptions": [ … ], "next_cursor": "eyJ0Ijoi…", "has_more": true } }

limit	1–100, clamped not rejected. Default 25; 100 on lists that were unbounded before (notes, tasks, record activities, webhooks); 50 on webhook deliveries.
cursor	Opaque. Echo next_cursor back verbatim. A cursor that does not decode is 400 VALIDATION_ERROR, never an empty page.
next_cursor	null on the last page — the only stop signal a client needs.
has_more	true when next_cursor is non-null.

Why keyset and not offset: with OFFSET n, one insert between two pages repeats a row and one delete skips one — silently, in a sync integration. A cursor anchors on a row, not a position. The sort is total, (timestamp, id) DESC, so a page boundary between two same-second rows can neither repeat nor skip. Design notes are in _shared/cursor.ts; the shared reader is _shared/pagination.ts (resolvePage).

Implementing a new list: resolvePage(query) → .or(keysetFilter(position)) when a cursor was sent → order by the timestamp then id, both descending → .limit(limit + 1) → buildPage / buildPageBy. Lists assembled from more than one table page in memory with pageInMemory, same semantics.

The deprecated offset path

GET /v1/activities shipped with limit/offset and a pagination.total. Both still work (additive-only), and the response now also carries next_cursor / has_more. A request that sends offset gets the headers:

Deprecation: Fri, 04 Sep 2026 00:00:00 GMT
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Link: <…/docs/api/conventions.md#pagination>; rel="deprecation"; type="text/html"

Migrate by dropping offset and passing next_cursor as cursor. Nothing else in v1 paginates by offset; do not add anything that does.

4. Idempotency

POSTs that create take an Idempotency-Key header (8–255 chars). Same key + same body replays the original response with Idempotent-Replay: true; same key + different body is 422 IDEMPOTENCY_CONFLICT. Keys are scoped to the company and the endpoint and expire after 24 h. Use idempotencyGuard(required) on the route. Detail: idempotency.md.

5. Naming and shape

• Paths: plural nouns, kebab-case (/v1/activity-types, /v1/webhook-events); sub-resources nest under their parent id; non-CRUD actions are a trailing verb (/rotate-secret, /replay, /test) or a colon suffix (/records:batch).
• Fields: snake_case. Timestamps are ISO 8601 UTC strings; money is minor units (price_monthly_minor); nullable fields are type: [T, "null"] in the spec.
• Every operation has tags (declared at the top of the spec) and a camelCase operationId (listWebhooks, createApiKey) — the SDK turns it into a method name, so renaming one is a breaking change.
• Read-only lookups are GET with query parameters; anything that changes state is POST/PATCH/DELETE. PATCH is a partial update; there is no PUT.

6. Auth and tenancy

• Routes own HTTP only. Data access goes through _shared/services/* on the tenant client (createTenantClient(ctx)); route-layering.test.ts fails a route that imports the admin client or calls .from().
• Scope-gate with scopeGuard/entitlementGuard (or inside the service where the 403/404 distinction matters). Public (credential-less) routes set security: [] in the spec and are mounted before authMiddleware.

7. Versioning

Additive only within /v1: add fields and endpoints; never remove, rename, retype, or make optional things required. Deprecate with deprecationHeaders() and a ≥ 12-month sunset — versioning-policy.md.

Checklist for a new endpoint

1. Spec entry first (docs/api/openapi.yaml): tags, operationId, params via #/components/parameters/PageLimit / PageCursor if it lists, envelope response, shared error responses. npm run docs:api:lint.
2. Service function on the tenant client; pure decision logic in a Deno-free module with a vitest test.
3. Route: validate, call the service, apiSuccess/toApiError. Nothing else.
4. npm run contract:test — spec ↔ routes, schema drift, error catalogue.
5. Copy the spec to public/openapi.yaml; bump sdk-gen if endpoints were added.