Call the digital signage API with curl
A script, CI job or server signs in as a service client. Ask the token endpoint for a 10-minute access token, then send it as a bearer. This lists the project's screens:
# 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"There is no refresh token: ask again when the token expires. A registered key can sign in instead of a secret, and Service clients shows both.
What does the digital signage REST API cover?
One OpenAPI contract describes every call. Each area has its own reference page with every operation's fields, a request template and its responses.
| Area | What your code can do | Reference |
|---|---|---|
| Screens | Pair and name screens, group them in folders and tags, assign a playlist, set a takeover, read health and uptime, take a screenshot, reboot, and schedule playlists, display power and reboots | Screens |
| Playlists | Create and update playlists and their pages, read their revisions and promote one | Playlists |
| Media | Upload images and video, organize folders and tags, replace a file and keep its versions | Media |
| Schedules | Run campaigns across a tagged fleet, and import schedule rows from a sheet. A screen's own playlist schedule sits with Screens | Campaigns, Schedule import |
| Apps | Upload a packed kiosk app and its releases, and read and write its key/value storage | Applications, Application storage |
| Card data | Feed live values to the 200+ ready-made apps | Card data |
| Webhooks and events | Receive signed webhooks, send email or webhook notifications on a screen's state, and read the replayable event stream | Webhooks, Notifications, Events |
| Reports and audit | Export reports as CSV, XLSX and PDF, schedule them by email, and verify the audit log's hash chain | Reports, Audit log |
The API reference lists every group, including alerts, single sign-on and user provisioning (SCIM).
How does the API sign in, and what can a caller do?
Every caller signs in with its own session, and a person approves each agent and app and creates each service client. Access tokens go in an Authorization: Bearer header and last 10 minutes.
- A server, script or CI job uses a service client with a key or secret and asks for a new token when one expires. A client holds up to two keys and two secrets, so you can rotate without downtime, and an organization holds up to 50 live service clients.
- An agent runs
screenrig login, and a person approves the code in the dashboard. A new agent with no account starts withscreenrig agent enroll. - A connected app such as Claude, ChatGPT or Grok opens the screenRIG consent page.
The person chooses how much the caller may do and in which areas: screens, content, playlists, advertising, reports and the project.
- Read only lists and reads.
- Propose also uploads media and proposes changes. The call succeeds with a review link, and nothing plays until a person approves the change in the dashboard.
- Manage also changes, publishes and spends.
A person ends any session from the dashboard's Access page, and its tokens stop working within seconds. Authentication and Service clients cover keys, rotation and errors.
Which interface should I use?
| Interface | Use it when | Reference |
|---|---|---|
| REST API | A service, script or CI job makes HTTP calls and you want one OpenAPI contract | REST API reference |
| CLI | You script a shell, a cron job or a terminal agent and want one JSON answer per command and an exit code for each outcome | CLI reference |
| Browser SDK | You build a kiosk app that runs on the Player and talks to it through window.screenrig | Kiosk app SDK |
| Remote MCP server | An AI assistant such as Claude, ChatGPT or Grok calls tools against your screens | MCP server |
| Official agent plugin | A terminal or chat agent publishes for you, with the skill and the CLI bundled | Quickstart |
Every interface reaches the same project, with the same project isolation, rate limits, idempotency and revision checks. The remote server covers the project's tools, including uploads. Steps that run on your machine, such as converting media and packing an app, stay in the CLI.
What does the CLI add?
The screenrig CLI wraps the API for shells, cron jobs and terminal agents. Every command prints one JSON envelope (ok, then data or error, with a request_id) and exits with a code for each outcome, such as 4 for not found, 5 for a conflict, 6 for a stale revision and 7 when rate limited. The official plugin bundles it.
screenrig screen list --tag Lobby
screenrig screen assign --tag Lobby --playlist-id pl_01EXAMPLEPLAYLIST000000Add --idempotency-key to retry a write safely. The CLI reference lists every command.
Where does the SDK fit?
A kiosk app is a static web page. When you publish it, the packer adds the runtime, so the page gets window.screenrig with no build step. The page can wait until it is active, send named events and read a key/value store whose changes reach every screen running the app within seconds. Kiosk software for Android and BrightSign records one built, tapped and reworded by chat, and the SDK reference lists everything the page can call.
What does the MCP server cover?
screenRIG runs a remote MCP server at https://api.screenrig.ai/mcp. Claude, ChatGPT or Grok connect with OAuth: a person approves the app, chooses the project and Read only, Propose or Manage, and the app gets tools for screens, playlists, media uploads, schedules, webhooks and reports. The official plugin adds the steps that run on your machine, such as converting media and packing apps. The MCP server reference has the details, and MCP servers compared sets the server against other products.
Prefer to start from the assistant you use? Control a TV with ChatGPT, Claude, Gemini or Grok shows each install path, and How can my AI agent put content on a TV? covers them all. AI digital signage lists example requests.
What did the API answer at each step?
The agent's answers, one by one. The run is real: 26 October 2026, on screenRIG's staging environment. The countdown and its label are demo content.
- Agent
The contract and sign-in. The version call needs no sign-in, and the contract is a single OpenAPI file. With the token, a list call returned the project's screens, including the one I was using.
- Agent
An error. My first card request put the label in the card's look. The API refused it and named the field: the label is live content, so it belongs in the card's data. I moved it, and the second request created the card.
- Agent
An idempotent create. I sent the playlist create twice with the same key, the way a client would after a lost reply. Both calls returned the same playlist, and the list shows one, not two.
- Agent
A revision check. I read the screen's revision, then assigned the playlist only if the screen was still at that revision. It applied, and the countdown was on the screen about two seconds later.
- Agent
The MCP server. Without a token it answers with a sign-in pointer, and its metadata names the three access levels a person can choose: Read only, Propose or Manage.

What stops a script from overwriting someone else's change?
A screen's revision is its ETag. Send it back as a condition, and the write applies only if nobody changed the screen in between:
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"'"}'The first time, this applied and the screen moved to revision 22. Sent again with the old revision, it was refused, and the answer (trimmed here) named the current one, so the client can read again and retry:
{"errors": [{"status": 412, "code": "revision_conflict", "current_revision": 22}]}Every error carries a stable code, a link to its description and a hint that says what to do next. A missing id answers 404 with a hint on how to find the right one. A create that carries an idempotency key is safe to retry, as the session showed.
What are the rate limits?
A limit answers 429 with Retry-After, and the CLI exits with code 7. These are the ones that matter to a script:
| What | Limit |
|---|---|
| One card's data or one key | 60 writes a minute, on every plan |
| Agent and webhook data writes | 60 a minute per organization on Standard and Plus, 600 on Premium and 3,000 on Enterprise |
| Schedule and takeover writes | 600 a minute per organization, 20 per screen and 60 per IP |
| Reboots, clear-cache, restart-app and update commands | 2 per screen every 10 minutes together, and 600 a minute per organization |
| Display power writes | 10 per screen a minute and 600 a minute per organization |
| Playback exports | 30 requests a minute per organization |
| Webhook test deliveries | 20 a minute per organization |
The CLI reference lists each limit next to the command it guards, and the plan limits are on pricing.
How do I get events and notifications instead of polling?
- Event stream. The CLI and a replayable REST stream both deliver events. A screen offline for 60 seconds raises one, and so does its return. A reconnect resumes from the last cursor, free. Headless digital signage records a pipeline reading the stream.
- Notifications. An organization holds up to 50 across its projects. An email or a signed webhook fires when a screen goes offline, loses its display, runs hot, cannot store its content, gets stuck on a content update, shows an error instead of playing or keeps crashing. A condition fires once it has lasted 10 minutes by default, so a quick reconnect stays quiet, and
crashingfires at once. A webhook is an HTTPS endpoint you run, and it can also receive raw project events. Every delivery is signed, so reject an old timestamp, compare in constant time and deduplicate on the delivery or event id, because delivery is at least once and unordered. Answer within 10 seconds. A failed attempt retries with backoff for 24 hours, and a notification that fails for 72 hours in a row is disabled.
How do I verify a webhook?
Each delivery carries ScreenRig-Signature: t=<unix seconds>,v1=<hex>, where v1 is an HMAC-SHA256 over <t>.<raw body> keyed with the notification's secret, and ScreenRig-Event-Id, which stays the same across retries. Compute it over the raw bytes before you parse the 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);
}How fast does a write reach the screen?
In the recorded pipeline run, a script wrote one board row and the event stream carried the whole path: the write, the change, and then the Player's own report that it had applied that revision to that page (times in UTC, trimmed to event and revision).
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"That is 1.8 seconds from an accepted write to the Player showing it. A job that must not go on until the screen shows a failure can wait for the last line. Headless digital signage has the whole run.
- MCP subscriptions. The remote server can subscribe an assistant to events, so it can tell you a screen went offline. The MCP server reference has the details.
Which Players can I target?
Twelve Players run screenRIG playlists: the web Player, Android and Google TV, the Amazon Signage Stick, Apple TV, macOS, iPhone and iPad, Windows, Linux, Raspberry Pi, LG webOS Signage, Samsung Smart Signage (Tizen) and BrightSign. Every Player shows a pairing code, and one call claims it. Apple TV plays images, video, streams and cards. Web pages and your own apps need another Player. Players has the full support table.
Frequently asked questions
Does screenRIG have a digital signage API?
Yes. A REST API covers screens, playlists, media, schedules, apps, webhooks and more, and one OpenAPI file describes every operation: version 0.3.0, a 3 MB file with 736 operations on 562 paths and 1,059 schemas. The plugin, the Players and the dashboard use the same HTTP operations. The API reference lists them, and the OpenAPI contract is one file.
Is screenRIG API-first digital signage software?
Yes. API-first means the API comes first and every client uses it, and here the dashboard, the CLI, agents and Players all do. Headless digital signage shows a pipeline running a screen with no dashboard open.
How do I push my own data to a screen?
Write it to a card's data or to an app's key/value store. A key/value webhook is a URL that writes one key, so a point of sale, a spreadsheet script or a cron job can push data to screens with one HTTP POST. An app that subscribes updates within seconds on every screen that runs it.
How do I know when a screen goes offline?
Create a notification that sends an email or a signed webhook, or read the replayable event stream. A screen counts as offline after 60 seconds, and a notification waits 10 minutes by default before it fires, so a quick reconnect stays quiet.
What happens when I hit a rate limit?
The API answers 429, and its Retry-After header says how long to wait. The CLI exits with code 7 and shows retry_after_seconds.
Will the API change under my script?
Changes within a major version are compatible: new endpoints, optional request members and new problem codes. A change that breaks a working call needs a new major version, which overlaps the old one for at least 180 days.
Is the digital signage API free?
screenRIG is free, with unlimited screens. Paid plans add business tools, more people, people to talk to, governance and contract terms. Calls from your code count as agent requests, and every plan allows some each hour. See pricing.
Make your first call
Open the REST API reference, which lists every call you saw here, or start free and let your agent make them. Agents explains how an agent signs itself up.
Related
More topics
screenRIG is free.
Install the official plugin, pair a screen and your agent publishes to it.