# 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 [#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 its `HQ-Version`
  header.
* Every response says which version served it, in its own `HQ-Version` header.

## What changes without a new version [#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 [#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](/docs/api/changelog/), and your pinned keys keep the old behaviour until you move them.

## The major version [#the-major-version]

`/v1` is supported for at least 24 months after a `/v2` exists. See the
[deprecation policy](/docs/api/deprecation-policy/).
