# Stability classes and sunset

Every operation of the specification carries a class, and an operation that is being sunset announces itself in its own responses. This page says what `stable`, `beta`, and `internal` promise, how long the period between announcement and shutdown is, and how a client recognizes the sunset without anyone reading a page.

> **Type:** reference
> **For:** Anyone who operates an integration and wants to know what they can rely on and how early they learn of a shutdown.
> **Prerequisite:** None

## The three classes

Every operation carries the extension `x-stability`:

| Class | What it promises |
|---|---|
| `stable` | Path, required fields, and error codes do not change without a new version. A field can be added, none disappears. Until beta there is one exception, see [below](#until-beta-exceptions-to-the-promise). |
| `beta` | Public, but young: the shape can still move until it has survived a cycle without a breaking change. Build on it, but read the notes. |
| `internal` | Not part of the public surface. These operations are neither in the reference nor in the specification on this page. |

The class is set, not guessed: an operation without a class aborts the generation of the public version. An unclassified route therefore never appears publicly by accident, and a public one does not silently disappear either.

What `internal` carries is the inside view of the house: the operator console, the bridges to the device and the display software, the inbound endpoint of the payment provider, and diagnostics. There is nothing for an organization to call there. A call ends with `403 Permission.OperatorOnly` or does not reach you at all.

## How a sunset works

**Twelve months** pass between the announcement and the shutdown of an operation, from beta on without exception ([until then](#until-beta-exceptions-to-the-promise)).

1. **In the specification.** The operation carries `deprecated: true` and `x-sunset` with the shutdown date. If you generate a client from the specification, you see the sunset at build time, and many generators then mark the method as deprecated.
2. **In every response.** The operation keeps responding but carries three additional headers:

   ```http
   HTTP/1.1 200 OK
   Deprecation: true
   Sunset: Thu, 09 Sep 2027 00:00:00 GMT
   Link: </docs>; rel="deprecation"
   ```

3. **On the deadline.** After the date from `Sunset`, the operation no longer responds.

So even someone who has never read the specification sees the sunset: in the log of their own client.

## Until beta: exceptions to the promise

The platform is in alpha until the end of 2026. Until beta, even routes of the stability class `stable` may be dropped or broken without a sunset. Every break is listed in the change notes of the train, under “Developers”, with the route and what takes its place. From beta on, the promises above apply without exception.

The train with the new analytics made use of this:

| Route | What happened |
|---|---|
| `GET /v1/analytics/playback`, `GET /v1/players/{playerId}/playback`, `GET /v1/media/assets/{assetId}/playback` | dropped without a sunset. The new analytics replaces them: `GET /v1/analytics/overview`, `GET /v1/analytics/players/{playerId}/day` and `/plays`, `GET /v1/analytics/content`, and `POST /v1/analytics/explore` |
| `GET /v1/analytics/insights/overview`, `POST /v1/analytics/insights/report` | dropped without a sunset, replaced by the overview and the ad hoc analysis |
| `/v1/analytics/reports` and the routes below it | changed shape: The query of a report is now that of the ad hoc analysis instead of a metric of the old measurement series, and formats exist only as `csv` and `pdf`. `beta` since then |

A client generated from the specification, and `@szenera/client` from before this train, get `404` for the dropped routes and `400` for the old report forms. What changes with each train is described under [Release trains, notes, and deprecations](/changes/release-notes).

## What your client should do about it

| Rule | Why |
|---|---|
| Watch for `Deprecation` in every response and log the finding once per route | A sunset rarely hits all calls at the same time. One line per route shows exactly what you still use. |
| Record `Sunset` and turn it into a deadline | Twelve months are long enough to forget and short enough that it is then too late. |
| Do not branch on `Link` | The address leads to the reference. It is a reading aid for people, not a redirect target. |
| For `beta`, compare the specification regularly | See [Compare the specification against your version](/changes/compare-specification). |

Two guards keep the policy honest: an announcement without `x-sunset` is an error in the build, and so is an elapsed `x-sunset` on a route that still responds.

## Where to read the current state

| Source | What it says |
|---|---|
| `https://developer.szenera.com/api/openapi.json` | the public specification as of the current train, with `x-stability` and `x-sunset` per operation |
| `GET /v1/openapi.json` on your environment | the same information for the version that actually runs there |
| [What’s new in the handbook](https://szenera.com/docs/help/whats-new) | what changed in the interface with each train, newest first |
| [The status of the platform](https://szenera.com/status) | the current state, announced maintenance windows, and the latest incidents |

The class also appears in the reference on every operation, see [Read the reference](/api/read-reference).

## Related

- [Base URL, /v1, and stability](/api/base-url-and-stability)
- [Compare the specification against your version](/changes/compare-specification)
- [Release trains, notes, and deprecations](/changes/release-notes)