Migrating between versions

Last updated Jun 14, 2026

This page is the migration contract. The per-release migration guides under /changelog/ follow the structure here so the diff between any two dated versions reads the same way every time.

How versions work

Matter has two version axes:

A token created against Matter-Version: 2026-05-01 continues to behave exactly as it did on that date for the lifetime of v1. The runtime keeps every dated minor live in parallel — it does not "redirect" old versions forward.

When a dated minor releases:

1. The canonical OpenAPI spec advances to the new date.
2. The previous date is snapshotted under api-reference/versions/<previous>.yaml.
3. A migration guide ships under /changelog/<new-date>/.
4. The version dropdown in the docs topbar lets readers compare the two.

See /api/conventions/versioning for the full version-policy contract.

What counts as additive

• Adding a new endpoint.
• Adding an optional request field.
• Adding a new field to a response (clients ignoring unknown keys are safe by design).
• Adding a new enum value to a field marked x-matter-enum-extensible: true.
• Adding a new event type.
• Adding a new error code (existing codes never change semantics).

What does not count as additive — and ships as a new major

• Removing a field, endpoint, or enum value.
• Tightening a validation rule that previously accepted a value.
• Changing the type of a field (string → object, etc.).
• Changing the URL of an existing endpoint.
• Changing default sort order or pagination semantics on a list endpoint.

The contract is enforced in CI by a spec-diff job that flags any of the above against the previous canonical spec. A dated minor that trips the guard cannot ship — the work moves to the next major.

Migration-guide template

Every per-release migration guide under /changelog/<date>/ follows this shape. Copy the section structure verbatim when you author the next one.

---
title: "Migrate to YYYY-MM-DD"
description: "What changed in the YYYY-MM-DD release of the Matter API and how to upgrade."
---

## Headline

One sentence on the scope of the release. "Adds X, deprecates Y, no
breaking changes." Readers who only read the headline should leave with
the right mental model.

## Additions

| Resource | What was added | Why |
|---|---|---|
| `Entity` | Optional `metadata.formation_intent_id` on response. | Cross-link entities to the `Intent` they resolved from. |
| `Filing` | New `/v1/filings/{id}/withdraw` endpoint. | First-party support for the Delaware withdraw-before-effect window. |

## Deprecations

| What | Sunset window | Replacement |
|---|---|---|
| `Filing.legacy_status` | 6 months from this release. | `Filing.status` plus `Filing.substatus`. |

A field marked deprecated continues to be returned for the full sunset
window; new clients should not read it. The field is annotated
`x-matter-deprecated-since: YYYY-MM-DD` in the spec so SDKs surface a
typed deprecation warning at compile time.

## Behavioural changes

Anything additive that nevertheless changes a default. Always opt-in for
existing tokens; pinning the prior version preserves the prior behaviour.

| What | Before | After |
|---|---|---|
| `?expand[]=cap_table` depth | Resolved 2 levels deep. | Resolves 4 levels deep. Use `?expand_depth=2` to opt out. |

## Code-mod

Where a mechanical migration is possible, ship a `codemod-<date>.sh`
script under `apps/docs/scripts/codemods/` that operates on Matter SDK
call sites. Inline the entire script in the guide so readers can audit
before running.

```bash
# example: rename Filing.legacy_status reads to Filing.status
fd -e ts -e py | xargs sed -i 's/\.legacy_status\b/.status/g'
```

If a code-mod is not possible (a deprecation that only some call sites
should migrate), say so explicitly and walk the reader through the
decision.

## Verifying the migration

Three checks the reader should run before bumping their pinned version:

1. **Run the SDK against `sk_test_` mode pinned to the new version** —
   confirms the call sites still work shape-wise.
2. **Subscribe to `*.deprecation_warning` webhooks** — the runtime fires
   one for every read of a deprecated field, with the request id and the
   field path.
3. **Bump the pinned version on a single token first** — if the new
   version misbehaves, that token's blast radius is bounded.

## Related

- [versioning](/api/conventions/versioning)
- [Previous: /changelog/<previous-date>/](/changelog)
- [OpenAPI snapshot for this version](https://api.mattermode.com/v1/openapi.yaml?version=YYYY-MM-DD)

Why we ship guides this way

A migration guide is not a marketing post. It exists to answer one question for an engineer who is about to bump a pinned version: "what will break for me, and what should I do about it?" The template above optimises for that.

• The headline tells the reader whether to keep reading.
• The additions table sets expectations on new surface area.
• The deprecations table is what they came for — the sunset window is the SLA that matters.
• The behavioural changes table catches the surprises that aren't schema-level.
• The code-mod lets them migrate mechanically when possible.
• The verification steps are the runbook for a safe bump.

Versioning the guide itself

The migration guide for <date> is the canonical artifact for that version. If a clarification is needed after publication, edit the guide in place — do not ship a "v2" of the guide. Material corrections add a > Updated YYYY-MM-DD: <reason> line at the top.

Related

• /changelog — the chronological feed.
• versioning — the versioning policy as canonical reference.
• agents › Version pinning — how Matter-Version interacts with token pinning.