Versioning

The version is in the path — /api/v1. It changes only for a break.

Changes that happen in place

These ship to /v1 without notice, so write clients that tolerate them:

• New endpoints and new sub-resources.
• New fields on an existing response.
• New optional query parameters.
• New error.type values on a status code that already existed.

In practice: do not assert on the exact set of keys in a response, and do not treat an unknown error.type as a crash.

Changes that require a new version

• Removing or renaming a field, or changing its type.
• Removing an endpoint, or changing what it returns for the same request.
• Making an optional parameter required, or narrowing accepted values.
• Changing a default, including sort order or page size.
• Changing the meaning of an existing error.type.

Deprecation

When /v2 arrives, /v1 keeps working through an announced window rather than being switched off. Deprecated responses carry a Sunset header with the date after which they may stop, and the changelog is the record of what changed and when.

What is stable now

Field names and response shapes for the endpoints in the reference are stable. Two things are explicitly not settled yet, and both are called out where they appear: per-plan quotas and the X-RateLimit-* headers (rate limits), and the MCP protocol version (MCP).