Both are generated by
buildOpenApiDocument() in
packages/contracts/src/http/openapi.ts from the same zod schemas the API
validates with and the browser validates against. Every endpoint appears
automatically in the API group of this tab, one page per operation, with its
request, response and error schemas. Regenerate the snapshot with
pnpm openapi:write.
Versioning
v1 is in the path of every endpoint. Every response carries x-api-version: v1.
See versioning.
Authentication
Authorization: Bearer <access token>, from auth.signIn. Two endpoints are
public: auth.signIn and auth.refresh. An expired access token is refreshed
once and the call is replayed; concurrent calls share a single refresh. See
sessions.
Errors
An RFC 9457 problem document. Match oncode, not title. See errors.
Pagination
List endpoints takepage (1-based, default 1) and limit (default 50, maximum
200) and answer with:
Unknown fields
Ignored, not rejected, so a newer client can talk to an older API. Withinv1
this is what makes additive change safe.
Streaming
chat.messages.stream answers text/event-stream. Each frame is a data: line
holding one JSON event: start, delta (repeated), then done or error. The
contract’s schema for the stream can be found under the operation in the rendered
reference. See stream a reply.
Using the typed client
In the web app, call operations by name. Types come from the registry:Keeping the reference honest
packages/contracts/test/openapi.test.mjs asserts that every registered operation
appears in the document, that each declared error code is documented, that public
operations opt out of bearer security, and that no reference dangles. Run it with
pnpm --filter @dme/contracts test.