Digital-Signage-API für Entwickler

Ein Skript, CI-Job oder Server meldet sich als Service-Client an. Fragen Sie den Token-Endpunkt nach einem 15-Minuten-Zugriffstoken und senden Sie es dann als Bearer. Das listet die Bildschirme des Projekts auf:

# Get a token with a service client's id and secret.
curl -s https://api.screenrig.ai/oauth/token \
  -u "$SCREENRIG_CLIENT_ID:$SCREENRIG_CLIENT_SECRET" \
  -d grant_type=client_credentials

# Put the access_token it returns in $TOKEN, then list the screens.
curl -s https://api.screenrig.ai/api/screens \
  -H "Authorization: Bearer $TOKEN"

Es gibt kein Refresh-Token: Fragen Sie erneut an, wenn das Token abläuft. Statt eines Geheimnisses kann sich auch ein registrierter Schlüssel anmelden, und Service-Clients zeigt beides.

Ein OpenAPI-Vertrag beschreibt jeden Aufruf. Jeder Bereich hat eine eigene Referenzseite mit den Feldern jeder Operation, einer Anfragevorlage und ihren Antworten.

Die API-Referenz listet jede Gruppe auf, einschließlich Alarmen, Single Sign-on und Benutzerbereitstellung (SCIM).

Jeder Aufrufer meldet sich mit seiner eigenen Sitzung an, und eine Person genehmigt jeden Agenten und jede App und erstellt jeden Service-Client. Zugriffstokens stehen in einem Authorization: Bearer-Header und gelten 15 Minuten.

• Ein Server, Skript oder CI-Job verwendet einen Service-Client mit einem Schlüssel oder Geheimnis und fordert ein neues Token an, wenn eines abläuft. Ein Client hält bis zu zwei Schlüssel und zwei Geheimnisse, sodass Sie ohne Ausfallzeit rotieren können, und eine Organisation hält bis zu 50 aktive Service-Clients.
• Ein Agent führt screenrig login aus, und eine Person genehmigt den Code im Dashboard. Ein neuer Agent ohne Konto beginnt mit screenrig agent enroll.
• Eine verbundene App wie Claude, ChatGPT oder Grok öffnet die Zustimmungsseite von screenRIG.

Die Person legt fest, wie viel der Aufrufer tun darf und in welchen Bereichen: Bildschirme, Inhalte, Playlists, Werbung, Berichte und das Projekt.

• Nur lesen listet auf und liest.
• Vorschlagen lädt außerdem Medien hoch und schlägt Änderungen vor. Der Aufruf gelingt mit einem Überprüfungslink, und nichts wird abgespielt, bis eine Person die Änderung im Dashboard freigibt.
• Verwalten ändert außerdem, veröffentlicht und tätigt Ausgaben.

Eine Person beendet jede Sitzung auf der Zugriffsseite des Dashboards, und ihre Tokens funktionieren innerhalb von Sekunden nicht mehr. Authentifizierung und Service-Clients behandeln Schlüssel, Rotation und Fehler.

Jede Schnittstelle erreicht dasselbe Projekt, mit derselben Projektisolation, denselben Ratenbegrenzungen, derselben Idempotenz und denselben Revisionsprüfungen. Der Remote-Server deckt API-artige Aufrufe ab. Schritte, die Dateien oder Geheimnisse bewegen, bleiben in der CLI.

Die screenrig-CLI verpackt die API für Shells, Cron-Jobs und Terminal-Agenten. Jeder Befehl gibt einen JSON-Umschlag aus (ok, dann data oder error, mit einem request_id) und beendet sich mit einem Code für jedes Ergebnis, etwa 4 für nicht gefunden, 5 für einen Konflikt, 6 für eine veraltete Revision und 7 bei Ratenbegrenzung. Das offizielle Plugin enthält sie.

screenrig screen list --tag Lobby
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000

Fügen Sie --idempotency-key hinzu, um einen Schreibvorgang sicher zu wiederholen. Die CLI-Referenz listet jeden Befehl auf.

Eine Kiosk-App ist eine statische Webseite. Wenn Sie sie veröffentlichen, fügt der Packer die Laufzeit hinzu, sodass die Seite window.screenrig ohne Build-Schritt erhält. Die Seite kann warten, bis sie aktiv ist, benannte Ereignisse senden und einen Schlüssel/Wert-Speicher lesen, dessen Änderungen jeden Bildschirm, auf dem die App läuft, innerhalb von Sekunden erreichen. Kiosk-Software für Android und BrightSign zeichnet eine auf, die per Chat gebaut, bedient und umformuliert wurde, und die SDK-Referenz listet alles auf, was die Seite aufrufen kann.

screenRIG betreibt einen Remote-MCP-Server unter https://api.screenrig.ai/mcp. Claude, ChatGPT oder Grok verbinden sich per OAuth: Eine Person genehmigt die App, wählt das Projekt und Nur lesen, Vorschlagen oder Verwalten, und die App erhält Tools für Bildschirme, Playlists, Medien, Zeitpläne, Webhooks und Berichte. Das offizielle Plugin bleibt der vollständige Workflow, weil es Dateien hochlädt und Apps auf Ihrem Rechner packt. Die MCP-Server-Referenz hat die Einzelheiten, und MCP-Server im Vergleich stellt den Server anderen Produkten gegenüber.

Möchten Sie lieber mit dem Assistenten beginnen, den Sie nutzen? Einen Fernseher mit ChatGPT steuern, Claude, Gemini oder Grok zeigt jeden Installationsweg, und Wie kann mein KI-Agent Inhalte auf einen Fernseher bringen? behandelt sie alle. KI-Digital-Signage listet Beispielanfragen auf.

Die Antworten des Agenten, eine nach der anderen. Der Lauf ist echt: 26. Oktober 2026, auf der Staging-Umgebung von screenRIG. Der Countdown und sein Label sind Demo-Inhalt.

Die Revision eines Bildschirms ist sein ETag. Senden Sie sie als Bedingung zurück, und der Schreibvorgang wird nur angewendet, wenn niemand den Bildschirm in der Zwischenzeit geändert hat:

curl -X PATCH "$API/api/screens/$SCREEN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: W/"21"' \
  -d '{"playlist_id": "'"$PLAYLIST"'"}'

Beim ersten Mal wurde das angewendet, und der Bildschirm wechselte auf Revision 22. Mit der alten Revision erneut gesendet, wurde es abgelehnt, und die Antwort (hier gekürzt) nannte die aktuelle, sodass der Client erneut lesen und es noch einmal versuchen kann:

{"errors": [{"status": 412, "code": "revision_conflict", "current_revision": 22}]}

Jeder Fehler trägt einen stabilen Code, einen Link zu seiner Beschreibung und einen Hinweis, was als Nächstes zu tun ist. Eine fehlende ID antwortet mit 404 und einem Hinweis, wie man die richtige findet. Eine Erstellung mit Idempotenzschlüssel kann sicher wiederholt werden, wie die Sitzung zeigte.

Ein Limit antwortet mit 429 und Retry-After, und die CLI beendet sich mit Code 7. Das sind die, die für ein Skript wichtig sind:

Die CLI-Referenz listet jedes Limit neben dem Befehl auf, den es schützt, und die Limits der Pläne stehen unter Preise.

• Ereignisstrom. Die CLI und ein wiederabspielbarer REST-Stream liefern beide Ereignisse. Ein Bildschirm, der 60 Sekunden offline ist, löst eines aus, ebenso seine Rückkehr. Ein erneutes Verbinden setzt am letzten Cursor fort, kostenlos. Headless Digital Signage zeichnet eine Pipeline auf, die den Stream liest.
• Benachrichtigungen. Eine Organisation hält bis zu 50 über ihre Projekte hinweg. Eine E-Mail oder ein signierter Webhook wird ausgelöst, wenn ein Bildschirm offline geht, sein Display verliert, heiß läuft, seine Inhalte nicht speichern kann, bei einem Inhaltsupdate hängen bleibt, einen Fehler statt der Wiedergabe zeigt oder ständig abstürzt. Eine Bedingung wird ausgelöst, sobald sie standardmäßig 10 Minuten angedauert hat, sodass ein kurzes erneutes Verbinden still bleibt, und crashing löst sofort aus. Ein Webhook ist ein HTTPS-Endpunkt, den Sie betreiben, und er kann auch rohe Projektereignisse empfangen. Jede Zustellung ist signiert, lehnen Sie also einen alten Zeitstempel ab, vergleichen Sie in konstanter Zeit und deduplizieren Sie anhand der Zustellungs- oder Ereignis-ID, denn die Zustellung erfolgt mindestens einmal und ungeordnet. Antworten Sie innerhalb von 10 Sekunden. Ein fehlgeschlagener Versuch wird 24 Stunden lang mit Backoff wiederholt, und eine Benachrichtigung, die 72 Stunden in Folge fehlschlägt, wird deaktiviert.

Wie verifiziere ich einen Webhook?

Jede Zustellung enthält ScreenRig-Signature: t=<unix seconds>,v1=<hex>, wobei v1 ein HMAC-SHA256 über <t>.<raw body> mit dem Geheimnis der Benachrichtigung als Schlüssel ist, und ScreenRig-Event-Id, das über Wiederholungen hinweg gleich bleibt. Berechnen Sie ihn über die rohen Bytes, bevor Sie das JSON parsen:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body bytes (Buffer) exactly as received.
function verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof signatureHeader !== "string" || !signatureHeader) return false;
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Wie schnell erreicht ein Schreibvorgang den Bildschirm?

Im aufgezeichneten Pipeline-Lauf schrieb ein Skript eine Tafelzeile, und der Ereignisstrom trug den ganzen Weg: das Schreiben, die Änderung und dann die eigene Meldung des Players, dass er diese Revision auf diese Seite angewendet hatte (Zeiten in UTC, auf Ereignis und Revision gekürzt).

03:43:47.501  kv.updated                 revision 5 written
03:43:47.505  screen.card_data_changed   revision 5
03:43:49.306  screen.card_data_applied   revision 5, page "board"

Das sind 1,8 Sekunden von einem akzeptierten Schreibvorgang bis zur Anzeige im Player. Ein Job, der erst weitermachen darf, wenn der Bildschirm es zeigt, kann auf die letzte Zeile warten. Headless Digital Signage enthält den ganzen Lauf.

• MCP-Abonnements. Der Remote-Server kann einen Assistenten auf Ereignisse abonnieren, sodass er Ihnen sagen kann, dass ein Bildschirm offline gegangen ist. Die MCP-Server-Referenz hat die Einzelheiten.

Zwölf Player spielen screenRIG-Playlists ab: der Web-Player, Android und Google TV, der Amazon Signage Stick, Apple TV, macOS, iPhone und iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) und BrightSign. Jeder Player zeigt einen Kopplungscode, und ein Aufruf beansprucht ihn. Apple TV spielt Bilder, Video, Streams und Karten ab. Webseiten und Ihre eigenen Apps brauchen einen anderen Player. Player enthält die vollständige Support-Tabelle.

Hat screenRIG eine Digital-Signage-API?

Ja. Eine REST-API deckt Bildschirme, Playlists, Medien, Zeitpläne, Apps, Webhooks und mehr ab, und eine OpenAPI-Datei beschreibt jede Operation: Version 0.3.0, eine 3-MB-Datei mit 736 Operationen auf 562 Pfaden und 1.059 Schemas. Das Plugin, die Player und das Dashboard nutzen dieselben HTTP-Operationen. Die API-Referenz listet sie auf, und der OpenAPI-Vertrag ist eine einzige Datei.

Ist screenRIG eine API-first-Digital-Signage-Software?

Ja. API-first bedeutet, dass die API zuerst kommt und jeder Client sie nutzt, und hier tun das das Dashboard, die CLI, Agenten und Player alle. Headless Digital Signage zeigt eine Pipeline, die einen Bildschirm ohne geöffnetes Dashboard betreibt.

Wie sende ich meine eigenen Daten an einen Bildschirm?

Schreiben Sie es in die Daten einer Karte oder in den Schlüssel/Wert-Speicher einer App. Ein Schlüssel/Wert-Webhook ist eine URL, die einen Schlüssel schreibt, sodass eine Kasse, ein Tabellenskript oder ein Cron-Job mit einem einzigen HTTP-POST Daten an Bildschirme senden kann. Eine App, die das abonniert, aktualisiert sich innerhalb von Sekunden auf jedem Bildschirm, auf dem sie läuft.

Woher weiß ich, wann ein Bildschirm offline geht?

Erstellen Sie eine Benachrichtigung, die eine E-Mail oder einen signierten Webhook sendet, oder lesen Sie den wiederabspielbaren Ereignisstrom. Ein Bildschirm gilt nach 60 Sekunden als offline, und eine Benachrichtigung wartet standardmäßig 10 Minuten, bevor sie auslöst, sodass ein kurzes erneutes Verbinden still bleibt.

Was passiert, wenn ich eine Ratenbegrenzung erreiche?

Die API antwortet mit 429, und ihr Header Retry-After sagt, wie lange zu warten ist. Die CLI beendet sich mit Code 7 und zeigt retry_after_seconds.

Ändert sich die API unter meinem Skript?

Änderungen innerhalb einer Hauptversion sind kompatibel: neue Endpunkte, optionale Anfragefelder und neue Problemcodes. Eine Änderung, die einen funktionierenden Aufruf bricht, braucht eine neue Hauptversion, die die alte mindestens 180 Tage lang überlappt.

Ist die Digital-Signage-API kostenlos?

screenRIG ist kostenlos, mit unbegrenzt vielen Bildschirmen. Bezahlte Pläne ergänzen Business-Tools, mehr Personen, Ansprechpartner, Governance und Vertragsbedingungen. Aufrufe aus Ihrem Code zählen als Agent-Anfragen, und jeder Plan enthält jeden Monat einige. Siehe Preise.

Öffnen Sie die REST-API-Referenz, die jeden Aufruf aufführt, den Sie hier gesehen haben, oder starten Sie kostenlos und lassen Sie Ihren Agenten sie ausführen. Agenten erklärt, wie sich ein Agent selbst anmeldet.