Skip to main content

Versioning

The API version is part of the URL path, such as /api/v1/.... Within a version we only make backward-compatible changes:
  • new endpoints
  • new optional request parameters
  • new fields in responses
  • new values in enums
Your client should ignore response fields and enum values it does not recognize. Breaking changes, such as removing a field or changing its type, go into a new version or a new endpoint.

Deprecating an endpoint

When we retire an endpoint, we:
  1. Announce it in the changelog and on the endpoint’s docs page, and name the replacement.
  2. Send the Deprecation and Link response headers on the endpoint from that day.
  3. Set a removal date at least 6 months after the announcement, and send it in the Sunset header. Security fixes may need a shorter period, with at least 30 days’ notice.
  4. Remove the endpoint after the sunset date.
Deprecated endpoints keep working until their sunset date. To find out early, watch for the Deprecation and Sunset headers in your client.

Currently deprecated endpoints