AI Workforce OneHQDocs

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

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.