Release trains, notes, and deprecations
How a release train comes about, how its notes are structured, what is attached to the release, and what applies to deprecations today.
7 minute readChangesUpdated: 10/25/2026
On this page
Before you start
- For
- Anyone who operates an integration and wants to know in what form changes to the API are announced.
- Prerequisite
- None. The specification at
https://developer.szenera.com/api/openapi.jsonis reachable without signing in.
The API changes in trains: a train bundles the versions of the services on one date, and each train gets a note that lists breaking changes before anything else. This page says how both are structured, where the notes are today, and what applies to deprecations.
The release train
A train is a cut through time, not a version contract. It therefore carries no major, minor, or patch of its own but its date.
| Attribute | What applies |
|---|---|
| Name | release/YYYY-MM-DD, with several trains on the same day release/YYYY-MM-DD.2 (a .1 never exists) |
| What it carries | the services of the platform: the API, the portal, Szenera Ops, the home page, and the display software of the displays |
| Versions | each service carries its own number (such as 0.4.14). The train lists only those services as moved whose number has risen since the last train. The others appear as unchanged in the note |
| When a train is due | as soon as the version of one of these services is above that of the last train. In practice, this happens when the collected change notes become new versions |
| What the train ships | the same images that ran on staging before. They are not rebuilt, only labeled with their version |
| What does not travel in the train | the operating system of the players. It follows its own cycle and its own triggers, and so does the display extension for the browser. Libraries such as the API client and the Apps SDK, and the apps, travel along in the services. The note lists their versions under “Packages” |
GET /health/version returns the version of the service that responds in your environment, without signing in, with the fields service, version, builtAt, and environment. In production, version holds only the number (0.4.1). On all other environments, the short commit hash of the build is appended (0.4.1+a1b2c3d). Outside a release image, the route reports unknown or a number with the suffix -dev. The route is limited to 60 calls per minute and address.
The specification itself carries a number of its own in info.version. It is an operator setting with the default 1.0.0 and does not move with every train. What has changed is therefore reliably visible only in the content of the specification, not in this number. How to compare the content is described in Compare the specification against your version.
How a release note is structured
The text of a release note comes from the change notes that every change to the platform brings along. Whoever writes a change adds a note for it and writes lines in it per package, each with a kind and an audience: for customers, for operations, or for developers. The release note of a train is addressed to operations. It names the breaking changes and the steps of deployment, and for customers and developers it refers to their pages. It does not claim what nobody wrote down.
| Part | Content |
|---|---|
| Title | Szenera <date> |
| Breaking changes | for each breaking change for developers and operations, one line with the package, the upgrade step, and a link to the change that brought it |
| Deployment | the steps for operations, numbered continuously: first before deploying, then while deploying, then after |
| For customers | the link to the changes page of the handbook and the number of apps that explain their new features in the store |
| For developers | the link to the change list per package and to the package page of the developer site |
| Packages | libraries, apps, and extension whose version rises with the train, with the version before |
| Delivery | a table Service · Version · Before · Digest over all services of the train |
| Comparison | a link to all changes since the last train |
A train without a single change note says so in one sentence and lists only the versions.
What a breaking change is
A breaking change is a change that forces you to act: a path that disappears or moves, a new required field, a different error code. It is marked in the note itself: the line carries breaking and names the upgrade step, and the level of the package rises. As long as the first digit of a version is 0, the second digit is the boundary for breaking changes: 0.4.21 to 0.5.0 is a breaking change, 0.4.21 to 0.4.22 is not. What to do appears as the upgrade step, word for word as the author wrote it. A shortened instruction would be a wrong one.
A breaking change appears at the very top, in the Breaking changes section. For the packages, the change list also shows it: there it appears under Breaking changes, see Packages and their versions.
What is attached to the release
| Attachment | Content |
|---|---|
manifest.json |
the train in machine-readable form: services, versions, digests, risen packages, consumed change notes |
openapi.json |
the specification as of this train |
| two SBOMs (CycloneDX) | the bills of materials of the dependencies from the same state |
SHA256SUMS |
checksums over all attachments |
A missing attachment does not hold up the train. The bills of materials are created in a separate run that can be slower than the train. If something is missing, the note says so in one line: “Not attached: … — could not be obtained in the run”.
Where the notes are today
The notes are created as a release entry in the source code archive of the platform. This archive is not public, and this page lists no entries from it. Five things are reliably reachable without signing in:
| Source | What it says |
|---|---|
https://developer.szenera.com/api/openapi.json |
the specification as of the current train |
GET /v1/openapi.json of your environment |
the specification of the version that actually runs there. The response may be cached for five minutes (Cache-Control: public, max-age=300) |
| Packages and their versions | version and change list of the API client, Apps SDK, CLI, and contracts, section for developers |
| What’s new in the handbook | what changed in the interface with each train, newest first, without signing in |
| The status of the platform | the current state, announced maintenance windows, and the latest incidents |
Both versions of the specification can differ if your environment runs an older train. A comparison of the two files is therefore the way to recognize a change reliably.
What applies to deprecations
| Question | Status today |
|---|---|
| How is an operation marked? | Every operation carries x-stability with stable, beta, or internal. Today, 372 of the 443 public operations are stable. |
What does stable mean? |
Path, required fields, and error codes do not change without a new version. A field can be added, none disappears. |
| Are there deprecated operations? | None today. If one were added, it would carry deprecated: true and x-sunset in the description as well as Deprecation, Sunset, and Link in every response. |
| Is there a procedure with deadlines? | Yes: twelve months pass between announcement and shutdown. The details are under Stability classes and sunset. |
| How do I recognize a change that affects me? | It appears in the note under Breaking changes, at the very top, with the required action verbatim, and it shows in the comparison of the specifications. |
| What about routes I cannot find in the reference? | Routes marked internal are not part of the public surface. They appear in no file on this page and in no promise. |