The Ashby API is versioned using date-based version identifiers. Versions are used to introduce changes that might break existing integrations such as:

Removing endpoints
Changing or removing response fields
Changes to core API behaviour e.g. pagination, authentication, error responses

Current versions

Status	Version	Deprecated	Unsupported	Removed
🟢 Active	2026-01-01

The version.list endpoint can be used to retrieve available versions and their status programmatically.

Each version moves through these statuses:

Status	Meaning
`pre-release`	Pre-release versions are only available to organizations enrolled in early access.
`active`	Generally available and fully supported. Ashby fixes bugs and may make non-breaking changes in response to customer requests. The newest active version is the default for new API credentials.
`deprecated`	Still fully served and supported, with an announced unsupported date and removal date. Plan your migration to the latest version.
`unsupported`	Still served until its removal date, but Ashby is no longer obligated to fix bugs or make changes in this version. Migrate to the latest version.
`removed`	No longer served. Requests that select a removed version with the `Ashby-Version` header are rejected.

A deprecated version stays fully supported for at least 3 months and remains available for at least 6 months before it is removed. The exact dates are announced when a version is deprecated and listed in the table above.

Selecting a version

When you create an API credential, it is assigned the newest active version unless you choose otherwise. A credential's version cannot be changed afterwards.

Ashby chooses the version for each request in this order:

The version named in the Ashby-Version request header.
Otherwise, the version of the API credential making the request.

Migrating to a new version

A credential's version cannot be changed so we recommend migrating in two steps:

Send the Ashby-Version header with the new version on individual requests. Start with a few requests and expand once each one works with the new version.
When your whole integration works with the new version, create a new credential on that version, switch to it, and remove the header.

Example usage of the Ashby-Version header:

curl https://api.ashbyhq.com/version.list \
  -u API_KEY: \
  -H "Ashby-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  --request POST

Response headers

Responses include two headers that identify the version used to process the request:

Header	Description
`Ashby-Version`	The version used to process the request.
`Ashby-Version-Status`	The lifecycle status of that version: `pre-release`, `active`, `deprecated`, or `unsupported`.

HTTP/1.1 200 OK
Ashby-Version: 2026-01-01
Ashby-Version-Status: active