Versioning
Dated API versions and how API keys pin to one
The Clarify API has dated versions. A version is a year and month, such as
2026-01. Each breaking change ships under a new version, so your integration
only sees it when you move to that version.
Changes that don't break existing callers ship to every version. These include new endpoints, new optional parameters, and new fields in a response.
How a request gets its version
Each API key is pinned to a version when it's created. A new key gets the
latest version. The key's version is the api_version field in the API keys
list.
The Clarify-Version header
Send Clarify-Version to use a newer version for a single request. Use it to
try a new version before you move a key over:
curl https://api.clarify.ai/v1/workspaces/your-workspace/objects/person/resources \
-H "Authorization: api-key YOUR_API_KEY" \
-H "Clarify-Version: 2026-01"The header can raise a key's version, never lower it. A version older than the
key's, or one that doesn't exist, returns 400 Bad Request.
To move a key to a newer version for good, create a new key.
Checking your version
Responses tell you which version handled them, in the Clarify-Version
header. If the API behaves differently than you expect, check this first.