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

# API Versioning

> How Clara versions its API and what to expect from each release.

Clara maintains multiple API versions simultaneously so you can integrate at your own pace without forced migrations.

## Current versions

| Version | Status  | Recommendation               |
| ------- | ------- | ---------------------------- |
| v3      | Current | Use for all new integrations |
| v2      | Stable  | Supported, not deprecated    |
| v1      | Legacy  | Avoid for new work           |

## What constitutes a breaking change

Clara considers these **breaking changes** — they will never happen within a version:

* Removing an existing field from a response
* Changing a field's data type
* Removing an endpoint
* Changing authentication requirements

These are **non-breaking** and may happen without a version bump:

* Adding new optional fields to responses
* Adding new optional query parameters
* Adding new endpoints
* Improving error messages

## Deprecation policy

When Clara deprecates a version:

1. A deprecation notice is published in the [Changelog](/versioning) with at least **6 months' notice**
2. The version remains functional throughout the deprecation period
3. A migration guide is provided before end-of-life

v1 and v2 are currently **not deprecated** — they will continue to receive security fixes.

## Version coexistence

All three versions share the same authentication (mTLS + OAuth 2.0). You can call v2 and v3 endpoints in the same integration using the same credentials — version is determined by the URL path (`/api/v2/...` vs `/api/v3/...`).

## Selecting a version

Use the **v3** tab on any API reference page to see the current interface. If a service is not yet available in v3, the page will indicate which version to use instead.