---
name: wilmo-api-migrations
description: Move an integration of Wilmo's public API from one dated API version to a newer one, safely. Use when Wilmo announces a new API version, when a response's Wilmo-Version header is older than the current version, or before using a field that only a newer version has.
---

# Migrating between Wilmo API versions

```text
versions        dated: 2026-11-06, ...          GET https://app.wilmo.ai/api/public/v1/api-versions
your version    the Wilmo-Version you send, else your key/grant's pinned version
breaking        only ever in a new version; your pinned version keeps its shape
additive        new operations, new optional inputs, new output fields: arrive in every version
```

## Steps

1. Read the changelog: `GET /api/public/v1/api-versions`. For every version newer than yours,
   read each change's `description` and `migration` for the operations you call.
2. Change your code for each one (a renamed field, a new required input).
3. Send `Wilmo-Version: <new version>` on every request, in tests first, then in production.
   Pinning the header in code is the migration: nothing changes until you send it.
4. Check every response's `Wilmo-Version` header says the new version.
5. Roll back by sending the old version again: older versions keep working.

## Write code that survives additive changes

- Ignore output fields you do not know.
- Treat enums as open: handle an unknown value gracefully.
- Page with `next_cursor` until `has_more` is false; never assume a page size.