API d’affichage numérique pour développeurs

Un script, une tâche CI ou un serveur se connecte comme client de service. Demandez au point de terminaison des jetons un jeton d’accès de 15 minutes, puis envoyez-le comme jeton porteur. Ceci énumère les écrans du projet :

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

Il n’y a pas de jeton d’actualisation : redemandez-en un à l’expiration du jeton. Une clé enregistrée peut servir à se connecter à la place d’un secret, et Clients de service présente les deux.

Un seul contrat OpenAPI décrit chaque appel. Chaque domaine a sa propre page de référence avec les champs de chaque opération, un modèle de requête et ses réponses.

La référence de l’API énumère chaque groupe, y compris les alertes, l’authentification unique et le provisionnement des utilisateurs (SCIM).

Chaque appelant se connecte avec sa propre session, et une personne approuve chaque agent et chaque app et crée chaque client de service. Les jetons d’accès vont dans un en-tête Authorization: Bearer et durent 15 minutes.

• Un serveur, un script ou une tâche CI utilise un client de service avec une clé ou un secret et demande un nouveau jeton à l’expiration de l’un d’eux. Un client détient jusqu’à deux clés et deux secrets, de sorte que vous pouvez effectuer une rotation sans interruption, et une organisation détient jusqu’à 50 clients de service actifs.
• Un agent exécute screenrig login, et une personne approuve le code dans le tableau de bord. Un nouvel agent sans compte commence par screenrig agent enroll.
• Une app connectée comme Claude, ChatGPT ou Grok ouvre la page de consentement de screenRIG.

La personne choisit ce que l’appelant peut faire et dans quels domaines : écrans, contenu, listes de lecture, publicité, rapports et projet.

• Lecture seule énumère et lit.
• Proposer téléverse aussi des médias et propose des changements. L’appel réussit avec un lien de révision, et rien n’est diffusé tant qu’une personne n’a pas approuvé le changement dans le tableau de bord.
• Gérer modifie, publie et dépense aussi.

Une personne met fin à n’importe quelle session depuis la page Accès du tableau de bord, et ses jetons cessent de fonctionner en quelques secondes. Authentification et Clients de service couvrent les clés, la rotation et les erreurs.

Chaque interface atteint le même projet, avec la même isolation de projet, les mêmes limites de débit, la même idempotence et les mêmes vérifications de révision. Le serveur distant couvre les appels de style API. Les étapes qui déplacent des fichiers ou des secrets restent dans le CLI.

Le CLI screenrig enveloppe l’API pour les interpréteurs de commandes, les tâches cron et les agents de terminal. Chaque commande affiche une seule enveloppe JSON (ok, puis data ou error, avec un request_id) et se termine avec un code pour chaque résultat, comme 4 pour introuvable, 5 pour un conflit, 6 pour une révision périmée et 7 en cas de limitation de débit. Le plugin officiel l’intègre.

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

Ajoutez --idempotency-key pour répéter une écriture en toute sécurité. La référence du CLI énumère chaque commande.

Une app kiosque est une page Web statique. Lorsque vous la publiez, l’outil d’empaquetage ajoute l’environnement d’exécution, de sorte que la page obtient window.screenrig sans étape de compilation. La page peut attendre d’être active, envoyer des événements nommés et lire un magasin clé/valeur dont les changements atteignent en quelques secondes chaque écran qui exécute l’app. Logiciel de kiosque pour Android et BrightSign présente l’enregistrement d’une app créée, touchée et reformulée par clavardage, et la référence du SDK énumère tout ce que la page peut appeler.

screenRIG exploite un serveur MCP distant à https://api.screenrig.ai/mcp. Claude, ChatGPT ou Grok se connectent avec OAuth : une personne approuve l’app, choisit le projet et Lecture seule, Proposer ou Gérer, et l’app obtient des outils pour les écrans, les listes de lecture, les médias, les horaires, les webhooks et les rapports. Le plugin officiel reste le flux de travail complet, parce qu’il téléverse des fichiers et empaquette des apps sur votre machine. La référence du serveur MCP donne les détails, et Serveurs MCP comparés met ce serveur en regard d’autres produits.

Vous préférez partir de l’assistant que vous utilisez? Contrôler un téléviseur avec ChatGPT, Claude, Gemini ou Grok présente chaque chemin d’installation, et Comment mon agent IA peut-il mettre du contenu sur un téléviseur? les couvre tous. L’affichage numérique par IA énumère des exemples de requêtes.

Les réponses de l’agent, une par une. L’exécution est réelle : le 26 octobre 2026, sur l’environnement de préproduction de screenRIG. Le compte à rebours et son libellé sont du contenu de démonstration.

La révision d’un écran est son ETag. Renvoyez-la comme condition, et l’écriture ne s’applique que si personne n’a modifié l’écran entre-temps :

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"'"}'

La première fois, ceci s’est appliqué et l’écran est passé à la révision 22. Renvoyé avec l’ancienne révision, il a été refusé, et la réponse (abrégée ici) nommait la révision actuelle, de sorte que le client peut relire et réessayer :

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

Chaque erreur porte un code stable, un lien vers sa description et une indication de ce qu’il faut faire ensuite. Un identifiant manquant répond 404 avec une indication pour trouver le bon. Une création qui porte une clé d’idempotence peut être répétée sans risque, comme la session l’a montré.

Une limite répond 429 avec Retry-After, et le CLI se termine avec le code 7. Voici celles qui comptent pour un script :

La référence du CLI énumère chaque limite à côté de la commande qu’elle protège, et les limites des forfaits figurent dans les tarifs.

• Flux d’événements. Le CLI et un flux REST rejouable livrent tous deux des événements. Un écran hors ligne pendant 60 secondes en déclenche un, tout comme son retour. Une reconnexion reprend au dernier curseur, sans frais. L’affichage numérique sans interface enregistre un pipeline qui lit le flux.
• Notifications. Une organisation peut en détenir jusqu’à 50 sur l’ensemble de ses projets. Un courriel ou un webhook signé se déclenche lorsqu’un écran passe hors ligne, perd son affichage, surchauffe, ne peut pas stocker son contenu, reste bloqué sur une mise à jour de contenu, affiche une erreur au lieu de diffuser ou plante sans cesse. Une condition se déclenche après avoir duré 10 minutes par défaut, de sorte qu’une reconnexion rapide reste silencieuse, et crashing se déclenche immédiatement. Un webhook est un point de terminaison HTTPS que vous exploitez, et il peut aussi recevoir les événements bruts du projet. Chaque livraison est signée, alors rejetez un horodatage ancien, comparez en temps constant et dédupliquez sur l’identifiant de livraison ou d’événement, car la livraison se fait au moins une fois et sans ordre garanti. Répondez en moins de 10 secondes. Une tentative échouée est reprise avec un délai croissant pendant 24 heures, et une notification qui échoue pendant 72 heures de suite est désactivée.

Comment vérifier un webhook?

Chaque livraison porte ScreenRig-Signature: t=<unix seconds>,v1=<hex>, où v1 est un HMAC-SHA256 calculé sur <t>.<raw body> avec le secret de la notification, et ScreenRig-Event-Id, qui reste identique d’une reprise à l’autre. Calculez-le sur les octets bruts avant d’analyser le JSON :

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);
}

En combien de temps une écriture atteint-elle l’écran?

Dans l’exécution de pipeline enregistrée, un script a écrit une ligne de tableau et le flux d’événements a porté tout le parcours : l’écriture, le changement, puis le rapport du Player lui-même indiquant qu’il avait appliqué cette révision à cette page (heures en UTC, réduites à l’événement et à la révision).

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"

Cela fait 1,8 seconde entre une écriture acceptée et son affichage par le Player. Une tâche qui ne doit pas se poursuivre avant que l’écran affiche un échec peut attendre la dernière ligne. L’affichage numérique sans interface présente toute l’exécution.

• Abonnements MCP. Le serveur distant peut abonner un assistant aux événements, de sorte qu’il peut vous dire qu’un écran est passé hors ligne. La référence du serveur MCP donne les détails.

Douze Players exécutent les listes de lecture screenRIG : le Player Web, Android et Google TV, l’Amazon Signage Stick, Apple TV, macOS, iPhone et iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) et BrightSign. Chaque Player affiche un code de jumelage, et un seul appel le réclame. Apple TV lit des images, des vidéos, des flux et des cartes. Les pages Web et vos propres apps exigent un autre Player. Players présente le tableau complet de prise en charge.

screenRIG a-t-il une API d’affichage numérique?

Oui. Une API REST couvre les écrans, les listes de lecture, les médias, les horaires, les apps, les webhooks et plus encore, et un seul fichier OpenAPI décrit chaque opération : version 0.3.0, un fichier de 3 Mo avec 736 opérations sur 562 chemins et 1 059 schémas. Le plugin, les Players et le tableau de bord utilisent les mêmes opérations HTTP. La référence de l’API les énumère, et le contrat OpenAPI tient en un seul fichier.

screenRIG est-il un logiciel d’affichage numérique axé sur l’API?

Oui. Axé sur l’API signifie que l’API vient en premier et que chaque client l’utilise, et ici le tableau de bord, le CLI, les agents et les Players le font tous. L’affichage numérique sans interface montre un pipeline qui pilote un écran sans tableau de bord ouvert.

Comment envoyer mes propres données à un écran?

Écrivez-la dans les données d’une carte ou dans le magasin clé/valeur d’une app. Un webhook clé/valeur est une URL qui écrit une clé, de sorte qu’un point de vente, un script de tableur ou une tâche cron peut envoyer des données aux écrans avec un seul POST HTTP. Une app abonnée se met à jour en quelques secondes sur chaque écran qui l’exécute.

Comment savoir quand un écran passe hors ligne?

Créez une notification qui envoie un courriel ou un webhook signé, ou lisez le flux d’événements rejouable. Un écran est considéré hors ligne après 60 secondes, et une notification attend 10 minutes par défaut avant de se déclencher, de sorte qu’une reconnexion rapide reste silencieuse.

Que se passe-t-il quand j’atteins une limite de débit?

L’API répond 429, et son en-tête Retry-After indique combien de temps attendre. Le CLI se termine avec le code 7 et affiche retry_after_seconds.

L’API va-t-elle changer sous mon script?

Les changements au sein d’une version majeure sont compatibles : nouveaux points de terminaison, membres de requête facultatifs et nouveaux codes de problème. Un changement qui casse un appel fonctionnel exige une nouvelle version majeure, qui chevauche l’ancienne pendant au moins 180 jours.

L’API d’affichage numérique est-elle gratuite?

screenRIG est gratuit, avec un nombre illimité d’écrans. Les forfaits payants ajoutent des outils d’affaires, plus de personnes, des personnes à qui parler, la gouvernance et des conditions contractuelles. Les appels de votre code comptent comme des requêtes d’agent, et chaque forfait en comprend un certain nombre par mois. Voir les tarifs.

Ouvrez la référence de l’API REST, qui énumère chaque appel vu ici, ou commencez gratuitement et laissez votre agent les effectuer. Agents explique comment un agent s’inscrit lui-même.