Base URL, /v1, and stability

Where the base URL comes from, why almost every route carries /v1, what the specification says about itself, and what x-stability guarantees per operation. Read the tables as a contract: Nothing stated here changes without notice.

Base URL#

The API has no fixed public address. You address the origin of your environment. The specification on this site names it as its first server under the name “Die Schnittstelle Ihrer Umgebung” (the API of your environment). The operator fills in the address at startup, which is why a self-built version still shows the placeholder https://api.szenera.com in its place. As its second server, it lists http://localhost:41000 for a local development environment. The version served by your environment (GET /v1/openapi.json) names / instead: There, its own origin is the right answer, whereas here it would be this documentation site.

In all examples on these pages, the base URL is stored in the environment variable SZENERA_API:

export SZENERA_API="https://<basis-adresse-ihrer-umgebung>"
curl -sS "$SZENERA_API/v1/me" -H "Authorization: Bearer $SZENERA_API_KEY"

Where set up, sign-in has a second host: https://auth.<your-domain>. It serves the same interface for /v1/auth/…, OAuth, SCIM and the metadata, while all other routes stay at the base URL. The sign-in endpoints will in future be named by the metadata of auth.<your-domain>, and the addresses at the base URL remain reachable until further notice.

The /v1 prefix#

Every route that Szenera itself decides on lives under /v1, and the path is part of the contract: GET /v1/scenes/{id}, POST /v1/auth/login, GET /v1/devices.

Four groups sit outside the prefix, and none of them is an oversight.

Everything that lies behind the consent, meaning the consent itself and the connected applications under GET /v1/me/connected-apps, lives under /v1 as usual. These routes are the contract of this API, not that of a third-party standard.

The specification#

Two sources:

Both sources show the same selection: the operations of the classes stable and beta. Whatever carries internal drops out, together with the schemas that were needed only there. Today that is 337 of the 780 operations, including the entire operator surface under /v1/platform/…. A client generated from it therefore gets only what your organization may also call. The full version is available to the platform operator behind its own sign-in. It does not appear on this site.

Stability per operation#

Every operation carries the extension x-stability with one of three values:

State of the current release: 372 of the 443 operations are stable, and 71 are beta: the 31 routes of advertising under /v1/advertising/… (see The areas of the reference), GET /v1/webhooks/event-types (see Fetch the event catalog through the API), the dry run POST /v1/scenes/validate (see The MCP service for AI assistants), the three routes of the render job of a scene version (POST /v1/scenes/{id}/versions/{vid}/render, GET /v1/scenes/{id}/versions/{vid}/render/{jobId}, and GET /v1/scenes/{id}/versions/{vid}/render/{jobId}/image), the five routes of the web displays, whose shape has already shifted once in this wave, the two routes of the screenshots of a display (GET /v1/players/{playerId}/screenshots and GET /v1/players/{playerId}/screenshots/{screenshotId}), the nine routes of the new analytics under /v1/analytics/ (the ad hoc analysis with catalog and output, the overview, the day and the log of a display, the content, and the delivery of an ad campaign), the eight routes of the saved views under /v1/analytics/reports, which changed shape with the new analytics, and the eleven routes of the proofs: the list, the files, and the interim statement under /v1/analytics/proofs, the links for advertisers under /v1/analytics/share-links, and the four routes of the verification page and the campaign report that need no sign-in, under /v1/public/…. No operation is currently marked deprecated.

An exception applies until beta. Until the end of alpha (end of 2026), 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. With the new analytics, five routes of the old playback analytics were dropped this way, and the saved reports changed shape and have been beta since. Details: Stability classes and sunset.

What the classes promise, how a sunset proceeds, and how a client recognizes it is described under Stability classes and sunset.

What does not exist#

• No version selection through headers or query parameters. The version is in the path.
• No separate base URL per area: All areas live under the same origin, including the paths without /v1. Sign-in is additionally reachable at the sign-in host, with the same paths.
• No second contract next to this specification: Whatever the command line, the assistant, or a portal can do, this API can do too.

When an operation is retired, it carries deprecated: true and x-sunset with the shutdown date, and its responses carry Deprecation and Sunset. Twelve months separate the announcement from the shutdown. The details are described under Stability classes and sunset. How changes to the API appear and how you compare two versions of the specification is described under Release trains, notes, and deprecations.

Related#

• Read the reference
• Your first call with curl
• Stability classes and sunset