Skip to main content
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.
StageBadgeSLASupportBreaking changesMinimum notice before next stage
BetaBETANone — use at own risk.Best-effort support for design partners.Allowed, documented in the changelog.—
Release CandidateRCNone — near-final quality.Priority support for testers.Unlikely, but possible.30 days before GA.
Generally AvailableGAFull 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.
SupportedSupportedReduced — security only.Critical security patches only. No new features.None — the version is frozen.12 months before end of life.
DeprecatedDeprecatedNone.None. The version still serves traffic and emits deprecation signals.None.12 months before end of life.
End of LifeEOLNone.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

VersionStageDeprecationEnd of life
v2.4GA——
v2.3Supported2026-06-012027-06-01
v2.2Supported2026-06-012027-06-01
v2.1Supported2026-06-012027-06-01
v2Supported2026-06-012027-06-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 8594.
  • Sunset response header. Companion to Deprecation. Carries the planned end-of-life date. Standardised in the same RFC.
Example response from a deprecated version: 
HTTP/1.1 200 OK
Deprecation: Mon, 01 Jun 2026 00:00:00 GMT
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.