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

# API versioning

> Pin the Messaging API contract date and handle version warnings and errors.

Messaging API requests can send a date version in the `Titan-Version` header:

```http theme={null}
Titan-Version: 2026-03-20
```

The current and minimum configured version is `2026-03-20`. When the header is
omitted, the API uses the current version. The resolved value is echoed in the
response as `Titan-Version`.

## Current request

```bash theme={null}
curl "https://api.polymorfa.com/api/sessions" \
  -H "Authorization: Bearer $TITAN_KEY" \
  -H "Titan-Version: 2026-03-20"
```

## Versions below the minimum

A version earlier than the configured minimum returns `400` before the route
handler runs. The response includes:

```http theme={null}
Deprecation: true
Link: <migration URL>; rel="deprecation"
```

```json theme={null}
{
  "error": "API version 2025-01-01 is no longer supported. Minimum: 2026-03-20",
  "docs": "<migration URL>"
}
```

Follow the response's `docs` URL rather than constructing a migration URL.

## Older supported versions

When a configured version is older than the current version but still meets
the minimum, the request continues and can include:

* `Sunset` when a sunset date is configured;
* `Titan-Deprecation-Warning`; and
* a `Link` with `rel="sunset"`.

No older version is supported because the current and minimum dates are the
same.

## Meta-compatible versioning

Meta-compatible Messaging API operations use the `vNN.0` segment in their path.
Keep native and Meta-compatible version selection separate; `Titan-Version`
does not replace the path version.