開発者向けデジタルサイネージ API

スクリプト、CI ジョブ、サーバーは、サービスクライアントとしてサインインします。トークンエンドポイントに15分間有効なアクセストークンを要求し、それを bearer として送ります。次の呼び出しで、プロジェクトのスクリーンが一覧表示されます。

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

リフレッシュトークンはありません。トークンが失効したら、あらためて要求してください。シークレットの代わりに、登録済みのキーでサインインすることもでき、両方の方法はサービスクライアントで説明しています。

1つの OpenAPI 契約がすべての呼び出しを記述しています。各分野には専用のリファレンスページがあり、すべてのオペレーションのフィールド、リクエストのテンプレート、レスポンスが載っています。

API リファレンスには、アラート、シングルサインオン、ユーザープロビジョニング（SCIM）を含むすべてのグループが載っています。

呼び出し側はそれぞれ自分のセッションでサインインし、人がエージェントとアプリをそれぞれ承認し、サービスクライアントをそれぞれ作成します。アクセストークンは Authorization: Bearer ヘッダーに入れて送り、15分間有効です。

• サーバー、スクリプト、CI ジョブは、キーまたはシークレットを持つサービスクライアントを使い、トークンが失効したら新しいトークンを要求します。クライアントはキーを2つ、シークレットを2つまで保持できるため、ダウンタイムなしでローテーションでき、組織が保持できる有効なサービスクライアントは最大50です。
• エージェントが screenrig login を実行し、人がダッシュボードでコードを承認します。アカウントのない新しいエージェントは screenrig agent enroll から始まります。
• 連携アプリ（Claude、ChatGPT、Grok など）は、screenRIG の同意ページを開きます。

呼び出し側にどこまでを許すかと、どの分野を許すかを、人が選びます。対象は、スクリーン、コンテンツ、プレイリスト、広告、レポート、プロジェクトです。

• 読み取り専用は、一覧表示と読み取りができます。
• 提案では、メディアのアップロードと変更の提案もできます。呼び出しはレビューへのリンクとともに成功し、人がダッシュボードで変更を承認するまで何も再生されません。
• 管理では、変更、公開、支出もできます。

人がダッシュボードの「アクセス」ページから任意のセッションを終了でき、そのトークンは数秒以内に使えなくなります。キー、ローテーション、エラーについては 認証とサービスクライアントをご覧ください。

どのインターフェースも同じプロジェクトに到達し、プロジェクトの分離、レート制限、冪等性、リビジョンチェックも同じです。リモートサーバーがカバーするのは API 形式の呼び出しです。ファイルやシークレットを扱う手順は CLI に残ります。

screenrig CLI は、API をシェル、cron ジョブ、ターミナルエージェント向けにラップします。すべてのコマンドは1つの JSON エンベロープ（ok、続いて data または error、さらに request_id）を出力し、結果ごとに終了コードを返します。たとえば、見つからない場合は4、競合は5、古いリビジョンは6、レート制限は7です。公式プラグインにも同梱されています。

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

--idempotency-key を付けると、書き込みを安全に再試行できます。すべてのコマンドは CLI リファレンスに載っています。

キオスクアプリは静的な Web ページです。公開すると、パッカーがランタイムを追加するため、ビルド手順なしで、ページは window.screenrig を使えるようになります。ページは有効になるまで待機でき、名前付きイベントを送信でき、変更がそのアプリを実行しているすべてのスクリーンに数秒以内に届くキー/値ストアを読み取れます。Android と BrightSign 向けのキオスクソフトウェアでは、チャットで作成、タップ、文言変更までを行った記録を見られ、ページから呼び出せるすべては SDK リファレンスに載っています。

screenRIG は https://api.screenrig.ai/mcp でリモート MCP サーバーを運用しています。Claude、ChatGPT、Grok は OAuth で接続します。人がアプリを承認し、プロジェクトと、読み取り専用、提案、管理のいずれかを選ぶと、アプリはスクリーン、プレイリスト、メディア、スケジュール、Webhook、レポート向けのツールを使えるようになります。ファイルのアップロードとアプリのパックはお使いのマシン上で行うため、公式プラグインが引き続き完全なワークフローです。詳細は MCP サーバーのリファレンスに、他の製品との比較は MCP サーバーの比較にあります。

普段使っているアシスタントから始めたいですか。ChatGPT、Claude、Gemini、Grok でテレビを操作するページに各インストール手順が載っており、AI エージェントはどうやってテレビにコンテンツを表示するのかがすべてをカバーしています。依頼の例は AI デジタルサイネージに載っています。

エージェントの返答を1つずつ見ていきます。この実行は実際のもので、2026年10月26日に screenRIG のステージング環境で行いました。カウントダウンとそのラベルはデモ用のコンテンツです。

スクリーンのリビジョンは ETag です。それを条件として送り返すと、その間に誰もスクリーンを変更していない場合に限り、書き込みが適用されます。

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

最初の1回は適用され、スクリーンはリビジョン22に移りました。古いリビジョンのまま再送すると拒否され、その応答（ここでは一部省略）に現在のリビジョンが示されるため、クライアントは読み直して再試行できます。

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

すべてのエラーには、安定したコード、説明へのリンク、次に何をすべきかを示すヒントが付きます。存在しない ID には404が返り、正しい ID の探し方がヒントで示されます。冪等キーを付けた作成は、セッションで示したように、安全に再試行できます。

制限に達すると 429 が Retry-After とともに返り、CLI は終了コード7で終了します。スクリプトにとって重要なのは次のとおりです。

CLI リファレンスには、各制限がそれを守るコマンドの隣に載っており、プランごとの制限は料金にあります。

• イベントストリーム。CLI と、再生可能な REST ストリームのどちらでもイベントを受け取れます。スクリーンが60秒オフラインになるとイベントが1件発生し、復帰したときにも発生します。再接続すると、最後のカーソルから無料で再開します。ヘッドレスデジタルサイネージでは、ストリームを読み取るパイプラインの記録を見られます。
• 通知。組織が保持できる通知は、すべてのプロジェクトを合わせて最大50です。スクリーンがオフラインになったとき、ディスプレイを失ったとき、高温になったとき、コンテンツを保存できないとき、コンテンツの更新で止まったとき、再生せずにエラーを表示するとき、クラッシュを繰り返すときに、メールまたは署名付き Webhook が送られます。条件は、既定では10分間続いた時点で発火するため、短時間の再接続は通知されず、crashing は即座に発火します。Webhook は自分で運用する HTTPS エンドポイントで、生のプロジェクトイベントも受け取れます。すべての配信には署名が付くため、古いタイムスタンプは拒否し、比較は一定時間で行い、配信またはイベントの ID で重複を排除してください。配信は少なくとも1回で、順序は保証されないためです。応答は10秒以内に返してください。失敗した試行は、バックオフしながら24時間再試行され、72時間連続で失敗した通知は無効になります。

Webhook を検証するにはどうすればよいですか。

各配信には ScreenRig-Signature: t=<unix seconds>,v1=<hex> が付いています。v1 は、通知のシークレットをキーとして <t>.<raw body> に対して計算した HMAC-SHA256 で、ScreenRig-Event-Id は再試行しても変わりません。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);
}

書き込みはどれくらい速くスクリーンに届きますか。

記録されたパイプラインの実行では、スクリプトがボードの1行を書き込み、イベントストリームがその全経路を伝えました。書き込み、変更、そして Player 自身がそのページにそのリビジョンを適用したという報告です（時刻は UTC で、イベントとリビジョンだけに絞っています）。

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"

書き込みが受理されてから Player が表示するまで1.8秒です。スクリーンが表示するまで先に進めてはならないジョブは、最後の行を待てば、失敗を検知できます。実行全体はヘッドレスデジタルサイネージをご覧ください。

• MCP サブスクリプション。リモートサーバーはアシスタントをイベントに登録できるため、スクリーンがオフラインになったことを知らせてもらえます。詳細は MCP サーバーのリファレンスをご覧ください。

screenRIG のプレイリストを再生する Player は12種類あります。Web Player、Android と Google TV、Amazon Signage Stick、Apple TV、macOS、iPhone と iPad、Windows、Linux、Raspberry Pi、LG webOS Signage、Samsung Smart Signage（Tizen）、BrightSign です。どの Player もペアリングコードを表示し、1回の呼び出しでそれを取得します。Apple TV は画像、動画、ストリーム、カードを再生します。Web ページと独自のアプリには別の Player が必要です。対応の一覧表はPlayerにあります。

screenRIG にはデジタルサイネージ API がありますか。

はい。REST API はスクリーン、プレイリスト、メディア、スケジュール、アプリ、Webhook などをカバーし、1つの OpenAPI ファイルがすべてのオペレーションを記述しています。バージョン 0.3.0、サイズ 3 MB で、562のパスに736のオペレーション、1,059のスキーマがあります。プラグイン、Player、ダッシュボードは同じ HTTP オペレーションを使っています。API リファレンスにその一覧があり、OpenAPI 契約は1つのファイルです。

screenRIG は API ファーストのデジタルサイネージソフトウェアですか。

はい。API ファーストとは、API が先にあり、すべてのクライアントがそれを使うという意味で、ここではダッシュボード、CLI、エージェント、Player のすべてがそうです。ダッシュボードを開かずにパイプラインがスクリーンを動かす様子は、ヘッドレスデジタルサイネージをご覧ください。

自分のデータをスクリーンに送るにはどうすればよいですか。

カードのデータ、またはアプリのキー/値ストアに書き込みます。キー/値の Webhook は1つのキーに書き込む URL なので、POS、スプレッドシートのスクリプト、cron ジョブから、1回の HTTP POST でスクリーンにデータを送れます。購読しているアプリは、それを実行しているすべてのスクリーンで数秒以内に更新されます。

スクリーンがオフラインになったことはどうすれば分かりますか。

メールまたは署名付き Webhook を送る通知を作成するか、再生可能なイベントストリームを読み取ります。スクリーンは60秒でオフラインとみなされ、通知は既定で10分待ってから発火するため、短時間の再接続は通知されません。

レート制限に達するとどうなりますか。

API は429を返し、Retry-After ヘッダーで待つべき時間が示されます。CLI は終了コード7で終了し、retry_after_seconds を表示します。

スクリプトの下で API が変わることはありますか。

同じメジャーバージョン内の変更には互換性があります。新しいエンドポイント、任意のリクエストメンバー、新しい問題コードなどです。動作している呼び出しを壊す変更には新しいメジャーバージョンが必要で、少なくとも180日間は旧バージョンと並行して提供されます。

デジタルサイネージ API は無料ですか。

screenRIG は無料で、スクリーン数は無制限です。有料プランでは、ビジネスツール、より多くのメンバー、相談できる担当者、ガバナンス、契約条件が加わります。コードからの呼び出しはエージェントのリクエストとして数えられ、どのプランにも毎月一定数が含まれています。料金をご覧ください。

ここで見たすべての呼び出しが載っている REST API リファレンスを開くか、無料で始めてエージェントに呼び出させてください。エージェントが自分でサインアップする仕組みは エージェントで説明しています。