API lifecycle - Primer

This page describes the lifecycle of the Primer API: the named stages every version moves through, what Primer commits to at each stage, and the rules that govern transitions.

Lifecycle stages

Every supported version of the API is in one of six stages at any given time.

Stage	Badge	SLA	Support	Breaking changes	Minimum notice before next stage
Beta	`BETA`	None — use at own risk.	Best-effort support for our early adopters.	Allowed, documented in the changelog.	—
Release Candidate	`RC`	None — near-final quality.	Priority support for testers.	Unlikely, but possible.	30 days before `GA`.
Generally Available	`GA`	Full production SLA.	Full support: bug fixes, security patches, and new features.	Avoided. A migration path is provided when one is required.	12 months before deprecation.
Supported	`Supported`	Reduced — security only.	Critical security patches only. No new features.	None — the version is frozen.	12 months before end of life.
Deprecated	`Deprecated`	Reduced.	None. The version still serves traffic and emits deprecation signals.	None.	12 months before end of life.
End of Life	`EOL`	None.	None. Calls return `410 Gone`.	—	—

How versions move between stages

The lifecycle is time-driven, with explicit minimum notice periods at each transition. Notice periods are floors, not targets — Primer can stay in any stage for longer than the minimum, but cannot shorten it.

A version in RC reaches GA no sooner than 30 days after entering RC.
A version in GA is given at least 12 months of notice before being deprecated.
A version in Deprecated remains there for at least 12 months before reaching EOL.

Current status

Version	Stage	Deprecation	End of life
`v2.4`	`GA`	—	—
`v2.3`	`Supported`	2026-07-01	2027-07-01
`v2.2`	`Supported`	2026-07-01	2027-07-01
`v2.1`	`Supported`	2026-07-01	2027-07-01
`v2`	`Supported`	2026-07-01	2027-07-01

This table is updated as versions transition between stages. For per-version changes, see the API changelog.

Machine-readable signals

Three HTTP signals communicate the lifecycle state of each request and response:

X-Api-Version request header. Pin every request to a specific API version. If the header is omitted, requests default to the earliest supported version — which means an unpinned client may silently start hitting an older version as new versions ship. Pinning is strongly recommended.
Deprecation response header. Emitted from Deprecated versions. Carries the date the version was deprecated. Standardised in RFC 9745.
Sunset response header. Companion to Deprecation. Carries the planned end-of-life date. Standardised in the same RFC. Standardised in RFC 8594

Example response from a deprecated version:

HTTP/1.1 200 OK
Deprecation: @1782864000
Sunset: Tue, 01 Jun 2027 00:00:00 GMT
Link: </api-reference/get-started/api-lifecycle>; rel="deprecation"

The Deprecation and Sunset headers are scheduled for rollout alongside this policy.

End of life behaviour

When a version reaches EOL, calls to that version return 410 Gone:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": {
    "type": "api_version_unsupported",
    "message": "This API version has reached end of life. Migrate to a supported version."
  }
}

To avoid silent breakage, always pin requests to a specific version using the X-Api-Version header rather than relying on the default.

Vocabulary

Supported is a specific lifecycle stage on this page, not a general adjective. A version in GA is actively supported but is not in the Supported stage. When referring to a version’s state, prefer the badges — GA, Supported, Deprecated, EOL — over prose. Deprecated and EOL are distinct stages. A Deprecated version still serves traffic, with deprecation signals attached to every response. An EOL version no longer serves traffic and returns 410 Gone.

API changelog
SDK lifecycle — the same model applied to the Primer SDKs.

​Lifecycle stages

​How versions move between stages

​Current status

​Machine-readable signals

​End of life behaviour

​Vocabulary

​Related