Versioning
How dated HQ-Version headers keep your integration stable.
The API has a major version in the URL (/v1) and a dated version in the HQ-Version
header, for example 2026-11-01.
How a version is chosen
- A key is pinned to the newest version when it is created.
- A request can ask for another known version by sending
HQ-Version: 2026-11-01. - An unknown date answers
400 invalid_request, with the current version in itsHQ-Versionheader. - Every response says which version served it, in its own
HQ-Versionheader.
What changes without a new version
These are additive and never break a careful client:
- a new endpoint;
- a new optional field on an object;
- a new optional query parameter;
- a new value in a field we document as open-ended (for example a session
status).
Write your code to ignore fields it does not know and to handle values it has not seen.
What needs a new version
Anything else: removing or renaming a field, changing a type, making a parameter required, changing what an endpoint does. Those ship under a new dated version, listed in the changelog, and your pinned keys keep the old behaviour until you move them.
The major version
/v1 is supported for at least 24 months after a /v2 exists. See the
deprecation policy.
Was this page helpful?