Versioning and deprecation

The API lives at /v1, and v1 is stable. This page says what that means: what can change without warning, what never changes inside v1, and how much notice you get when something has to go.

Changes that can land at any time#

These are additive. They can ship in v1 on any day, with no notice:

• new endpoints
• new fields in a response
• new optional parameters on a request
• new values in a field that lists a fixed set of values, such as a status or a stage

Write your client to cope with them. Ignore fields you do not know, and treat an enum value you do not recognize as "something new" rather than as an error. A client that rejects an unknown field will break the day we add one.

Changes that need a new version#

A breaking change never ships in v1. It ships in a new version, at /v2, and v1 keeps working beside it. Breaking means a call that worked before now fails or means something else, for example:

• removing or renaming an endpoint, a parameter or a response field
• changing the type or the meaning of a field
• making an optional parameter required

Notice before anything is removed#

If something in v1 will be removed or changed, we tell you at least 6 months ahead, in two places:

1. The changelog, in these docs. The entry names what is changing, the date and what to use instead.
2. Response headers on the affected endpoint. Each response carries a Deprecation header (RFC 9745) from the day the notice starts, and a Sunset header (RFC 8594) with the date it stops working.

The headers look like this. The values are an example, not a live notice:

Deprecation: @1798761600
Sunset: Fri, 01 Jan 2027 00:00:00 GMT

A client that logs these two headers will hear about a removal without anyone reading the changelog.

Today#

Nothing in v1 is deprecated, so no response carries either header. The OpenAPI document always describes the API as it is now.