Versioning and deprecation

How versions work

Major version in the path: /v1/…. It does not change in a way that breaks your integration while v1 exists.
Feature releases within v1: v1.0, v1.1, v1.2. Every operation in openapi.yaml carries an x-release, and the ones live today carry x-implemented: true. See the changelog.
Contract version: 1.0.0-draft.1 (info.version).

Before and after a release ships

We publish the contract ahead of the implementation so you can build in parallel. Before a release ships its shapes may still change, and every such change goes in the changelog. After it ships, v1 changes additively only.

Changes we make within v1 without notice

New endpoints and new webhook event types
New optional query parameters and request fields
New fields in responses and webhook payloads
New values in an existing enum
New error codes (each still uses the documented HTTP status)
New optional response headers
Accepting input that used to be rejected

Build to tolerate them: ignore fields you don't recognise, handle unknown enum values gracefully, don't depend on field order, branch on an error's code rather than its title, and treat an unknown error code by its HTTP status.

Breaking changes go to v2

We never make any of these within v1:

Removing or renaming an endpoint, field, parameter, enum value or event
Changing a field's type, format or meaning
Making an optional parameter or field required
Rejecting input that used to be accepted
Requiring a different or additional scope for an existing endpoint
Changing the signature scheme or the error format

If we need any of them, we ship /v2 alongside /v1, and v1 keeps working for at least [notice period to be confirmed] from the day its deprecation is announced.

How we announce a deprecation

A Deprecated entry in the changelog with the shutdown date.
The operation or field marked deprecated: true in openapi.yaml, so it shows in the reference and the Postman collection.
Email to the registered developer contacts and to companies using what is going away.
Deprecation and Sunset headers on the affected operations' responses until the shutdown date.

Previews

Features marked preview — currently OAuth — are outside this policy until they are generally available, and may change without a notice period.