# 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.

> **Type:** reference
> **For:** Anyone who enters the first address into a configuration or wants to know what a client can rely on.
> **Prerequisite:** the base URL of your environment, which is the origin your portal also talks to

## 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 `__SZENERA_API_BASE_URL__` 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.

| What | Value |
|---|---|
| Base URL | the origin of your environment, e.g., `https://api.<your-domain>` |
| Path prefix | `/v1` on every route |
| Transport | HTTPS. Request and response bodies as JSON |
| Example | `GET $SZENERA_API/v1/me` |

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

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

| Path | Why without `/v1` |
|---|---|
| `/scim/v2/…` | The path belongs to a third-party protocol (RFC 7644), which carries its own version. A directory service validates its data against the address it talks to, and a prefix in front would break that. See [Provisioning with SCIM 2.0](/api/scim-provisioning). |
| `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource` | RFC 8414 and RFC 9728 define these addresses literally. A third-party client looks there and nowhere else. |
| `/oauth/register`, `/oauth/authorize`, `/oauth/token`, `/oauth/revoke` | the endpoints of the standard, see [Delegated access with OAuth 2.1](/api/oauth-delegated-access) |
| `GET /health/live`, `GET /health/ready`, `GET /health/version`, `GET /metrics` | operational routes that need no sign-in. They describe the state of an environment, not your inventory, and are therefore not part of the public specification either |

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

| Detail | Value |
|---|---|
| Format | OpenAPI `3.1.0` |
| `info.title` | `Szenera API` |
| `info.version` | `1.0.0` |
| Operations | 443 on 346 paths |
| Areas (tags) | 19 in 7 groups, see [The areas of the reference](/api/reference-areas) |
| Schemas with example | 741 of 741 |

Two sources:

| Source | Content | Access |
|---|---|---|
| `/api/openapi.json` on this site | the current release, **without** the operations marked `internal` | no sign-in required |
| `GET /v1/openapi.json` on your environment | the same public version, for the build that is actually running there | no sign-in required. `Cache-Control: public, max-age=300`, so it can be cached for five minutes |

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:

| Value | Meaning |
|---|---|
| `stable` | Path, required fields, and error codes do not change without a new version. |
| `beta` | Public but young: The shape can still move until it has survived one cycle without a breaking change. |
| `internal` | Not part of the public surface. Appears only in the operator’s version and therefore in no file on this site. |

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](/api/reference-areas)), `GET /v1/webhooks/event-types` (see [Fetch the event catalog through the API](/webhooks/fetch-event-catalog)), the dry run `POST /v1/scenes/validate` (see [The MCP service for AI assistants](/api/mcp-service)), 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](/api/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](/changes/stability-and-sunset#until-beta-exceptions-to-the-promise).

What the classes promise, how a sunset proceeds, and how a client recognizes it is described under [Stability classes and sunset](/changes/stability-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](/changes/stability-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](/changes/release-notes).

## Related

- [Read the reference](/api/read-reference)
- [Your first call with curl](/getting-started/first-call)
- [Stability classes and sunset](/changes/stability-and-sunset)