Versioning and deprecation

v1 is additive only

Everything under /api/v1 follows these rules. Changes we can make at any time, without notice:

• New endpoints.
• New optional request parameters or body fields.
• New fields in responses. Ignore fields you do not recognise.
• New error codes. Handle unknown codes by their HTTP status.
• Changes to error message text. Match on error.code, not the message.

Breaking changes

A breaking change is anything that can make a correct client fail: removing or renaming an endpoint, field or parameter, changing a type or default, making an optional input required, or changing the status code or error code for an existing case.

• We announce it in the changelog at least 90 days before it takes effect.
• Affected responses carry a Deprecation header from the announcement, and a Sunset header with the date the old behaviour ends.

The exception is a fix for a security issue, which may ship with shorter notice. It will still be recorded in the changelog.

History

Before this policy was published, a validation change shipped on 30 September 2026 without a notice period (unknown require values and extra PATCH fields now return 422). It is listed in the changelog. Changes since then follow the rules above.

SDKs

The Python and TypeScript SDKs and the MCP server follow semantic versioning. While they are below 1.0, a minor version (0.x) may contain breaking changes; each one is noted in the package changelog and in ours.