# Die Referenz lesen

Nach dieser Anleitung finden Sie in der Referenz unter `/api/reference` eine Operation, lesen das benötigte Recht, das Sicherheitsverfahren, das Beispiel und die Stabilität ab und bauen daraus einen Aufruf mit curl.

> **Typ:** anleitung
> **Für wen:** Wer die Referenz zum ersten Mal öffnet oder eine bestimmte Operation sucht.
> **Voraussetzung:** keine — die Referenz ist öffentlich; für den Aufruf am Ende ein Schlüssel `ak_…`
> **Ort:** die Referenz unter `/api/reference` auf dieser Seite

## Was die Referenz zeigt

Die Referenz ist die öffentliche Spezifikation des aktuellen Release, interaktiv dargestellt: 443 Operationen in 19 Bereichen und 7 Gruppen, jede Operation mit deutscher Kurzbeschreibung, jedes Schema mit einem Beispiel aus einem zusammenhängenden Demo-Universum. Was die Spezifikation als `internal` führt, steht weder in der Referenz noch in der Datei `/api/openapi.json` — darunter die gesamte Betreiber-Fläche unter `/v1/platform/…`, die Brücken zu Gerät und Anzeige-Anwendung und die Betriebsrouten unter `/health/…`.

## Schritte

1. Wählen Sie in der linken Navigation die Gruppe und darunter den Bereich. Die sieben Gruppen sind **Identität & Zugang**, **Organisation & Abrechnung**, **Inhalte & Planung**, **Apps & Marketplace**, **Flotte & Wiedergabe**, **Überwachung & Meldungen** und **Plattform-Betrieb**. Die ersten sechs sind die Fläche für Organisationen; unter **Plattform-Betrieb** stehen hier nur die beiden anmeldefreien Betriebsrouten. Was jeder Bereich enthält, steht unter [Die Bereiche der Referenz](/de/api/reference-areas).

2. Öffnen Sie die Operation. Der Titel ist die deutsche Kurzbeschreibung („Listet Szenen gefiltert und seitenweise“), darunter stehen Methode und Pfad.

3. Lesen Sie die Beschreibung. Sie nennt das benötigte Recht in der Form **Benötigte Berechtigung:** `scene.list` und bei öffentlichen Routen den Satz „Öffentlich — keine Anmeldung erforderlich“. Fehlt ein Recht, braucht die Route nur eine Anmeldung.

4. Sehen Sie den Abschnitt `security` an. Er sagt maschinenlesbar, welcher Ausweis die Route annimmt:

   | Eintrag | Ausweis |
   |---|---|
   | `apiKey` | API-Schlüssel `ak_…` |
   | `oauthAccessToken` | Zugriffstoken `oat_…` eines [delegierten Zugangs](/de/api/oauth-delegated-access), angenommen an denselben Stellen wie ein API-Schlüssel |
   | `sessionJwt` | Zugriffstoken einer Sitzung `eyJ…` |
   | `scimToken` | SCIM-Zugang `sct_…`, nur auf der Fläche unter `/scim/v2` |
   | leere Liste | öffentlich |

   Ob ein Schlüssel die Route auch fachlich darf, entscheidet das Recht aus Schritt 3 — `apiKey` in `security` heißt nur, dass der Ausweis angenommen wird. Die Fläche unter `/scim/v2` nennt ausschließlich `scimToken`, die Einwilligung eines delegierten Zugangs und die Liste der verbundenen Anwendungen ausschließlich `sessionJwt`. Das Erneuerungs-Cookie `refresh_token` steht in keiner Liste: Es weist keine fachliche Anfrage aus, nur `POST /v1/auth/refresh` liest es.

5. Sehen Sie das Beispiel des Anfrage- und des Antwortschemas an. Jedes Schema trägt eines; die Kennungen darin (`scn_…`, `dev_…`, `tnt_…`) gehören zum Demo-Universum, nicht zu Ihrer Organisation.

6. Prüfen Sie `x-stability`. Steht dort `stable`, ändern sich Pfad, Pflichtfelder und Fehlercodes nicht ohne Ankündigung; `beta` heißt, die Form kann sich noch bewegen. Trägt die Operation zusätzlich `deprecated: true` und `x-sunset`, läuft sie aus — siehe [Stabilitätsklassen und Auslauf](/de/changes/stability-and-sunset).

7. Bauen Sie den Aufruf aus dem Beispiel. Für `GET /v1/scenes`:

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

## Optionen

| Sie wollen | So |
|---|---|
| Die Spezifikation als Datei | `/api/openapi.json` auf dieser Seite (Stand des Release) oder `GET /v1/openapi.json` an Ihrer Umgebung (genau der laufende Stand) |
| Nur die Operationen, die ein Schlüssel erreicht | Nach dem Recht filtern: schlüsselfähig sind heute `asset.*`, `scene.*`, `layout-template.*`, `playlist.*`, `schedule.*`, `location.*`, die vier Display-Rechte `fleet.player.list`, `…read`, `…update`, `…command.issue`, dazu `fleet.web-display.manage`, `advertising.*`, `analytics.proof.read` und `analytics.proof.manage` sowie `billing.usage.read` und `analytics.query.run` — siehe [Anmeldung](/de/api/authentication) |
| Die Fehler einer Operation | Jede Operation listet 401, 403, 404, 409, 422, 429 und 502 mit den sieben zentralen Antworten; die konkreten Codes stehen auf den Fehlercode-Seiten |

## Ergebnis prüfen

- Jede Operation, die Sie öffnen, trägt eine deutsche Kurzbeschreibung, und jedes Schema ein Beispiel.
- Der Aufruf aus Schritt 7 antwortet `200` mit `items` — oder mit einem Fehlerrumpf, dessen `code` Sie auf den Fehlercode-Seiten finden.

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| Der Aufruf mit der Kennung aus dem Beispiel antwortet `404` | Die Beispiele sind Demo-Daten. | Kennungen aus Ihrer Organisation einsetzen — etwa aus einer Liste. |
| `403 Permission.OperatorOnly` | Sie haben eine Route unter `/v1/platform/…` gerufen — die Betreiber-Fläche. | Sie steht nicht in dieser Referenz; für Organisationen gibt es dort nichts zu rufen. |
| Eine Route Ihrer Umgebung fehlt, obwohl sie antwortet | Sie ist als `internal` geführt — etwa `GET /health/ready` oder eine Route der Betreiber-Fläche. | Ihre Beschreibung steht nicht in der öffentlichen Fassung; verlassen Sie sich in einer Integration nur auf das, was hier steht. |
| `POST /v1/webhooks/stripe` sieht aus wie ein Webhook-Endpunkt | Es ist der Eingang des Zahlungsdienstleisters, kein Kunden-Endpunkt. | Eigene Webhooks legen Sie unter [Einen Webhook-Endpunkt anlegen](/de/webhooks/create-endpoint) an. |
| Eine Route Ihrer Umgebung fehlt in der Referenz | Ihre Umgebung läuft auf einem anderen Stand als das Release dieser Seite. | `GET /v1/openapi.json` Ihrer Umgebung laden. |

## Weiterführendes

- [Die Bereiche der Referenz](/de/api/reference-areas)
- [Basis-URL, /v1 und Stabilität](/de/api/base-url-and-stability)
- [Einen eigenen Client aus der Spezifikation erzeugen](/de/api/generate-client)