Zum Inhalt springen
Szenera DeveloperHandbuch
API › Referenz-Wegweiser › Die Referenz lesen
Kapitel

Die Referenz lesen

Unter /api/reference eine Operation finden, Berechtigung, Sicherheitsverfahren, Beispiel und Stabilität ablesen und die Spezifikation herunterladen.

4 Minuten LesezeitAPIStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

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

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.

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.

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

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

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