> ## Documentation Index
> Fetch the complete documentation index at: https://developer.affinity.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

Versioning in Affinity's API ensures that your integrations remain stable as updates are introduced.
Within API v2, minor versions identify releases that include breaking or behavior-changing
modifications, and they allow you to target the exact API behavior your integration depends on.

The current available versions are:

* **2026-09-17** - The new current stable version of the v2 API. Introduces breaking changes around
  relative date filters, `is-between` bounds validation, new field types, and AI Notetaker
  transcript IDs. See the [changelog](https://developer.affinity.co/pages/changelog/version-migration.md) for full details.
* **2026-07-15** - A previous stable version of the v2 API. This version is now locked and will not
  receive further changes.
* **2024-01-01** - A previous stable version of the v2 API. This version is now locked and will not
  receive further changes.

As new minor versions of Affinity API v2 are introduced, they will appear in this list. You'll be able to
create new apps using those versions, update an existing app's default version, or override the
version on a per-request basis with a header.

### Setting an app's default version

Every app has a **Default API Version**, which is used for any request made with that app that does
not specify a version header.

* **When creating an app:** open the Manage Apps page in your Affinity Settings and select a
  **Default API Version** in the app creation form.
* **For an existing app:** open the app from the Manage Apps table and edit its **Default API
  Version**.

### Overriding the version per request

To target a specific version on an individual request, send the `X-Affinity-Api-Version` header with
the desired version. This overrides the app's default version for that request only:

```bash theme={null}
curl https://api.affinity.co/v2/persons \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "X-Affinity-Api-Version: 2026-09-17"
```

If the header is omitted, the request is handled using the app's Default API Version. If the header
specifies a version that is not supported, the request returns a validation error.

Every response includes an `X-Affinity-Api-Version` header indicating the version that was used to
handle the request. You can also use `current` as the version value to always receive the latest
version, though this will make your integration vulnerable to breaking changes when new versions are
released.


## Related topics

- [Versioning & Deprecation](https://developer.affinity.co/pages/data-share/versioning.md)
- [Version Migration](https://developer.affinity.co/pages/changelog/version-migration.md)
- [OAuth Apps and MCP Clients (CIMD)](https://developer.affinity.co/pages/external-api-v2/oauth-apps.md)
- [Previous Changes](https://developer.affinity.co/pages/changelog/previous-changes.md)
- [Beta Endpoints](https://developer.affinity.co/pages/external-api-v2/beta-endpoints.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.