# Read the reference

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.

> **Type:** guide
> **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

## 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](/api/reference-areas).

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](/api/oauth-delegated-access), 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](/changes/stability-and-sunset).

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

   ```bash
   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](/api/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](/webhooks/create-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. |

## Related

- [The areas of the reference](/api/reference-areas)
- [Base URL, /v1, and stability](/api/base-url-and-stability)
- [Generate your own client from the specification](/api/generate-client)