API de sinalização digital para desenvolvedores

Um script, job de CI ou servidor faz login como cliente de serviço. Peça ao endpoint de token um token de acesso de 15 minutos e envie-o como bearer. Isto lista as telas do projeto:

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

Não há token de atualização: peça de novo quando o token expirar. Uma chave registrada pode fazer o login no lugar de um segredo, e Clientes de serviço mostra os dois.

Um único contrato OpenAPI descreve todas as chamadas. Cada área tem sua própria página de referência com os campos de cada operação, um modelo de solicitação e suas respostas.

A referência da API lista todos os grupos, incluindo alertas, login único e provisionamento de usuários (SCIM).

Cada chamador faz login com a própria sessão, e uma pessoa aprova cada agente e app e cria cada cliente de serviço. Os tokens de acesso vão em um cabeçalho Authorization: Bearer e duram 15 minutos.

• Um servidor, script ou job de CI usa um cliente de serviço com uma chave ou um segredo e pede um novo token quando um expira. Um cliente guarda até duas chaves e dois segredos, para você poder fazer a rotação sem indisponibilidade, e uma organização comporta até 50 clientes de serviço ativos.
• Um agente executa screenrig login, e uma pessoa aprova o código no dashboard. Um agente novo, sem conta, começa com screenrig agent enroll.
• Um app conectado como Claude, ChatGPT ou Grok abre a página de consentimento do screenRIG.

A pessoa escolhe quanto o chamador pode fazer e em quais áreas: telas, conteúdo, playlists, publicidade, relatórios e o projeto.

• Somente leitura lista e lê.
• Propor também envia mídia e propõe alterações. A chamada é concluída com um link de revisão, e nada é reproduzido até que uma pessoa aprove a alteração no dashboard.
• Gerenciar também altera, publica e gasta.

Uma pessoa encerra qualquer sessão pela página Acesso do dashboard, e os tokens dela deixam de funcionar em segundos. Autenticação e Clientes de serviço cobrem chaves, rotação e erros.

Toda interface alcança o mesmo projeto, com o mesmo isolamento de projeto, os mesmos limites de taxa, a mesma idempotência e as mesmas verificações de revisão. O servidor remoto cobre chamadas no estilo de API. As etapas que movem arquivos ou segredos ficam na CLI.

A CLI screenrig envolve a API para shells, cron jobs e agentes de terminal. Cada comando imprime um envelope JSON (ok, depois data ou error, com um request_id) e sai com um código para cada resultado, como 4 para não encontrado, 5 para um conflito, 6 para uma revisão desatualizada e 7 quando há limite de taxa. O plugin oficial a inclui.

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

Adicione --idempotency-key para repetir uma gravação com segurança. A referência da CLI lista todos os comandos.

Um app de quiosque é uma página web estática. Quando você o publica, o empacotador adiciona o runtime, então a página recebe window.screenrig sem etapa de build. A página pode esperar até ficar ativa, enviar eventos nomeados e ler um armazenamento chave/valor cujas alterações chegam a todas as telas que executam o app em segundos. Software de quiosque para Android e BrightSign registra um criado, tocado e reescrito pelo chat, e a referência do SDK lista tudo o que a página pode chamar.

O screenRIG executa um servidor MCP remoto em https://api.screenrig.ai/mcp. Claude, ChatGPT ou Grok se conectam com OAuth: uma pessoa aprova o app, escolhe o projeto e Somente leitura, Propor ou Gerenciar, e o app recebe ferramentas para telas, playlists, mídia, programações, webhooks e relatórios. O plugin oficial continua sendo o fluxo completo, porque envia arquivos e empacota apps na sua máquina. A referência do servidor MCP traz os detalhes, e servidores MCP comparados coloca o servidor ao lado de outros produtos.

Prefere começar pelo assistente que você usa? Controlar uma TV com o ChatGPT, Claude, Gemini ou Grok mostra o caminho de instalação de cada um, e Como meu agente de IA pode colocar conteúdo em uma TV? cobre todos eles. Sinalização digital com IA lista exemplos de pedidos.

As respostas do agente, uma a uma. A execução é real: 26 de outubro de 2026, no ambiente de staging do screenRIG. A contagem regressiva e o rótulo dela são conteúdo de demonstração.

A revisão de uma tela é o ETag dela. Envie-a de volta como condição, e a gravação é aplicada somente se ninguém alterou a tela nesse meio-tempo:

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

Da primeira vez, foi aplicada e a tela passou para a revisão 22. Enviada de novo com a revisão antiga, foi recusada, e a resposta (reduzida aqui) nomeou a atual, para que o cliente possa ler de novo e tentar outra vez:

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

Todo erro traz um código estável, um link para a descrição dele e uma dica que diz o que fazer em seguida. Um ID ausente responde 404 com uma dica de como encontrar o certo. Uma criação que traz uma chave de idempotência pode ser repetida com segurança, como a sessão mostrou.

Um limite responde 429 com Retry-After, e a CLI sai com o código 7. Estes são os que importam para um script:

A referência da CLI lista cada limite ao lado do comando que ele protege, e os limites dos planos estão em preços.

• Fluxo de eventos. A CLI e um fluxo REST reproduzível entregam eventos. Uma tela offline por 60 segundos gera um, e o retorno dela também. Uma reconexão retoma a partir do último cursor, sem custo. Sinalização digital headless registra um pipeline lendo o fluxo.
• Notificações. Uma organização comporta até 50 em todos os seus projetos. Um e-mail ou um webhook assinado dispara quando uma tela fica offline, perde o display, superaquece, não consegue armazenar o conteúdo, trava em uma atualização de conteúdo, mostra um erro em vez de reproduzir ou fica travando. Uma condição dispara depois de durar 10 minutos por padrão, então uma reconexão rápida fica em silêncio, e crashing dispara na hora. Um webhook é um endpoint HTTPS que você executa, e ele também pode receber eventos brutos do projeto. Toda entrega é assinada, então rejeite um timestamp antigo, compare em tempo constante e remova duplicatas pelo ID da entrega ou do evento, porque a entrega é pelo menos uma vez e fora de ordem. Responda em até 10 segundos. Uma tentativa com falha é repetida com backoff por 24 horas, e uma notificação que falha por 72 horas seguidas é desativada.

Como verifico um webhook?

Cada entrega traz ScreenRig-Signature: t=<unix seconds>,v1=<hex>, em que v1 é um HMAC-SHA256 sobre <t>.<raw body> com a chave do segredo da notificação, e ScreenRig-Event-Id, que permanece o mesmo entre as novas tentativas. Calcule-o sobre os bytes brutos antes de analisar o 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);
}

Com que rapidez uma gravação chega à tela?

Na execução registrada do pipeline, um script gravou uma linha do painel e o fluxo de eventos mostrou o caminho inteiro: a gravação, a alteração e, depois, o relato do próprio Player de que aplicou aquela revisão àquela página (horários em UTC, reduzidos a evento e revisão).

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"

São 1,8 segundo desde uma gravação aceita até o Player exibi-la. Um job que não deve prosseguir até a tela mostrar uma falha pode esperar pela última linha. Sinalização digital headless traz a execução completa.

• Assinaturas MCP. O servidor remoto pode inscrever um assistente em eventos, para que ele avise você quando uma tela ficar offline. A referência do servidor MCP traz os detalhes.

Doze Players executam playlists do screenRIG: o Player web, Android e Google TV, o Amazon Signage Stick, Apple TV, macOS, iPhone e iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) e BrightSign. Todo Player mostra um código de pareamento, e uma chamada o reivindica. O Apple TV reproduz imagens, vídeo, streams e cartões. Páginas web e seus próprios apps exigem outro Player. Players traz a tabela completa de compatibilidade.

O screenRIG tem uma API de sinalização digital?

Sim. Uma API REST cobre telas, playlists, mídia, programações, apps, webhooks e mais, e um único arquivo OpenAPI descreve todas as operações: versão 0.3.0, um arquivo de 3 MB com 736 operações em 562 caminhos e 1.059 esquemas. O plugin, os Players e o dashboard usam as mesmas operações HTTP. A referência da API as lista, e o contrato OpenAPI é um único arquivo.

O screenRIG é um software de sinalização digital API-first?

Sim. API-first significa que a API vem primeiro e todo cliente a usa, e aqui o dashboard, a CLI, os agentes e os Players a usam. Sinalização digital headless mostra um pipeline controlando uma tela sem nenhum dashboard aberto.

Como envio meus próprios dados para uma tela?

Grave nos dados de um cartão ou no armazenamento chave/valor de um app. Um webhook chave/valor é uma URL que grava uma chave, então um ponto de venda, um script de planilha ou um cron job pode enviar dados às telas com um único HTTP POST. Um app que assina atualiza em segundos todas as telas que o executam.

Como saber quando uma tela fica offline?

Crie uma notificação que envia um e-mail ou um webhook assinado, ou leia o fluxo de eventos reproduzível. Uma tela é considerada offline após 60 segundos, e uma notificação espera 10 minutos por padrão antes de disparar, então uma reconexão rápida fica em silêncio.

O que acontece quando atinjo um limite de taxa?

A API responde 429, e o cabeçalho Retry-After dela informa quanto esperar. A CLI sai com o código 7 e mostra retry_after_seconds.

A API vai mudar sob o meu script?

As alterações dentro de uma versão principal são compatíveis: novos endpoints, membros opcionais de solicitação e novos códigos de problema. Uma alteração que quebre uma chamada que funciona exige uma nova versão principal, que se sobrepõe à antiga por pelo menos 180 dias.

A API de sinalização digital é grátis?

O screenRIG é grátis, com telas ilimitadas. Os planos pagos acrescentam ferramentas empresariais, mais pessoas, pessoas com quem falar, governança e condições contratuais. As chamadas do seu código contam como solicitações de agente, e todo plano inclui algumas por mês. Veja preços.

Abra a referência da API REST, que lista todas as chamadas que você viu aqui, ou comece grátis e deixe seu agente fazê-las. Agentes explica como um agente se cadastra sozinho.