Versions and deprecation

Every request goes to a path under a version, such as /api/v2/. The versions served today:

Any other version path, such as /api/v1/, answers 404 with {"error":"not_found"}. The token endpoint, /oauth/token, sits outside the versions.

Breaking changes

A change that could break a system already connected, such as removing or renaming a field, a route or a format, is published only under a new version path. The version you use keeps working as it is. A change that only adds, such as each change in the Changelog so far, is made to the current version.

When a version is superseded

• The previous version is deprecated on the day its successor is published, and stays available for at least 12 months after that before it is removed.
• The Administrators of every organisation with an API credential are emailed when the deprecation starts, and again 3 months before removal.
• Every response from a deprecated version carries a Deprecation header with the date its deprecation started, a Sunset header with the date it will be removed, and a Link header pointing to the policy. A response from the current version carries neither.

Every change, with its date, is in the Changelog. The policy is also in the Help Centre: Versions and deprecation. The current version’s OpenAPI document is at /api/v2/openapi.json on your organisation’s address.