# Digital signage REST API for your code and agents

> Canonical HTML: https://screenrig.ai/developers

The screenRIG digital signage REST API lets your service, script or AI agent manage screens, playlists, media, schedules, apps and webhooks. One OpenAPI file describes the calls. A CLI, browser SDK, remote MCP server and official agent plugin use the same platform.

Updated November 12, 2026.

Start with the [REST API reference](https://screenrig.ai/docs/api.md) and [service-client authentication](https://screenrig.ai/docs/service-clients.md). The [Screens reference](https://screenrig.ai/docs/api/screens.md) covers pairing and playlist assignment, and the [Playlists reference](https://screenrig.ai/docs/api/playlists.md) covers the content a screen plays. The curl example below makes the first authenticated request.

> **You:** Our deploy dashboard needs a release countdown on the platform team's TV, and I want to see exactly what the API does before we script it. Make the countdown and a playlist for it with plain curl, assign it to the screen, and show me what comes back at each step: the contract, sign-in, an idempotent create, a revision check, an error, and what the MCP server answers when it has no token.
>
> **Agent:** Done. The countdown is on the platform team's TV, counting down to the Acme billing v2 cutover. It took plain curl, a token and no dashboard. Here is what the API answered at each step.

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

```bash
# 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](https://screenrig.ai/docs/service-clients.md) 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](https://screenrig.ai/docs/api/screens.md) |
| Playlists | Create and update playlists and their pages, read their revisions and promote one | [Playlists](https://screenrig.ai/docs/api/playlists.md) |
| Media | Upload images and video, organize folders and tags, replace a file and keep its versions | [Media](https://screenrig.ai/docs/api/media.md) |
| Schedules | Run campaigns across a tagged fleet, and import schedule rows from a sheet. A screen's own playlist schedule sits with Screens | [Campaigns](https://screenrig.ai/docs/api/campaigns.md), [Schedule import](https://screenrig.ai/docs/api/schedule-import.md) |
| Apps | Upload a packed kiosk app and its releases, and read and write its key/value storage | [Applications](https://screenrig.ai/docs/api/applications.md), [Application storage](https://screenrig.ai/docs/api/owner-kv.md) |
| Card data | Feed live values to the 200+ ready-made apps | [Card data](https://screenrig.ai/docs/api/card-data.md) |
| Webhooks and events | Receive signed webhooks, send email or webhook notifications on a screen's state, and read the replayable event stream | [Webhooks](https://screenrig.ai/docs/api/webhooks.md), [Notifications](https://screenrig.ai/docs/api/notifications.md), [Events](https://screenrig.ai/docs/api/events.md) |
| Reports and audit | Export reports as CSV, XLSX and PDF, schedule them by email, and verify the audit log's hash chain | [Reports](https://screenrig.ai/docs/api/reports.md), [Audit log](https://screenrig.ai/docs/api/audit.md) |

The [API reference](https://screenrig.ai/docs/api.md) 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 with `screenrig 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](https://screenrig.ai/docs/authentication.md) and [Service clients](https://screenrig.ai/docs/service-clients.md) 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](https://screenrig.ai/docs/api.md) |
| 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](https://screenrig.ai/docs/cli.md) |
| Browser SDK | You build a kiosk app that runs on the Player and talks to it through `window.screenrig` | [Kiosk app SDK](https://screenrig.ai/docs/sdk.md) |
| Remote MCP server | An AI assistant such as Claude, ChatGPT or Grok calls tools against your screens | [MCP server](https://screenrig.ai/docs/mcp.md) |
| Official agent plugin | A terminal or chat agent publishes for you, with the skill and the CLI bundled | [Quickstart](https://screenrig.ai/docs/start.md) |

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.

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

Add `--idempotency-key` to retry a write safely. The [CLI reference](https://screenrig.ai/docs/cli.md) 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](https://screenrig.ai/digital-signage/kiosk-software.md) records one built, tapped and reworded by chat, and the [SDK reference](https://screenrig.ai/docs/sdk.md) 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](https://screenrig.ai/docs/mcp.md) has the details, and [MCP servers compared](https://screenrig.ai/compare/digital-signage-mcp-servers.md) sets the server against other products.

Prefer to start from the assistant you use? [Control a TV with ChatGPT](https://screenrig.ai/guides/control-tv-with-chatgpt.md), [Claude](https://screenrig.ai/guides/digital-signage-with-claude-code.md), [Gemini](https://screenrig.ai/guides/control-tv-with-gemini.md) or [Grok](https://screenrig.ai/guides/control-tv-with-grok.md) shows each install path, and [How can my AI agent put content on a TV?](https://screenrig.ai/guides/ai-agent-on-tv.md) covers them all. [AI digital signage](https://screenrig.ai/digital-signage/ai.md) 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.

![A countdown on the Player: Until the Acme billing v2 cutover, 5 days 6 hours 16 minutes, in the Avant Garde theme](https://screenrig.ai/static-resources/images/screenshots/landing/venues-developers-countdown-637d9f8f.webp)
*The countdown about two seconds after the assignment. Its time and label are content, kept apart from its look.*

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

```bash
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:

```json
{"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](https://screenrig.ai/docs/cli.md) lists each limit next to the command it guards, and the plan limits are on [pricing](https://screenrig.ai/pricing.md).

## 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](https://screenrig.ai/headless-digital-signage.md) 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 `crashing` fires 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:

```javascript
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).

```text
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](https://screenrig.ai/headless-digital-signage.md) 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](https://screenrig.ai/docs/mcp.md) has the details.

## Which Players can I target?

Twelve Players run screenRIG playlists: the web Player, [Android and Google TV](https://screenrig.ai/digital-signage/android-tv.md), the [Amazon Signage Stick](https://screenrig.ai/amazon-signage-stick.md), [Apple TV](https://screenrig.ai/digital-signage/apple-tv.md), macOS, iPhone and iPad, [Windows](https://screenrig.ai/digital-signage/windows.md), [Linux](https://screenrig.ai/digital-signage/linux.md), [Raspberry Pi](https://screenrig.ai/digital-signage/raspberry-pi.md), [LG webOS Signage](https://screenrig.ai/digital-signage/lg-webos.md), [Samsung Smart Signage (Tizen)](https://screenrig.ai/digital-signage/samsung-tizen.md) and [BrightSign](https://screenrig.ai/partners/brightsign.md). 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](https://screenrig.ai/docs/players.md) 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](https://screenrig.ai/docs/api.md) lists them, and the [OpenAPI contract](https://screenrig.ai/openapi.json) 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](https://screenrig.ai/headless-digital-signage.md) 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](https://screenrig.ai/pricing.md).

## Make your first call

Open the [REST API reference](https://screenrig.ai/docs/api.md), which lists every call you saw here, or [start free](https://screenrig.ai/docs/start.md) and let your agent make them. [Agents](https://screenrig.ai/docs/agents.md) explains how an agent signs itself up.

## Related

- [Digital Signage REST API Reference](https://screenrig.ai/docs/api.md): REST API for screens, playlists, media, apps and webhooks, generated from OpenAPI, with every operation, schema and problem type.
- [Headless Digital Signage (API-First Screens)](https://screenrig.ai/headless-digital-signage.md): Headless digital signage: a CI pipeline updates a TV through the API with curl, with no dashboard open and no one watching.
- [Publish Content to a TV Programmatically](https://screenrig.ai/guides/publish-content-to-tv-programmatically.md): Publish to a TV from code, a CI job or your AI agent, with proof it is playing. See the conversation first, then the short script.
- [Digital Signage CLI Command Reference](https://screenrig.ai/docs/cli.md): The CLI publishes media, playlists and apps to TVs and kiosks from a terminal or an agent. JSON output.
- [Digital Signage MCP Servers Compared (Nov 2026)](https://screenrig.ai/compare/digital-signage-mcp-servers.md): Eleven digital signage MCP servers compared from their own docs: where each runs, how it signs in, which plans include it and what holds a change.

## More topics

- [Digital Signage Apps, Extensions and Plugins](https://screenrig.ai/tools.md): screenRIG tools for the computer and phone you work on: a Chrome and Firefox extension, the iPhone, iPad and Apple Watch app, and an Omarchy plugin.
- [AI Digital Signage Software Run by Your Agent](https://screenrig.ai/digital-signage/ai.md): AI digital signage agents make content, publish it to TVs and keep it current. Use Claude, ChatGPT, Gemini or Grok, with example requests and real runs.
- [Omarchy Plugin for Digital Signage Screens](https://screenrig.ai/omarchy.md): The screenRIG plugin for Omarchy shows your screens in the bar, casts your desktop or a window live to TVs and chats with your coding agent.
- [Automated Digital Signage That Runs Itself](https://screenrig.ai/digital-signage/automation.md): Automated digital signage: screens switch by time, weather, data and events, alerts take over on their own, and you hear when a screen needs you.
- [All digital signage](https://screenrig.ai/digital-signage.md): Digital signage software your AI agent runs: pair a TV, stick, Raspberry Pi or PC, say what to show and the agent builds and checks it.

[Start free](https://screenrig.ai/docs/start.md). screenRIG is free.
