API de señalización digital para desarrolladores

Un script, un trabajo de CI o un servidor inicia sesión como cliente de servicio. Pida al endpoint de tokens un token de acceso de 15 minutos y luego envíelo como bearer. Esto enumera las pantallas del proyecto:

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

No hay token de actualización: vuelva a pedir uno cuando el token caduque. Una clave registrada puede iniciar sesión en lugar de un secreto, y Clientes de servicio muestra ambos.

Un contrato OpenAPI describe cada llamada. Cada área tiene su propia página de referencia con los campos de cada operación, una plantilla de solicitud y sus respuestas.

La referencia de la API enumera cada grupo, incluidas las alertas, el inicio de sesión único y el aprovisionamiento de usuarios (SCIM).

Cada llamador inicia sesión con su propia sesión, y una persona aprueba cada agente y app y crea cada cliente de servicio. Los tokens de acceso van en un encabezado Authorization: Bearer y duran 15 minutos.

• Un servidor, script o trabajo de CI usa un cliente de servicio con una clave o un secreto y pide un token nuevo cuando uno caduca. Un cliente tiene hasta dos claves y dos secretos, de modo que puede rotarlos sin tiempo de inactividad, y una organización tiene hasta 50 clientes de servicio activos.
• Un agente ejecuta screenrig login, y una persona aprueba el código en el dashboard. Un agente nuevo sin cuenta comienza con screenrig agent enroll.
• Una app conectada como Claude, ChatGPT o Grok abre la página de consentimiento de screenRIG.

La persona elige cuánto puede hacer quien llama y en qué áreas: pantallas, contenido, listas de reproducción, publicidad, informes y el proyecto.

• Solo lectura enumera y lee.
• Proponer también sube medios y propone cambios. La llamada se completa con un enlace de revisión, y no se reproduce nada hasta que una persona aprueba el cambio en el dashboard.
• Administrar también modifica, publica y gasta.

Una persona finaliza cualquier sesión desde la página Acceso del dashboard, y sus tokens dejan de funcionar en segundos. Autenticación y Clientes de servicio cubren claves, rotación y errores.

Cada interfaz llega al mismo proyecto, con el mismo aislamiento de proyectos, límites de frecuencia, idempotencia y comprobaciones de revisión. El servidor remoto cubre llamadas de estilo API. Los pasos que mueven archivos o secretos se quedan en la CLI.

La CLI screenrig envuelve la API para shells, trabajos cron y agentes de terminal. Cada comando imprime un solo sobre JSON (ok, luego data o error, con un request_id) y sale con un código para cada resultado, como 4 para no encontrado, 5 para un conflicto, 6 para una revisión obsoleta y 7 cuando hay límite de frecuencia. El plugin oficial la incluye.

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

Añada --idempotency-key para reintentar una escritura de forma segura. La referencia de la CLI enumera todos los comandos.

Una app de kiosco es una página web estática. Cuando la publica, el empaquetador añade el entorno de ejecución, de modo que la página obtiene window.screenrig sin ningún paso de compilación. La página puede esperar hasta estar activa, enviar eventos con nombre y leer un almacén de clave/valor cuyos cambios llegan a cada pantalla que ejecuta la app en segundos. Software de kiosco para Android y BrightSign registra uno creado, tocado y reformulado por chat, y la referencia del SDK enumera todo lo que la página puede llamar.

screenRIG ejecuta un servidor MCP remoto en https://api.screenrig.ai/mcp. Claude, ChatGPT o Grok se conectan con OAuth: una persona aprueba la app, elige el proyecto y Solo lectura, Proponer o Administrar, y la app obtiene herramientas para pantallas, listas de reproducción, medios, programaciones, webhooks e informes. El plugin oficial sigue siendo el flujo de trabajo completo, porque sube archivos y empaqueta apps en su equipo. La referencia del servidor MCP tiene los detalles, y servidores MCP comparados contrasta el servidor con otros productos.

¿Prefiere empezar desde el asistente que usa? Controlar una TV con ChatGPT, Claude, Gemini o Grok muestra cada vía de instalación, y ¿Cómo puede mi agente de IA poner contenido en una TV? las cubre todas. La señalización digital con IA enumera solicitudes de ejemplo.

Las respuestas del agente, una por una. La ejecución es real: 26 de octubre de 2026, en el entorno de pruebas de screenRIG. La cuenta regresiva y su etiqueta son contenido de demostración.

La revisión de una pantalla es su ETag. Envíela de vuelta como condición, y la escritura se aplica solo si nadie cambió la pantalla mientras tanto:

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 primera vez, esto se aplicó y la pantalla pasó a la revisión 22. Enviado de nuevo con la revisión anterior, fue rechazado, y la respuesta (recortada aquí) nombró la actual, de modo que el cliente puede leer de nuevo y reintentar:

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

Cada error lleva un código estable, un enlace a su descripción y una pista que indica qué hacer a continuación. Un ID inexistente responde 404 con una pista sobre cómo encontrar el correcto. Una creación con una clave de idempotencia es segura de reintentar, como mostró la sesión.

Un límite responde 429 con Retry-After, y la CLI sale con el código 7. Estos son los que importan para un script:

La referencia de la CLI enumera cada límite junto al comando que protege, y los límites de los planes están en los precios.

• Flujo de eventos. La CLI y un flujo REST reproducible entregan eventos. Una pantalla sin conexión durante 60 segundos genera uno, y su regreso también. Una reconexión continúa desde el último cursor, sin costo. Señalización digital headless registra un pipeline que lee el flujo.
• Notificaciones. Una organización tiene hasta 50 en todos sus proyectos. Un correo electrónico o un webhook firmado se activa cuando una pantalla se desconecta, pierde su pantalla, se calienta, no puede almacenar su contenido, se queda atascada en una actualización de contenido, muestra un error en lugar de reproducir o falla repetidamente. Una condición se activa una vez que ha durado 10 minutos de forma predeterminada, de modo que una reconexión rápida no genera avisos, y crashing se activa de inmediato. Un webhook es un endpoint HTTPS que usted ejecuta, y también puede recibir eventos brutos del proyecto. Cada entrega está firmada, así que rechace una marca de tiempo antigua, compare en tiempo constante y elimine duplicados por el ID de entrega o de evento, porque la entrega es al menos una vez y sin orden. Responda en 10 segundos. Un intento fallido se reintenta con espera creciente durante 24 horas, y una notificación que falla durante 72 horas seguidas se desactiva.

¿Cómo verifico un webhook?

Cada entrega lleva ScreenRig-Signature: t=<unix seconds>,v1=<hex>, donde v1 es un HMAC-SHA256 sobre <t>.<raw body> con la clave del secreto de la notificación, y ScreenRig-Event-Id, que se mantiene igual en los reintentos. Calcúlelo sobre los bytes sin procesar antes de analizar el 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);
}

¿Qué tan rápido llega una escritura a la pantalla?

En la ejecución registrada del pipeline, un script escribió una fila del tablero y el flujo de eventos recogió todo el recorrido: la escritura, el cambio y luego el propio informe del Player de que había aplicado esa revisión a esa página (horas en UTC, reducidas a evento y revisión).

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"

Son 1.8 segundos desde una escritura aceptada hasta que el Player la muestra. Un trabajo que no debe continuar hasta que la pantalla muestre un fallo puede esperar a la última línea. Señalización digital headless tiene la ejecución completa.

• Suscripciones MCP. El servidor remoto puede suscribir a un asistente a eventos, de modo que pueda avisarle de que una pantalla se desconectó. La referencia del servidor MCP tiene los detalles.

Doce Players ejecutan listas de reproducción de screenRIG: el Player web, Android y Google TV, el Amazon Signage Stick, Apple TV, macOS, iPhone y iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) y BrightSign. Cada Player muestra un código de vinculación, y una llamada lo reclama. Apple TV reproduce imágenes, video, transmisiones y tarjetas. Las páginas web y sus propias apps necesitan otro Player. Players tiene la tabla de compatibilidad completa.

¿screenRIG tiene una API de señalización digital?

Sí. Una API REST cubre pantallas, listas de reproducción, medios, programaciones, apps, webhooks y más, y un solo archivo OpenAPI describe cada operación: versión 0.3.0, un archivo de 3 MB con 736 operaciones en 562 rutas y 1,059 esquemas. El plugin, los Players y el dashboard usan las mismas operaciones HTTP. La referencia de la API las enumera, y el contrato OpenAPI es un solo archivo.

¿screenRIG es un software de señalización digital API-first?

Sí. API-first significa que la API va primero y todos los clientes la usan, y aquí el dashboard, la CLI, los agentes y los Players lo hacen. La señalización digital headless muestra un pipeline que controla una pantalla sin ningún dashboard abierto.

¿Cómo envío mis propios datos a una pantalla?

Escríbalo en los datos de una tarjeta o en el almacén de clave/valor de una app. Un webhook de clave/valor es una URL que escribe una clave, de modo que un punto de venta, un script de hoja de cálculo o un trabajo cron pueden enviar datos a las pantallas con un solo HTTP POST. Una app que se suscribe se actualiza en segundos en cada pantalla que la ejecuta.

¿Cómo sé cuándo una pantalla se desconecta?

Cree una notificación que envíe un correo electrónico o un webhook firmado, o lea el flujo de eventos reproducible. Una pantalla se considera sin conexión tras 60 segundos, y una notificación espera 10 minutos de forma predeterminada antes de activarse, de modo que una reconexión rápida no genera avisos.

¿Qué pasa cuando alcanzo un límite de frecuencia?

La API responde 429, y su encabezado Retry-After indica cuánto esperar. La CLI sale con el código 7 y muestra retry_after_seconds.

¿Cambiará la API bajo mi script?

Los cambios dentro de una versión mayor son compatibles: nuevos endpoints, miembros de solicitud opcionales y nuevos códigos de problema. Un cambio que rompe una llamada que funciona requiere una nueva versión mayor, que se solapa con la anterior durante al menos 180 días.

¿La API de señalización digital es gratuita?

screenRIG es gratis, con pantallas ilimitadas. Los planes de pago añaden herramientas de negocio, más personas, personas con quienes hablar, gobernanza y condiciones contractuales. Las llamadas desde su código cuentan como solicitudes de agente, y todos los planes incluyen algunas cada mes. Consulte los precios.

Abra la referencia de la API REST, que enumera todas las llamadas que vio aquí, o comience gratis y deje que su agente las haga. Agentes explica cómo se registra un agente por sí mismo.