# Migrating versions

> **TL;DR** — Your key is pinned to a dated version. When Wandura releases a newer one: read what changed, try it per request with the `Wandura-Version` header, then move your keys (a new key is pinned to the latest version; a rotated key keeps its pin). A new major version (`/v2`) gets 12 months of overlap.

Today there is one dated version, `2026-10-02`, so there is nothing to migrate yet. This page is the procedure for when there is.

## 1. Know where you are
```bash
curl -s https://www.wandura.ai/api/delivery/v1/config \
  -H "Authorization: Bearer $WANDURA_API_KEY"
```

`api.pinned_version` is your key's version, `api.latest_version` the newest, `api.supported_versions` the ones you may send, each with its `deprecated_at` and `sunset_at`. Every response also says the version it used, in `Wandura-Version`. Log that header.

## 2. Read what changed
The [version history](https://docs.wandura.ai/v1/developers/concepts/versioning#version-history), the changelog, and `https://docs.wandura.ai/changes.json` (`api_versions`) list each version and its changes.

## 3. Try the new version per request
Send `Wandura-Version: <new date>` on a few requests from a test environment (ideally your test organisation). The header overrides your key's pin for that request only. An unknown or retired value answers `400` `unsupported_version` with the versions you can use.

## 4. Move your keys
| Way | Pin after | Downtime |
|---|---|---|
| **Create a new key** with the same scopes, deploy it, revoke the old one | The **latest** version | None |
| Rotate the old key | **Unchanged**: rotation keeps the pin | Secret changes at once |
| Keep the old key and send `Wandura-Version` on every request | Whatever you send | None |

Before you switch keys in an emergency (a leak), check that the new key's version matches what your code expects: a new key is on the latest version.

## 5. Watch for deprecations
A deprecated version or endpoint answers with `Deprecation`, `Sunset` and `Link` headers on every response. Alert on them ([Observability](https://docs.wandura.ai/v1/developers/production/observability)). Notice periods: 30 days during the beta, 12 months after it.

## Related
- [Versioning and API evolution](https://docs.wandura.ai/v1/developers/concepts/versioning)