Compatibility Policy

The API is versioned in the path (/api/v1). This page is the contract: it tells you which changes we may ship at any time — so you can write a client that won't break — and what we owe you when something genuinely has to change.

Changes we can make at any time

These are not breaking, and they can ship without notice. Your client must tolerate them:

New endpoints.
New optional query parameters.
New fields in a response object. Ignore fields you don't recognize.
New members in an enum (for example a new status, or a chair adding a custom decision type). Don't switch exhaustively over an enum and throw on the default branch.
New response headers.
A change in the length or format of an opaque string — ids, cursors, and pfx_live_… keys are opaque. Don't parse them; don't assume a maximum length beyond 255 characters.
Reordering of object keys, and reordering of list items where no sort order is documented.

The two that bite people are new response fields and new enum members. A client that rejects unknown fields, or that treats an unfamiliar enum value as a fatal error, will break on a routine additive release. Parse leniently.

Changes that count as breaking

These require a new major version (/api/v2), which we would rather never ship:

Removing or renaming an endpoint, a query parameter, or a response field.
Adding a required request parameter, or making an existing optional one required.
Changing the type of a field.
Removing a member from an enum.
Tightening validation on an existing parameter so previously-accepted requests start failing.
Changing authentication or authorization requirements.
Changing the observable meaning of an existing field.

Deprecation

If we ever retire an endpoint, it will:

Return a Deprecation header (RFC 9745) from the moment it is deprecated.
Return a Sunset header (RFC 8594) with the date it stops working.
Carry a Link header pointing at the migration guide.

You get at least 12 months between the Deprecation header appearing and the Sunset date. Watch for those headers in your integration — logging them is the cheapest early-warning system you can build.

Writing a durable client

Ignore unknown fields and unknown enum values. Treat an unrecognized enum as "some other value", not as an error.
Treat ids, slugs, and cursors as opaque. Don't construct or decode a cursor; pass back the nextCursor you were given.
Branch on the error code, not the detail string. detail is written for humans and may be reworded at any time; code is stable.
Honor Retry-After on a 429, and back off exponentially with jitter on a 5xx.
Pin nothing to response order unless the endpoint documents a sort.

Status of v1

v1 is stable. The current surface is read-only — write endpoints will be added (which is a non-breaking change under the rules above), not swapped in.