Implemented API reference

Release 0.3. This inventory is generated from server route declarations. It describes 365 implemented method/path declarations, not the larger production target. The report format parameter accepts preview or download. Unknown API routes return a structured 404 from the running server.

Transport and authentication

The browser and API share one origin (localhost or the production Vercel URL). API sessions use the HttpOnly dg_session cookie. Sign-in/register/enrollment return a session-bound CSRF token; authenticated changes require X-CSRF-Token. Commands also require a unique Idempotency-Key of at most 128 characters. Reusing a key with identical actor/path/content returns the saved result; changed content conflicts. Invitation bearer URLs are redacted from saved receipts.

Authentication and invitation entry points have a production-default limit of 40 requests per 15 minutes per IP. Hosted limits use a PostgreSQL counter shared by function instances; local limits are per process. Provider-key settings share this limiter. Business routes enforce the server actor and tenant context; no request may select a different tenant or role. Advisor routes manage companies within that tenant. Participant routes and assets enforce the assigned person/company/request.

Use expectedVersion for record edits/actions and case progress. Reports/framework saves and graph rebuild use expectedRevision for the company snapshot. Review current data after a 409; do not blindly retry old content with a new key.

Implemented routes

Record payloads

POST records accepts a closed object with kind and data. PATCH records/{recordId} accepts data and expectedVersion; the existing record determines kind. The generated OpenAPI file contains a kind-discriminated creation union and runtime Zod input schemas. FIELD-REFERENCE lists the human-readable field limits. Server-generated snapshots, hashes, workflow checkpoints, review flags and authority states cannot be inserted through generic input. Original evidence and requests cannot be edited.

The route inventory is complete for the current declarations, but full response/error schemas and every non-record request body are not yet expressed in OpenAPI. Use the executable API tests and source validators for those exact payloads. This limitation remains in the production contract backlog.

Main command flows

• Evidence: create a source, inspect it, then record accept; retract requires a reason and invalidates dependent current records.
• Confirmation: review a task, create a request with task IDs, issue a private link, enroll the participant, submit decisions, inspect and accept the returned response. Confirmation binds to the request snapshot, never a client-supplied task hash.
• Report: create with audience/purpose/narrative/recordIds/expectedRevision; review with expectedVersion/contentHash/decision/note; download only when approved and bindings remain current.
• Workflow: create a definition with taskIds/handoffIds/joinPolicy/timeoutHours/maxAttempts; review it; start a case; record step actions with expectedVersion, stepId, action, note and routeIds.
• Asset: create a scoped upload, query status, PUT numbered base64/checksummed chunks, finalize the whole checksum, and read only within scope before expiry. The asset router enforces 25 MB and supported audio MIME types.
• Agents (shared/agents/contracts.ts AGENTS_API): GET agents lists the proposals, Not proposed and the saved manifests with their freshness; GET agents/build/{key} takes a proposal key or a saved manifest id. POST agents/save takes key, manifestId, expectedVersion and the advisor's edits; a stale version is 409 VERSION_CONFLICT and a loosening is 422 ADVISOR_LOOSENS. GET agents/manifests/{id}/export?format=sheet|json|claude-code|managed-agents|openai-agents returns a zip, or the JSON with as=json; {id} may also be a proposal key (the unsaved template, version 0). POST agents/access captures role × system access levels; POST agents/access/ask drafts an ask to the access granter and never sends it. The generic record route cannot change a saved manifest (422 MANIFEST_VIA_AGENTS). No Agents route calls an AI provider or runs an agent.
• Route (shared/route/contracts.ts ROUTE_API): GET route lists 1 card per accepted possible constraint and its rivals (RouteView); GET route/{cardId} is 1 card with its numbers ({cardId} is the candidate id, or "<candidateId>~H2" for a rival); GET route/patterns is the dated pattern library. POST route/{cardId}/ask drafts 1 field-bound ask per person (plan prefix route:ask:v1:) and never sends it; the sample company gets 403 SAMPLE_COMPANY. POST route/{cardId}/accept takes the rung, the owner, the prediction range, the guardrail, the window, the stop rule, the review date and expectedLadderHash; it writes a metric (or takes metricId), an intervention with the route fields (status agreed) and, for rungs 1 to 4, a review decision record. A changed ladder is 409 ROUTE_HASH_MISMATCH; a rung that does not fit, without overrideReason, is 422 ROUTE_NOT_ENOUGH_DATA; a Not proposed rung is 422 ROUTE_NOT_PROPOSED; a withdrawn, rejected or stale candidate is 409. GET route/{cardId}/work-order returns "Work order (draft)" as a zip, or the JSON with as=json, for rungs 5 to 7. GET route/patterns adds the dated options of the patterns research refresh. POST route/patterns/refresh (research.run, consent: true) starts that refresh as a research run (202) or, on the sample company, returns the authored sample with no run (200); refusals are 422 CONSENT_REQUIRED, 409 RESEARCH_SOURCE_MISSING, 409 PATTERNS_NOTHING_FITS and the research refresh rules. The generic record route cannot change an intervention's route fields (422 ROUTE_FIELDS_VIA_ROUTE). An outcome of a routed intervention gets its word from the proof rule (422 ROUTE_PROOF_RULE). Only the pattern refresh starts research; no Route route calls an AI provider for a verdict.
• Graph: GET supports focus, depth 0–4, limit 1–150, allowlisted relationships/kinds/states; it does not accept arbitrary query text. Rebuild uses current authoritative records and never invokes external actions.

Errors and operations

Errors carry a code, readable message, retryable flag and requestId where handled by the application. Typical statuses: 400 invalid command metadata; 401 missing/expired session; 403 actor/origin/CSRF rejection; 404 inaccessible scope; 409 version, binding or transition conflict; 410 expired request/audio; 422 semantic validation; 429 auth throttling; 503 unconfigured runtime. See tests/api.test.ts for executable examples.

The health route checks a live database query and reports service/version/runtime coverage. It does not prove external provider health, signing or customer-system access. Generated client reports are audience-reviewed local downloads; the explicit request email endpoint sends through the configured Resend account. No route executes a customer business action.

Companion mobile contract

contracts/companion-mobile.openapi.json is an authored OpenAPI 3.1 contract for /api/mobile/v1. npm run contracts checks that file and does not rewrite it. React Native generates types from it. The pinned operationIds are enrollParticipant, refreshParticipantSession, logoutParticipantSession, getParticipantProfile, listParticipantRequests, getParticipantRequest, createTranscription, createUnderstanding, and submitParticipantRequest. The QA vertical-slice matrix in docs/qa/companion-mobile-e2e-matrix.md is enforced as contract assertions. Runtime handlers for the pinned paths live in server/mobile-participant.ts. Preferences, push tokens, live transcription tickets, task-card routes, and Something Changed updates may be registered on the server, but they stay out of the pinned file. Browser invitation, team-link, and kickoff routes are unchanged.