Versioning & changes

The API version is in the path: every endpoint is under /v1. Responses also carry an X-Api-Version: 1 header.

Changes that can happen at any time

These don’t break a well-written client, so we make them within v1 without notice:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses.
• New values in fields that list a fixed set, such as state, status, endCause or type.
• New webhook event types (you only receive the ones you subscribed to, unless you subscribed to all).
• New error codes, and changes to error message wording.
• Tighter limits that protect the platform (for example rate limits), announced where possible.

Build your client to allow for these:

• Ignore fields you don’t recognize. Don’t fail on extra properties.
• Handle unknown enum values with a sensible default rather than an error.
• Branch on the error code, never on the message text.
• Don’t depend on field order in JSON objects, or on the length of ids.

Breaking changes

A change that could break a correct v1 client (removing or renaming a field or endpoint, changing a field’s type or meaning, making an optional field required) ships only in a new version (/v2). When that happens:

• We announce it at least 90 days before v1 changes behaviour.
• v1 keeps working, unchanged, for at least 12 months after /v2 is released.
• Deprecated endpoints return a Deprecation header, and a Sunset header with the date they stop working once that’s set.

Security fixes are the one exception: if an endpoint allows something it must not, we fix it immediately, even if a client relied on it.

Stay informed

The OpenAPI spec always describes the current v1. Diff it to see what changed.