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

# Versioning

> Dated API versions, the Tavrn-Version header, and the support window

The Enterprise API path stays `/v2`. Behaviour changes ship as **dated versions** (`YYYY-MM-DD`) that you opt into, the way Stripe, GitHub and Anthropic version their APIs. Nothing changes for an integration until it asks for a newer version.

## Tavrn-Version header

Send `Tavrn-Version` on any request to pin that request to a version:

```bash theme={null}
curl https://enterprise.tavrn.ai/v2/cases \
  -H "Authorization: Bearer tavrn_sk_live_..." \
  -H "Tavrn-Version: 2026-10-16"
```

Every authenticated response — success or error — echoes the version that was applied. Requests rejected before authentication (`401 invalid_api_key`) carry no `Tavrn-Version` header, because the version cannot be resolved without the key:

```http theme={null}
HTTP/1.1 200 OK
Tavrn-Version: 2026-10-16
```

## Resolution order

| Priority | Source | Notes |
| - | - | - |
| 1 | `Tavrn-Version` request header | Must be a version listed in the [changelog](/guides/v2/changelog). |
| 2 | Default version pinned to the API key | Set to the newest version when the key is created. Shown read-only on the key in **Dashboard → API**. |
| 3 | Baseline `2026-10-16` | Keys created before versioning existed resolve here. |

Unknown, malformed or not-yet-released values are rejected with `400` and the `invalid_api_version` error code — they are never rounded to a nearby version.

```json theme={null}
{
  "error": {
    "code": "invalid_api_version",
    "message": "Tavrn-Version must be a supported dated version (YYYY-MM-DD). Supported: 2026-10-16. See https://docs.tavrn.ai/guides/v2/versioning"
  }
}
```

## Upgrading

1. Read the [changelog](/guides/v2/changelog) entry for the target version.
2. Send `Tavrn-Version: <date>` from a test client and verify the response header echoes it.
3. Roll the header out to your integration. To move a whole integration at once without code changes, create a new API key after the version ships — new keys default to the newest version — and rotate to it.

Keys cannot be re-pinned from the dashboard yet; create a new key or send the header per request.

## Support window

A version is supported for **12 months** after the next version is released. Responses served on a superseded version carry standard deprecation headers so monitoring can catch them:

| Header | Meaning |
| - | - |
| `Deprecation: @<unix-timestamp>` | When the version was superseded ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)). |
| `Sunset: <HTTP-date>` | When the version stops being served — superseded date + 12 months ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). |
| `Link: <…/versioning>; rel="deprecation"` | This page. |

No version is deprecated today, so these headers are not currently emitted.

## What a version does and does not change

Additive changes — new endpoints, new optional request fields, new response fields, new enum values, new webhook event types — ship to **all** versions without a new date. Clients should ignore unknown response fields and unknown enum values.

A new dated version is only cut for a change that could break a working integration: removing or renaming a field, changing a default, changing a status code, or making an optional field required.