Skip to main content
The version is in the URL path. Every endpoint lives under /v1/, and there is no version header or query parameter to set.

​
What can change inside a version

Changes inside /v1/ are additive:
  • new endpoints
  • new optional request fields
  • new fields in a response body
A client has one obligation in return: ignore response fields you do not recognise. A parser that rejects unknown fields turns a routine addition into an outage on your side. These never change inside a version:
  • the meaning or type of an existing field
  • an existing field becoming required, or disappearing
  • an error code string for a given failure
  • the path of an existing endpoint
A change of that kind gets a new version path (/v2/). Existing paths are not repurposed.

​
How a deprecation is announced

A deprecated endpoint says so in its own responses, so a client learns about it from a call rather than from a changelog nobody reads: There is a minimum of six months between the Deprecation date and the Sunset date on any generally available endpoint.
Nothing is deprecated today, so no live endpoint carries these headers.

​
Checking programmatically

The OpenAPI specification is the authoritative list of what exists in the current version. Log the Deprecation and Sunset headers alongside your other request metadata — that way an endpoint you depend on cannot be retired without it showing up in your own logs first.