Versioning

Last updated Jun 14, 2026

Every request must pin an API version via the Matter-Version: YYYY-MM-DD header. Keys and tokens pin at creation — there's no implicit "latest." The version selected here controls request/response shape, enum membership, and error format.

Matter-Version: 2026-05-01

See versioning for the deprecation policy and upgrade path.

Matter versions the API on two axes:

• URL major (/v1/, future /v2/). Today there is exactly one: v1. A new major ships only on a breaking change.
• Dated Matter-Version minor (YYYY-MM-DD). Backward-compatible additions inside the current major. 2026-05-01 is the GA launch and the only dated minor today.

The live registry of every major and its supported dated minors is GET /v1/api_versions — call it from SDKs to negotiate a version at startup.

Format

Matter-Version: 2026-05-01

ISO 8601 date. No codename suffix — the date alone identifies the release.

Pinning

Every key or token pins an api_version at creation time. Per-request Matter-Version headers override the pinned version. Matter does not auto-pin at first request — implicit version drift would silently change behavior between deployments, so we require an explicit choice up front.

POST /v1/tokens
{
  "tier": 4,
  "api_version": "2026-05-01",   # required
  "principal": { "human_id": "usr_..." }
}

Webhook endpoints pin separately — events are always serialized at the endpoint's pinned version regardless of what version the API is serving at the time.

What's backward-compatible

Additive changes land in dated releases without requiring consumers to bump versions:

• New endpoints.
• New optional request parameters.
• New fields on response bodies.
• New enum values, when the enum is flagged x-matter-enum-extensible: true.
• New error codes.

What's breaking

Breaking changes ship in a new URL major (/v2/). Inside a URL major, these require a dated bump:

• Renamed fields.
• Removed fields.
• Changed types.
• Changed enum semantics (a previously-meaningful value now means something different).
• Stricter validation on existing fields.

Architecture: version-change modules

Matter internally runs every response through a chain of version-change modules. Each module declares:

• A short description of the change.
• A transformation — typically "rename field X to Y" or "add missing defaults for Z".
• The resource types it applies to.

When a request arrives, Matter builds the response at the current internal version, then walks back through change modules until it reaches the target version (the one in the request's Matter-Version header). The same machinery serves requests from clients pinned to versions released years ago without any per-endpoint branching.

This is what lets Matter promise backward compatibility forever — every old client sees the API exactly as it did at the version it pinned.

Preview releases

Experimental endpoints and fields ship under preview before they GA. Opt in with a preview-suffixed version plus an explicit feature list:

Matter-Version: 2026-05-01.preview
Matter-Preview-Features: <feature-name>

• The .preview suffix on Matter-Version unlocks preview-marked surface.
• Matter-Preview-Features is a comma-separated list of named features this request opts into. Unknown features are rejected with 400 unknown_preview_feature so a preview consumer can't silently receive a different shape than it expected.
• Preview surface may change without a dated release — that's the whole point. Treat it as pre-GA and pin to a specific feature name, not to the preview version generally.

Once a preview feature GAs, it lands in a dated release and Matter-Preview-Features for that feature becomes a no-op (the feature is live for every client on that dated version or later).

No preview features are exposed at the GA launch.

Deprecation policy

When a dated release marks an endpoint or field for removal, the response carries:

Deprecation: <RFC 9745 deprecation date>
Sunset: <RFC 8594 removal date>

Plus a warning key in the JSON body. The minimum deprecation window is 12 months between the Deprecation and Sunset dates.

No surface is deprecated at the GA launch.

Tracking versions

• Full changelog: /changelog.
• Via the API: GET /v1/api_versions.
• Via MCP: the matter_list_api_versions tool.
• Via response header: every response echoes the pinned Matter-Version you used.

Version snapshots

When v1 ships its second dated minor release, the previous spec is preserved as a frozen OpenAPI document under apps/docs/api-reference/versions/. At launch the directory is empty — the canonical openapi.yaml is the single source for 2026-05-01.

The topbar exposes a v1 chip; the menu lists every dated minor and links to that date's changelog entry. Switching the rendered playground at runtime requires per-version page generation — out of scope for the GA cut. The active build selects its spec at build time via the MATTER_DOC_VERSION environment variable (default: latest).