# Szenera Developer

> Die Entwicklerdokumentation der Digital-Signage-Plattform Szenera (HKNovaTech UG (haftungsbeschränkt), Ahrensburg): HTTP-API unter `/v1`, die Kommandozeile `szenera`, das Apps-SDK und Webhooks. Sie richtet sich an Entwicklerinnen und Entwickler, die Szenera aus eigenen Systemen ansprechen — vom ersten Aufruf bis zur laufenden Integration. Bedienanleitungen für das Portal stehen nicht hier, sondern unter https://szenera.com/de/docs.

Kernpunkte:
- Die API ist OpenAPI 3.1 und liegt unter `/v1`; angemeldet wird mit einem API-Schlüssel aus dem Portal.
- Auf jeder Route gelten dieselben Regeln: ein einheitliches Fehlerformat, ETag/If-Match für sicheres Ändern, `Idempotency-Key` für wiederholbare Schreibvorgänge, Rate-Limits und Blättern über `limit`/`cursor`.
- Die vollständige Referenz steht unter https://developer.szenera.com/api/reference, die Spezifikation als Datei unter https://developer.szenera.com/api/openapi.json.
- Webhooks tragen Ereignisse der Organisation nach außen; die Zustellung ist über HMAC signiert und wird bei Fehlern wiederholt.
- Jede Seite dieser Fläche gibt es zusätzlich als Markdown-Zwilling: eine Blattseite unter ihrer eigenen Adresse mit der Endung `.md` (`/de/api/error-format` → `/de/api/error-format.md`), eine Bereichsübersicht und die Startseite unter `<adresse>/index.md` (`/de/api` → `/de/api/index.md`, die Startseite → `/de/index.md`).
- Dieselbe Dokumentation auf Englisch liegt in der Wurzel (`https://developer.szenera.com/llms.txt` ist ihre Seitenliste).

## Maschinenlesbar

- [OpenAPI-Spezifikation](https://developer.szenera.com/api/openapi.json): die öffentliche Mandanten-API als OpenAPI-3.1-Dokument — die Quelle, aus der die Referenz und jeder erzeugte Client entstehen.
- [API-Referenz](https://developer.szenera.com/api/reference): dieselbe Spezifikation als lesbare Oberfläche.
- [Abschnitts-Index der Suche](https://developer.szenera.com/de/search.json): je Überschrift ein Eintrag mit Bereich, Seite und Sprungmarke.

## Seiten

Alle Seiten in kuratierter Reihenfolge. Jede gibt es zusätzlich als Markdown-Zwilling — derselbe Text ohne Rahmen, ohne Navigation und ohne Skript.

- [Entwickeln mit Szenera](https://developer.szenera.com/de): API, CLI, Apps-SDK und Webhooks von Szenera: Schlüssel erzeugen, Aufrufe absetzen, Ereignisse empfangen — und die Regeln, die auf jeder Route gelten. — Markdown: https://developer.szenera.com/de/index.md
- [Erste Schritte](https://developer.szenera.com/de/getting-started): Vom API-Schlüssel zum ersten Aufruf: Schlüssel erzeugen, mit curl anfragen, Antworten lesen und Wiederholungen von Anfang an absichern. — Markdown: https://developer.szenera.com/de/getting-started/index.md
- [Wie läuft ein Aufruf durch die Plattform?](https://developer.szenera.com/de/getting-started/about-request-flow): Von der Bearer-Kopfzeile über die Rechteprüfung bis zur Antwort mit Trace-Kennung: die Stationen, die jeder Aufruf durchläuft. — Markdown: https://developer.szenera.com/de/getting-started/about-request-flow.md
- [Einen API-Schlüssel erzeugen](https://developer.szenera.com/de/getting-started/create-api-key): Im Portal unter Einstellungen › Organisation › API-Schlüssel einen Schlüssel mit Klasse, Rechten und Ablauf anlegen — der Klartext erscheint genau einmal. — Markdown: https://developer.szenera.com/de/getting-started/create-api-key.md
- [Der erste Aufruf mit curl](https://developer.szenera.com/de/getting-started/first-call): Mit Schlüssel und curl GET /v1/me und GET /v1/playlists aufrufen, die Antwort und ihre Kopfzeilen ansehen — in fünf Minuten. — Markdown: https://developer.szenera.com/de/getting-started/first-call.md
- [Was eine Antwort enthält](https://developer.szenera.com/de/getting-started/response-contents): Status, Kopfzeilen, Listenform, Kennungen mit Präfix und der Fehlerrumpf — alles, was in einer Antwort der API steckt, in Tabellen. — Markdown: https://developer.szenera.com/de/getting-started/response-contents.md
- [Idempotenz von Anfang an](https://developer.szenera.com/de/getting-started/idempotency): Verändernde Aufrufe mit Idempotency-Key absichern, damit eine Wiederholung nach Netzabbruch keinen zweiten Vorgang erzeugt. — Markdown: https://developer.szenera.com/de/getting-started/idempotency.md
- [Wenn der erste Aufruf scheitert](https://developer.szenera.com/de/getting-started/troubleshooting): 401, 403, 404, 422, 429 und Netzfehler beim ersten Aufruf: was der Code bedeutet und welche Seite den Weg zurück zeigt. — Markdown: https://developer.szenera.com/de/getting-started/troubleshooting.md
- [API](https://developer.szenera.com/de/api): Die Regeln, die auf jeder Route gelten — Adresse, Anmeldung, Fehler, Sperren, Blättern, Stabilität —, die Zugänge für fremde Anwendungen… — Markdown: https://developer.szenera.com/de/api/index.md
- [Basis-URL, /v1 und Stabilität](https://developer.szenera.com/de/api/base-url-and-stability): Woher die Basis-Adresse kommt, warum fast jede Route /v1 trägt, welche Pfade außerhalb liegen und was x-stability je Operation zusagt. — Markdown: https://developer.szenera.com/de/api/base-url-and-stability.md
- [Anmeldung: Schlüssel und Sitzungen](https://developer.szenera.com/de/api/authentication): Bearer-Kopfzeile, Schlüssel-Präfixe, Rechteumfang, Ablauf und Rotation eines Schlüssels — und wann eine Sitzung statt eines Schlüssels sinnvoll ist. — Markdown: https://developer.szenera.com/de/api/authentication.md
- [Das Fehlerformat](https://developer.szenera.com/de/api/error-format): Der Fehlerrumpf mit code, message und traceId, die RFC-9457-Form und die Regel, nach der aus einem Code der HTTP-Status wird. — Markdown: https://developer.szenera.com/de/api/error-format.md
- [Gleichzeitige Änderungen: ETag und If-Match](https://developer.szenera.com/de/api/etag-and-if-match): Eine versionierte Ressource lesen, die Version als If-Match zurückschicken und einen 409-Konflikt sauber auflösen. — Markdown: https://developer.szenera.com/de/api/etag-and-if-match.md
- [Drosselung und Rate-Limit-Kopfzeilen](https://developer.szenera.com/de/api/rate-limits): Welche Routen eine eigene Grenze haben, welches Kontingent an einem Schlüssel hängt, was die vier Kopfzeilen bedeuten und wie ein Client auf 429 reagiert. — Markdown: https://developer.szenera.com/de/api/rate-limits.md
- [Blättern: limit, cursor, items, nextCursor](https://developer.szenera.com/de/api/pagination): Cursor-Blättern auf allen Listen, die Grenzen 50/200 und 25/100, die vier Routen mit page — und wie die CLI mit --all allen Seiten folgt. — Markdown: https://developer.szenera.com/de/api/pagination.md
- [Delegierter Zugang mit OAuth 2.1](https://developer.szenera.com/de/api/oauth-delegated-access): Ihre Anwendung läuft bei fremden Kunden: registrieren, mit PKCE einwilligen lassen, Token oat_ tauschen, erneuern, widerrufen. — Markdown: https://developer.szenera.com/de/api/oauth-delegated-access.md
- [Provisionierung mit SCIM 2.0](https://developer.szenera.com/de/api/scim-provisioning): Ein Verzeichnisdienst soll Konten anlegen, sperren und Rollen setzen: Zugang sct_, Endpunkte unter /scim/v2, Abbildung und Fehler. — Markdown: https://developer.szenera.com/de/api/scim-provisioning.md
- [Der MCP-Dienst für KI-Assistenten](https://developer.szenera.com/de/api/mcp-service): Ein Assistent soll mit Ihrem Bestand arbeiten: Adresse, Anmeldung, Werkzeugliste, Bestätigungspflicht, Grenzen und Fehler. — Markdown: https://developer.szenera.com/de/api/mcp-service.md
- [Standorte](https://developer.szenera.com/de/api/locations): Eine Filialstruktur spiegeln: Felder eines Standorts, seine Routen, die Zuordnung eines Displays und die Auswertung nach Orten. — Markdown: https://developer.szenera.com/de/api/locations.md
- [Web-Displays](https://developer.szenera.com/de/api/web-displays): Ein Display anlegen, hinter dem kein Gerät steht: Routen, Anschluss-Adresse, die beiden Zustände, Löschen und die Grenzen gegenüber einem Gerät. — Markdown: https://developer.szenera.com/de/api/web-displays.md
- [Fehlercodes: auf jeder Route möglich](https://developer.szenera.com/de/api/error-codes-general): Die plattformweiten Codes für Anmeldung, Rechte, Validierung, Konflikte, Sperren, Nutzlast, HTTP, Ereignisse, Zwischenspeicher, Jobs und Ressourcen. — Markdown: https://developer.szenera.com/de/api/error-codes-general.md
- [Fehlercodes: Konten und Sitzungen](https://developer.szenera.com/de/api/error-codes-accounts): Die Codes der Bereiche Identity und Sessions: Benutzerkonten, Schlüssel, Einladungen, Anmeldung, zweiter Faktor, Sitzungen. — Markdown: https://developer.szenera.com/de/api/error-codes-accounts.md
- [Fehlercodes: Organisation, Zugang, Beitritt](https://developer.szenera.com/de/api/error-codes-organization): Die Codes der Bereiche Tenancy, Access, Onboarding und Cloud-Connections: Stammdaten, Domain, Rollen, Erteilungen, Registrierung, Speicher-Verbindungen. — Markdown: https://developer.szenera.com/de/api/error-codes-organization.md
- [Fehlercodes: Abrechnung](https://developer.szenera.com/de/api/error-codes-billing): Die Codes des Bereichs Billing: Paket, Lizenzen, Zubuchungen, Zahlungsmittel, Rechnungen — und warum hier 402 steht. — Markdown: https://developer.szenera.com/de/api/error-codes-billing.md
- [Fehlercodes: Medien, Szenen, Programme, Apps](https://developer.szenera.com/de/api/error-codes-content): Die Codes der Bereiche Media-Library, Composition, Scheduling, App-Catalog, Marketplace, App-Runtime und Advertising. — Markdown: https://developer.szenera.com/de/api/error-codes-content.md
- [Fehlercodes: Geräte, Wiedergabe, Meldungen, Betrieb](https://developer.szenera.com/de/api/error-codes-devices-operations): Die Codes der Bereiche Fleet, Playback, Realtime, Notifications, Analytics, Audit und Ops-Console — letztere nur auf Betreiberrouten. — Markdown: https://developer.szenera.com/de/api/error-codes-devices-operations.md
- [Fehlercodes: Serverfehler (5xx)](https://developer.szenera.com/de/api/error-codes-server): Die 119 Codes, auf die ein Client nicht fachlich reagieren kann: Invarianten, Start, Datenbank, nachgelagerte Dienste — wiederholen oder melden. — Markdown: https://developer.szenera.com/de/api/error-codes-server.md
- [Die Referenz lesen](https://developer.szenera.com/de/api/read-reference): Unter /api/reference eine Operation finden, Berechtigung, Sicherheitsverfahren, Beispiel und Stabilität ablesen und die Spezifikation herunterladen. — Markdown: https://developer.szenera.com/de/api/read-reference.md
- [Die Bereiche der Referenz](https://developer.szenera.com/de/api/reference-areas): Die 19 Tags der Spezifikation in ihren 7 Gruppen mit je einem Satz Zweck — und warum die Betreiber-Fläche nicht dazugehört. — Markdown: https://developer.szenera.com/de/api/reference-areas.md
- [Einen eigenen Client aus der Spezifikation erzeugen](https://developer.szenera.com/de/api/generate-client): Es gibt heute keinen veröffentlichten Client: So erzeugen Sie aus openapi.json Ihren eigenen und bilden die Konventionen der API darin ab. — Markdown: https://developer.szenera.com/de/api/generate-client.md
- [CLI](https://developer.szenera.com/de/cli): Die Kommandozeile szenera: Profile, Ausweis, 136 Befehle, JSON-Ausgabe und Exit-Codes — und was heute beim Bezug gilt. — Markdown: https://developer.szenera.com/de/cli/index.md
- [Die CLI beziehen](https://developer.szenera.com/de/cli/get-cli): Wie Sie die CLI heute bekommen: kein npm-Paket, kein Download — die CLI wird aus dem Quellbaum der Plattform gebaut; ohne Zugang bleibt die API. — Markdown: https://developer.szenera.com/de/cli/get-cli.md
- [Profile und Ausweis](https://developer.szenera.com/de/cli/profiles-and-credentials): Ein Profil mit Umgebung, Ausweisart und Schreibschutz anlegen — als Datei oder nur mit Umgebungsvariablen — und mit whoami prüfen. — Markdown: https://developer.szenera.com/de/cli/profiles-and-credentials.md
- [Befehle für Ihre Organisation](https://developer.szenera.com/de/cli/commands-organization): Alle Befehle von szenera, die mit einem Schlüssel oder Konto Ihrer Organisation laufen: Medien, Szenen, Playlisten, Programme, Geräte, Team, Apps, Abo. — Markdown: https://developer.szenera.com/de/cli/commands-organization.md
- [Befehle für den Plattformbetrieb](https://developer.szenera.com/de/cli/commands-platform-operations): Die Befehle des internen Werkzeugs szenera-ops, die nur mit einem Betreiber-Profil laufen: Geräte-Software, Approvals, Störungen, Warteschlangen… — Markdown: https://developer.szenera.com/de/cli/commands-platform-operations.md
- [Ausgabe als JSON und Exit-Codes](https://developer.szenera.com/de/cli/output-and-exit-codes): JSON ohne Hülle auf der Standardausgabe, Fehler nur auf der Fehlerausgabe, --raw bei Vertragsbrüchen und die 13 Exit-Codes von 0 bis 12. — Markdown: https://developer.szenera.com/de/cli/output-and-exit-codes.md
- [Skripte und CI](https://developer.szenera.com/de/cli/scripts-and-ci): Ohne Profildatei mit Umgebungsvariablen arbeiten, Exit-Codes auswerten, Listen vollständig holen, Wartezeiten begrenzen und Wiederholungen absichern. — Markdown: https://developer.szenera.com/de/cli/scripts-and-ci.md
- [Wenn die CLI abbricht](https://developer.szenera.com/de/cli/troubleshooting): Unbekannter Befehl, Profil gesperrt, 401 trotz Schlüssel, Antwort widerspricht dem Vertrag, Exit 11 oder 12 — Symptom, Bedeutung, Lösung. — Markdown: https://developer.szenera.com/de/cli/troubleshooting.md
- [Webhooks](https://developer.szenera.com/de/webhooks): Ereignisse Ihrer Organisation an Ihre Systeme: Endpunkt anlegen, Signatur prüfen, Wiederholungen verstehen, Ereignistypen nachschlagen und den Katalog… — Markdown: https://developer.szenera.com/de/webhooks/index.md
- [Wie wird ein Webhook zugestellt?](https://developer.szenera.com/de/webhooks/about-delivery): Vom Ereignis über den Abgleich mit Ihren Endpunkten, die Signatur und den Versand bis zu Wiederholung oder Abschaltung. — Markdown: https://developer.szenera.com/de/webhooks/about-delivery.md
- [Was gesendet wird und wie wiederholt wird](https://developer.szenera.com/de/webhooks/delivery-and-retries): Die Anfrage an Ihren Endpunkt (Methode, Kopfzeilen, Rumpf), die Zustände einer Zustellung, das Wiederholungsschema und die Abschaltung. — Markdown: https://developer.szenera.com/de/webhooks/delivery-and-retries.md
- [Einen Webhook-Endpunkt anlegen](https://developer.szenera.com/de/webhooks/create-endpoint): Unter Einstellungen › Organisation › Webhooks eine https-Adresse und die abonnierten Ereignisse eintragen und das Signatur-Secret sicher übernehmen. — Markdown: https://developer.szenera.com/de/webhooks/create-endpoint.md
- [Die Signatur einer Zustellung prüfen](https://developer.szenera.com/de/webhooks/verify-signature): HMAC-SHA256 über den rohen Rumpf nachrechnen, in konstanter Zeit mit X-Signature vergleichen, nach X-Delivery-Id entdoppeln und das Secret rotieren. — Markdown: https://developer.szenera.com/de/webhooks/verify-signature.md
- [Ereignistypen: Organisation, Konten, Abrechnung](https://developer.szenera.com/de/webhooks/event-types-organization): Die abonnierbaren Ereignistypen aus Organisation, Speicher-Verbindungen, Zugang, Konten und delegiertem Zugang, Sitzungen, Abrechnung und Beitritt mit… — Markdown: https://developer.szenera.com/de/webhooks/event-types-organization.md
- [Ereignistypen: Inhalte, Programme, Geräte, Apps](https://developer.szenera.com/de/webhooks/event-types-content-devices): Die abonnierbaren Ereignistypen aus Medien, Szenen, Programmen, Marktplatz, Flotte, App-Laufzeit, Wiedergabe, Auswertung und Werbung, dazu die Typen der… — Markdown: https://developer.szenera.com/de/webhooks/event-types-content-devices.md
- [Den Ereigniskatalog über die API abrufen](https://developer.szenera.com/de/webhooks/fetch-event-catalog): Sie legen Endpunkte aus einem eigenen System an oder zeigen die Auswahl in Ihrer Oberfläche: den Katalog als JSON holen, eine Ereignis-Liste prüfen… — Markdown: https://developer.szenera.com/de/webhooks/fetch-event-catalog.md
- [Wenn keine Zustellung ankommt](https://developer.szenera.com/de/webhooks/troubleshooting): Endpunkt abgelehnt, inaktiv nach Fehlschlägen, keine Wiederholung nach 4xx, Signatur passt nicht, doppelte Zustellungen, Ereignis tritt nie ein. — Markdown: https://developer.szenera.com/de/webhooks/troubleshooting.md
- [Apps-SDK](https://developer.szenera.com/de/apps-sdk): Wie eine App gebaut ist — Manifest, Widget, Server-Teil, Datenzugriff, Signatur — und wie sie in den Katalog und auf den Bildschirm kommt. Der ganze Weg… — Markdown: https://developer.szenera.com/de/apps-sdk/index.md
- [Von der Vorlage bis zur Freigabe](https://developer.szenera.com/de/apps-sdk/template-to-release): Der ganze Weg einer neuen App: mit pnpm app:new aus der Vorlage anlegen, Widget, Config, Texte und Bilder schreiben, mit pnpm app:check prüfen, testen… — Markdown: https://developer.szenera.com/de/apps-sdk/template-to-release.md
- [Eine App im neuen Standard](https://developer.szenera.com/de/apps-sdk/new-app-standard): Eine App auf Vorlagen mit Größe, Formate, Passt-Bericht, Flächen und das deklarative Formular umstellen, mit der Wetter-App als Beispiel — dazu… — Markdown: https://developer.szenera.com/de/apps-sdk/new-app-standard.md
- [Was ist eine App, und wie kommt sie auf den Bildschirm?](https://developer.szenera.com/de/apps-sdk/about-apps): Vom Manifest über Release, Kanäle und Installation bis zum signierten Bündel auf dem Gerät: der Lebensweg einer App in einem Bild. — Markdown: https://developer.szenera.com/de/apps-sdk/about-apps.md
- [Das Manifest](https://developer.szenera.com/de/apps-sdk/manifest): Jedes Feld des App-Manifests mit Pflicht, Format und Wirkung — von id und version bis legal, unlocks und connects. — Markdown: https://developer.szenera.com/de/apps-sdk/manifest.md
- [Widget, Konfiguration und Vorschau](https://developer.szenera.com/de/apps-sdk/widget-and-preview): defineWidget mit configSchema und noResolver, Formate (useWidgetFormat), Vorschau-Varianten mit Größe für Katalog und Miniaturen sowie Vorschau-Zustände… — Markdown: https://developer.szenera.com/de/apps-sdk/widget-and-preview.md
- [Widgets konfigurieren](https://developer.szenera.com/de/apps-sdk/configure-widgets): Den Widget-Katalog lesen: configSchema als JSON-Schema, Pflichtfelder, Beispiele — und je eingebautem Baustein eine fertige Widget-Instanz. — Markdown: https://developer.szenera.com/de/apps-sdk/configure-widgets.md
- [Server-Teil: Resolver, Fetcher und Jobs](https://developer.szenera.com/de/apps-sdk/backend): Die drei Decorator @WidgetResolver, @Fetcher und @JobHandler, ihre Regeln und die Fähigkeiten, die der Server-Teil einer App über Token bezieht. — Markdown: https://developer.szenera.com/de/apps-sdk/backend.md
- [Datenzugriff, Rechte und Bedingungen](https://developer.szenera.com/de/apps-sdk/data-access): dataAccess (reads, external, retention), Rechte für Team und Betreiber, unlocks und connects, der legal-Block: was eine App vor der Installation offenlegt. — Markdown: https://developer.szenera.com/de/apps-sdk/data-access.md
- [Signieren und der Weg in den Katalog](https://developer.szenera.com/de/apps-sdk/signing-and-catalog): Was an einem Release liegt, sha256 und Ed25519-Signatur, die Politik am Gerät, Kanäle canary → beta → stable — und wer heute Releases anlegt. — Markdown: https://developer.szenera.com/de/apps-sdk/signing-and-catalog.md
- [Die Beispiel-Apps](https://developer.szenera.com/de/apps-sdk/example-apps): Alle 26 mitgelieferten Apps mit Profil und Besonderheit — und die drei Referenzen clock (nur Widget), weather (Fetcher), pharmacies-on-duty (Ressourcen… — Markdown: https://developer.szenera.com/de/apps-sdk/example-apps.md
- [Änderungen](https://developer.szenera.com/de/changes): Wo Änderungen an der API entstehen, was ein Bruch ist und wie Sie die Spezifikation gegen Ihren Stand vergleichen — ohne Versprechen, die es nicht gibt. — Markdown: https://developer.szenera.com/de/changes/index.md
- [Stabilitätsklassen und Auslauf](https://developer.szenera.com/de/changes/stability-and-sunset): Was stable, beta und internal zusagen, wie lange zwischen Ankündigung und Abschaltung liegt und woran Ihr Client einen Auslauf ohne Zutun erkennt. — Markdown: https://developer.szenera.com/de/changes/stability-and-sunset.md
- [Release-Züge, Notizen und Abkündigungen](https://developer.szenera.com/de/changes/release-notes): Wie ein Release-Zug entsteht, wie seine Notizen aufgebaut sind, was am Release hängt — und was für Abkündigungen heute gilt. — Markdown: https://developer.szenera.com/de/changes/release-notes.md
- [Pakete und ihre Fassungen](https://developer.szenera.com/de/changes/packages): Welche Fassung von API-Client, Apps-SDK, CLI und Verträgen gilt und was sich in jeder Fassung für Entwickler geändert hat. — Markdown: https://developer.szenera.com/de/changes/packages.md
- [Die Spezifikation gegen Ihren Stand vergleichen](https://developer.szenera.com/de/changes/compare-specification): openapi.json datiert ablegen, bei jedem Zug neu laden, Pfade, Pflichtfelder und Fehlercodes vergleichen — Seite und eigene Umgebung nebeneinander. — Markdown: https://developer.szenera.com/de/changes/compare-specification.md