Versioning and deprecation

This reference describes /v1 at version 1.0.0, and /v1 is stable. Within /v1, paths, parameters and response fields keep their names, types and meaning, and an optional parameter stays optional. New endpoints, optional parameters, response fields, headers and enum values can arrive at any time, so read what you recognise and ignore the rest.

When something in /v1 has to change in a way that could break an integration, we announce it at least 12 months before it stops working. From the day of the announcement, every response it affects carries three headers:

• Deprecation

  When it was deprecated: @ and Unix seconds (RFC 9745), e.g. @1793869200

• Sunset

  When it stops working: an HTTP date (RFC 8594), e.g. Fri, 05 Nov 2027 09:00:00 GMT, at least 12 months after Deprecation

• Link

  <url>; rel="deprecation": the page that describes the change and what replaces it

The same day, /v1/changelog carries the announcement and this reference marks the operation deprecated. Nothing in /v1 is deprecated today, so no response carries these headers yet. The changelog on this site shows the same entries /v1/changelog answers.