API versioning
The stability promise and how changes are rolled out.
The public API is versioned in the URL: everything under /api/v1. The
machine-readable contract is openapi/getwait.v1.json,
generated from the route registry (bun run openapi:generate). CI fails when
the committed file differs from the code (openapi:check), when it breaks the
lint rules in .spectral.yaml (openapi:lint), or when a real response
differs from it (the integration suite validates every response).
Routes under /api/internal are for the scheduler, are not part of the API,
and may change at any time.
What /v1 promises
/v1 is stable. Within it we only make additive changes:
- new endpoints;
- new optional request fields, query parameters and headers;
- new fields in response bodies (clients must ignore fields they do not know);
- new values in
eventsand webhook event types, and new errorcodes; - looser validation (a larger limit, a wider accepted format).
We do not, within /v1:
- remove or rename an endpoint, field, parameter, header or error code;
- change a field's type, format or meaning;
- make an optional field required, or tighten validation of accepted input;
- change an existing status code, or the auth a route requires;
- change the error envelope
{ error: { code, message, requestId, details? } }.
Treat message as free text and match on code. Response objects are open
in the spec (no additionalProperties: false) for this reason; request bodies
are strict, so a typo is a 422 instead of being silently ignored.
Rate limits and plan limits are operational settings, not part of the contract; they appear in the spec descriptions and may change with notice in the changelog.
Breaking changes
A breaking change ships as a new version (/api/v2) next to /v1; it never
replaces /v1 in place. Webhook payloads carry an api_version date for the
same reason.
Deprecation window
When something in /v1 is to be removed:
- It is marked
deprecated: truein the OpenAPI document and announced in the changelog. Responses to deprecated routes carry aDeprecationheader and, once a date is set, aSunsetheader (RFC 8594). - It keeps working unchanged for at least 12 months after the
announcement, and for at least 6 months after
/v2offers a replacement, whichever is later. - Only after the sunset date is it removed, and only in a new major version;
/v1routes that are removed answer410 Gone.
Security fixes are the exception: a change needed to close a vulnerability may ship without the full window, with the reason in the changelog.
For contributors
- Changing a route, schema or example changes the spec: run
bun run openapi:generateand commitopenapi/getwait.v1.jsonwith the code.bun run verifyfails otherwise. - A diff that removes or renames a property, or narrows a type, in the
generated file is a breaking change; do not merge it into
/v1. - Every public route needs a
docsblock (summary, description, tag, examples) or the registry refuses to start.