Skip to content
Szenera DeveloperDocs
API › Guide to the reference › Read the reference
Chapters

Read the reference

Find an operation at /api/reference, read off permission, security scheme, example, and stability, and download the specification.

5 minute readAPIUpdated: 10/25/2026

On this page

Before you start

For
Anyone who opens the reference for the first time or is looking for a specific operation.
Prerequisite
none, because the reference is public. For the call at the end, an ak_… key
Where
the reference at /api/reference on this site

This guide shows you how to find an operation in the reference at /api/reference, read off the required permission, the security scheme, the example, and the stability, and build a curl call from them.

What the reference shows

The reference is the public specification of the current release, displayed interactively: 443 operations in 19 areas and 7 groups, each operation with a short description in German, each schema with an example from a coherent demo universe. Whatever the specification lists as internal appears neither in the reference nor in the file /api/openapi.json, including the entire operator surface under /v1/platform/…, the bridges to the device and the display software, and the operational routes under /health/….

Steps

  1. In the left navigation, choose the group and, below it, the area. The seven groups are Identity & access, Organization & billing, Content & planning, Apps & marketplace, Fleet & playback, Monitoring & notifications, and Platform operations. The first six are the surface for organizations. Under Platform operations, only the two operational routes without sign-in appear here. What each area contains is described under The areas of the reference.

  2. Open the operation. The title is the short description in German (“Listet Szenen gefiltert und seitenweise”), and below it are the method and path.

  3. Read the description. It names the required permission in the form Benötigte Berechtigung: scene.list (“required permission”) and, for public routes, the sentence “Öffentlich — keine Anmeldung erforderlich” (“public, no sign-in required”). If no permission is named, the route needs only authentication.

  4. Look at the security section. It states in machine-readable form which credential the route accepts:

    Entry Credential
    apiKey API key ak_…
    oauthAccessToken access token oat_… of a delegated access grant, accepted in the same places as an API key
    sessionJwt access token of a session eyJ…
    scimToken SCIM token sct_…, only on the surface under /scim/v2
    empty list public

    Whether a key is also permitted to call the route is decided by the permission from step 3. apiKey in security only means that the credential is accepted. The surface under /scim/v2 names exclusively scimToken, and the consent of a delegated access grant and the list of connected applications name exclusively sessionJwt. The refresh cookie refresh_token appears in no list: It does not authenticate a regular request, and only POST /v1/auth/refresh reads it.

  5. Look at the example of the request schema and the response schema. Every schema carries one, and the identifiers in them (scn_…, dev_…, tnt_…) belong to the demo universe, not to your organization.

  6. Check x-stability. If it says stable, path, required fields, and error codes do not change without notice, and beta means the shape can still move. If the operation additionally carries deprecated: true and x-sunset, it is being retired, see Stability classes and sunset.

  7. Build the call from the example. For GET /v1/scenes:

    curl -sS "$SZENERA_API/v1/scenes?status=published&limit=5" \
  -H "Authorization: Bearer $SZENERA_API_KEY"

Options

You want How
The specification as a file /api/openapi.json on this site (state of the release) or GET /v1/openapi.json on your environment (exactly the running state)
Only the operations a key can reach Filter by permission: Key-capable today are asset.*, scene.*, layout-template.*, playlist.*, schedule.*, location.*, the four display permissions fleet.player.list, …read, …update, …command.issue, plus fleet.web-display.manage, advertising.*, analytics.proof.read, and analytics.proof.manage, as well as billing.usage.read and analytics.query.run, see Authentication
The errors of an operation Every operation lists 401, 403, 404, 409, 422, 429, and 502 with the seven central responses. The concrete codes are on the error code pages

Check the result

  • Every operation you open carries a short description in German, and every schema an example.
  • The call from step 7 answers 200 with items, or with an error body whose code you find on the error code pages.

If something goes wrong

Symptom Meaning Solution
The call with the identifier from the example answers 404 The examples are demo data. Insert identifiers from your organization, for example from a list.
403 Permission.OperatorOnly You called a route under /v1/platform/…, which is the operator surface. It is not in this reference. There is nothing for organizations to call there.
A route of your environment is missing although it answers It is marked internal, for example GET /health/ready or a route of the operator surface. Its description is not in the public version. In an integration, rely only on what is listed here.
POST /v1/webhooks/stripe looks like a webhook endpoint It is the inbound endpoint of the payment provider, not a customer endpoint. You create your own webhooks under Create a webhook endpoint.
A route of your environment is missing in the reference Your environment runs a different build than the release of this site. Download GET /v1/openapi.json from your environment.