Versions and stability

Versions

Every version is named YYYY-MM-DD.name, the day it was cut and a name, for example 2026-10-09.aster. A new version is cut only for a change that would break a caller: an operation removed or renamed, a field it returned removed, a required variable added, a variable's type changed, or its access level raised. Everything else, such as a new operation or a new field, lands in the current version and breaks nobody.

The changelog lists every version, newest first, with release notes and upgrade steps.

Before release

Until the API is released for general use, it is in pre-release, and the version menu and the changelog mark the latest version with Release candidate "Pre-release". During pre-release, breaking changes may land in the latest version without a new version being cut: an operation's old shape stops working when its new one ships, and no older version keeps serving it. Expect to update your integration when the changelog lists a change. Once the API is released, the pre-release note goes away and every breaking change gets a new version, as described below.

How long an old version works

When a new version is cut, the previous one stays served for 12 months. Once the new version is the current stable one, every request the older version serves carries Deprecation and Sunset headers. After the 12 months, a request that names it is served by the oldest version still supported, and the Missin-Version response header says which.

Pinning a version

Surface	What decides the version
GraphQL (/graphql/v1)	The operation's hash: an old hash keeps working while its version is supported. Send Missin-Version to have it checked.
Hosted MCP (/mcp)	The Missin-Version header; without it, the latest version.
SDK	The version it was generated from (API_VERSION), sent on every request. createMissinClient({ apiVersion }) overrides it.
CLI	The version it was built for. --api-version or MISSIN_API_VERSION overrides it.

Missin-Version: latest means whichever version we currently point it at: normally the current stable version, but it may name a release candidate while one is being readied, so pin a version rather than sending latest in anything that must not change under you. A version that does not exist is refused with unknown_api_version.

Reading the headers

Header	When	Meaning
Missin-Version	Always	The version that served the request.
Deprecation	A version older than the current stable one served it	@ and the time the next version was released, in seconds (RFC 9745).
Sunset	A version older than the current stable one served it	The date it stops being served (RFC 8594).
Link	A version older than the current stable one served it	The release notes of the next version, rel="deprecation".
Missin-Deprecated	The operation is deprecated	The operation's name. Its reference page says what to use instead.

Release candidates

A version marked release candidate is served and documented under its own address but may still change before it becomes the stable line. Requests it serves carry only the Missin-Version header, and the current stable version is not deprecated by it. Build against the current stable version unless you are testing the next one.

SDK and API versions

Once the API is released, a release that cuts a new API version raises the SDK's major version; a new operation or a deprecation raises the minor version; a fix raises the patch. During pre-release the SDK and CLI stay below 1.0.0 and a breaking change raises the minor version; 1.0.0 ships with the API's release. Every SDK release names its API version in API_VERSION, and each version's section of the changelog lists the SDK releases that shipped it ("In 1.0.0"), so the changelog is the one table of SDK release to API version.