> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API lifecycle

> How Primer versions, supports, and deprecates the Primer API.

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` | None.                      | 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`.

```mermaid theme={"dark"}
gantt
    title Example timeline (illustrative)
    dateFormat YYYY-MM-DD
    axisFormat %b %Y

    section vN
    Beta                 :vnbeta, 2025-01-01, 60d
    RC                   :vnrc,   2025-03-01, 30d
    GA                   :vnga,   2025-04-01, 365d
    Supported            :vnsup,  2026-04-01, 365d

    section vN-1
    GA                   :vmga,   2024-01-01, 455d
    Supported            :vmsup,  2025-04-01, 365d
    Deprecated           :crit, vmdep, 2026-04-01, 365d
    End of life          :milestone, vmeol, 2027-04-01, 0d

    section vN-2
    Supported            :vlsup,  2024-04-01, 365d
    Deprecated           :crit, vldep, 2025-04-01, 365d
    End of life          :milestone, vleol, 2026-04-01, 0d
```

## 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](/changelogs/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](https://www.rfc-editor.org/rfc/rfc8594).
* **`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 theme={"dark"}
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 theme={"dark"}
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`.

## Related

* [API changelog](/changelogs/api-changelog)
* [SDK lifecycle](/sdk/lifecycle) — the same model applied to the Primer SDKs.