Basis-URL, /v1 und Stabilität

Woher die Basis-Adresse kommt, warum fast jede Route /v1 trägt, was die Spezifikation über sich selbst sagt und was x-stability je Operation zusichert. Lesen Sie die Tabellen als Vertrag: Was hier steht, ändert sich nicht ohne Ankündigung.

Basis-Adresse#

Die API hat keine feste öffentliche Adresse. Sie sprechen den Ursprung Ihrer Umgebung an. Die Spezifikation auf dieser Seite nennt ihn als ersten Server unter dem Namen „Die Schnittstelle Ihrer Umgebung“ — die Adresse setzt der Betreiber beim Start ein, deshalb steht in einer selbst gebauten Fassung an ihrer Stelle noch der Platzhalter https://api.szenera.com. Als zweiten Server führt sie http://localhost:41000 für eine lokale Entwicklungsumgebung. Die Fassung an Ihrer Umgebung (GET /v1/openapi.json) nennt stattdessen / — dort ist die eigene Herkunft die richtige Antwort, hier wäre es diese Doku-Seite.

In allen Beispielen dieser Seiten steht die Basis-Adresse in der Umgebungsvariablen SZENERA_API:

export SZENERA_API="https://<basis-adresse-ihrer-umgebung>"
curl -sS "$SZENERA_API/v1/me" -H "Authorization: Bearer $SZENERA_API_KEY"

Die Anmeldung hat, wo eingerichtet, einen zweiten Wirt: https://auth.<ihre-domain>. Er bedient dieselbe Schnittstelle für /v1/auth/…, OAuth, SCIM und die Metadaten, alle anderen Routen liegen weiter an der Basis-Adresse. Die Endpunkte der Anmeldung nennen künftig die Metadaten von auth.<ihre-domain>, die Adressen an der Basis-Adresse bleiben bis auf Weiteres erreichbar.

Das Präfix /v1#

Jede Route, über die Szenera selbst entscheidet, liegt unter /v1, und der Pfad ist Teil des Vertrags: GET /v1/scenes/{id}, POST /v1/auth/login, GET /v1/devices.

Außerhalb des Präfixes liegen vier Gruppen, und keine davon ist eine Nachlässigkeit.

Alles, was hinter der Einwilligung liegt — die Einwilligung selbst, die verbundenen Anwendungen unter GET /v1/me/connected-apps —, steht regulär unter /v1: Diese Routen sind der Vertrag dieser API und nicht der eines fremden Standards.

Die Spezifikation#

Zwei Bezugsquellen:

Beide Quellen zeigen dieselbe Auswahl: die Operationen der Klassen stable und beta. Was internal trägt, fällt heraus, mitsamt den Schemata, die nur dort gebraucht wurden — heute 337 der 780 Operationen, darunter die gesamte Betreiber-Fläche unter /v1/platform/…. Ein daraus erzeugter Client bekommt damit nur, was Ihre Organisation auch aufrufen darf. Die vollständige Fassung steht dem Betreiber der Plattform hinter seiner eigenen Anmeldung zur Verfügung. Auf dieser Seite erscheint sie nicht.

Stabilität je Operation#

Jede Operation trägt die Erweiterung x-stability mit einem von drei Werten:

Stand des aktuellen Release: 372 der 443 Operationen sind stable, 71 sind beta — die 31 Routen der Werbung unter /v1/advertising/… (siehe Die Bereiche der Referenz), GET /v1/webhooks/event-types (siehe Den Ereigniskatalog über die API abrufen), der Trockenlauf POST /v1/scenes/validate (siehe Der MCP-Dienst für KI-Assistenten), die drei Wege des Render-Auftrags einer Szenen-Version (POST /v1/scenes/{id}/versions/{vid}/render, GET /v1/scenes/{id}/versions/{vid}/render/{jobId} und GET /v1/scenes/{id}/versions/{vid}/render/{jobId}/image), die fünf Routen der Web-Displays, deren Form sich mit dieser Welle bereits einmal verschoben hat, die zwei Wege der Bildschirmaufnahmen eines Displays (GET /v1/players/{playerId}/screenshots und GET /v1/players/{playerId}/screenshots/{screenshotId}), die neun Routen der neuen Auswertung unter /v1/analytics/ — die freie Auswertung mit Katalog und Ausgabe, der Überblick, Tag und Protokoll eines Displays, die Inhalte und die Lieferung einer Werbekampagne —, die acht Routen der gespeicherten Ansichten unter /v1/analytics/reports, die mit der neuen Auswertung ihre Gestalt gewechselt haben, sowie die elf Routen der Nachweise: Verzeichnis, Dateien und Zwischenstand unter /v1/analytics/proofs, die Verweise für Werbepartner unter /v1/analytics/share-links und die vier anmeldefreien Wege der Prüfseite und des Kampagnenberichts unter /v1/public/…. Keine Operation ist heute als deprecated markiert.

Bis zur Beta gilt eine Ausnahme. Bis zum Ende der Alpha (Ende 2026) dürfen auch Wege der Stabilität stable ohne Auslauf entfallen oder brechen. Jeder Bruch steht in den Änderungsnotizen des Zugs. Mit der neuen Auswertung entfielen so fünf Wege der alten Wiedergabe-Auswertung, und die gespeicherten Berichte wechselten ihre Gestalt und stehen seitdem auf beta. Einzelheiten: Stabilitätsklassen und Auslauf.

Was die Klassen zusagen, wie ein Auslauf abläuft und woran ein Client ihn erkennt, steht unter Stabilitätsklassen und Auslauf.

Was es nicht gibt#

• Keine Versionswahl über Kopfzeilen oder Abfrageparameter; die Version steht im Pfad.
• Keine eigene Basis-Adresse je Bereich: Alle Bereiche liegen unter demselben Ursprung, auch die Pfade ohne /v1. Die Anmeldung ist zusätzlich unter dem Anmelde-Wirt erreichbar, mit denselben Pfaden.
• Kein zweiter Vertrag neben dieser Spezifikation: Was die Kommandozeile, der Assistent oder ein Portal kann, kann diese API auch.

Läuft eine Operation aus, trägt sie deprecated: true und x-sunset mit dem Abschalt-Tag, und ihre Antworten tragen Deprecation und Sunset. Zwischen Ankündigung und Abschaltung liegen zwölf Monate — die Einzelheiten stehen unter Stabilitätsklassen und Auslauf. Wie Änderungen an der API erscheinen und wie Sie zwei Stände der Spezifikation vergleichen, steht unter Release-Züge, Notizen und Abkündigungen.

Weiterführendes#

• Die Referenz lesen
• Der erste Aufruf mit curl
• Stabilitätsklassen und Auslauf