API conventions

The cross-cutting rules, in one table. The per-endpoint truth is the OpenAPI spec.

Concern	Rule
Base URL	https://api.quietdesk.dev/v1
Auth	Authorization: Bearer qd_live_… — token acts as its creator, in one org
Content type	application/json both ways; UTF-8
IDs	Prefixed strings (snp_, crd_, …) — see the Glossary. Treat as opaque
Human refs	Cards/milestones also accept their ref (PS-117, SP-14) wherever an id is expected
Timestamps	RFC 3339 UTC (2026-06-10T09:14:02Z); date-only fields are YYYY-MM-DD in the org timezone
Pagination	cursor + limit (≤100); next_cursor absent on the last page
Idempotency	Idempotency-Key on writes; 24 h window; key+body mismatch ⇒ 409
Rate limits	Per token; 429 + Retry-After. Default 1,000 req/min
Errors	One envelope: code, http_status, user_message, request_id
Org scoping	Implicit from the token. Objects outside your org 404 (never 403) — existence is not leaked
Gated moves	Agent callers get 403 gated_move_requires_human; the attempt is audited
Versioning	Snippets version on every save; other objects carry updated_at
Audit	Every write produces an evt_… with actor, door (ui·cli·mcp·http), and agent attribution
Deprecation	Beta: breaking changes announced in Availability ≥14 days ahead
OpenAPI	/docs/openapi.yaml — also feeds this site's operation pages and the LLM corpus