REST API

Quick start

List your screens, then tell one of them to reload its content:

export DS_KEY="ds_live_…"
BASE="https://app.digitalsign.co/api/v1"

# 1. Find the screen
curl -s "$BASE/screens?q=lobby" \
  -H "Authorization: Bearer $DS_KEY"

# 2. Send it a refresh command (use the id from step 1)
curl -s -X POST "$BASE/screens/scr_4k8m2q7v9x1c3b5n6p0w/commands" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"refresh"}'

The second call returns the queued command:

{ "id": "cmd_7t2r9w4y6u1i3o5p8a0s", "type": "refresh", "status": "pending" }

Base URL

https://app.digitalsign.co/api/v1

Requests and responses are JSON. Send Content-Type: application/json with a body on POST requests. The API accepts GET, POST and DELETE. Responses are sent with Cache-Control: no-store.

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer ds_live_…

• Create keys in the dashboard under Settings → Alerts & API, in the API keys section. Owners and admins (anyone with the Manage organization settings permission) can create and revoke keys.
• The full key is shown once, when you create it. DigitalSign stores only a hash, so copy it somewhere safe. The list shows the first characters, who created it and when it was last used.
• A key acts with its creator's permissions at the time of each request. If the creator is demoted, limited to certain locations or removed from the organization, the key changes or loses access with them.
• Revoking a key takes effect on the next request.
• The API sends Access-Control-Allow-Origin: *, so browsers can call it, but a key in browser code is visible to anyone who loads the page. Call the API from a server.

Permissions and plans

The API, like the dashboard, checks the key creator's role. Read endpoints return what that person can see: someone limited to certain locations only sees screens and locations there. Endpoints that change things need the permission listed with them below. By default:

If the organization is not on the Pro plan or higher, every request returns 402 upgrade_required. The audit log endpoint also needs the Enterprise plan.

Errors

Errors use one shape:

{
  "error": {
    "code": "invalid",
    "message": "type must be one of: refresh, restart_player, reboot_device, screenshot, clear_cache, set_volume, display_off, display_on, update_software, send_logs, identify"
  }
}

The message is written for people and may change; branch on the HTTP status and code.

Rate limit

Each key can make up to 120 requests per minute, counted in fixed one-minute windows. Request 121 in a window returns 429 with code rate_limited and these headers:

Retry-After: 60
X-RateLimit-Limit: 120

Wait the number of seconds in Retry-After, then retry. Requests with a malformed key are rejected with 401 and do not count toward any key's limit.

Conventions

• IDs are strings with a type prefix: scr_ screens, pls_ playlists, scn_ designs, ast_ media, sch_ schedules, loc_ locations, grp_ groups, dsr_ data sources, cmd_ commands.
• Times are ISO 8601 strings in UTC, for example 2026-10-02T14:03:11.512Z. Fields with no value are null.
• List endpoints return { "data": [ … ] }. Only the audit log is paginated; other lists return everything (designs are capped at 200 and media at 500, most recently changed first).

Endpoint summary

Account

GET /me

Returns the organization the key belongs to and the email of the person who created it. Useful to check a key works.

{
  "organization": {
    "id": "org_2b6n8m1q4w7e9r3t5y0u",
    "name": "Acme Coffee",
    "timezone": "America/Chicago",
    "plan": "pro"
  },
  "user": { "email": "[email protected]" }
}

plan is one of free, standard, ai, pro or enterprise.

Screens

GET /screens

Lists the screens the key can see, sorted by name.

{
  "data": [
    {
      "id": "scr_4k8m2q7v9x1c3b5n6p0w",
      "name": "Lobby",
      "status": "online",
      "location": { "id": "loc_9d3f5h7j1k2l4z6x8c0v", "name": "Downtown" },
      "tags": ["lobby", "menu"],
      "orientation": "landscape",
      "width": null,
      "height": null,
      "lastHeartbeatAt": "2026-10-02T14:03:11.512Z",
      "defaultPlaylistId": "pls_3e5r7t9y1u2i4o6p8a0s"
    }
  ]
}

• status: online (the display checked in within the last 90 seconds), offline, or unpaired (no display paired yet).
• orientation: landscape, portrait, landscape_flipped or portrait_flipped.
• width and height: a canvas size set on the screen, or null when none is set.
• defaultPlaylistId: what the screen plays when nothing is scheduled, or null.

GET /screens/{id}

Returns a screen's status, what it should be playing now, and the next scheduled change, worked out in the screen's time zone.

{
  "id": "scr_4k8m2q7v9x1c3b5n6p0w",
  "name": "Lobby",
  "status": "online",
  "timezone": "America/Chicago",
  "nowPlaying": {
    "scheduleId": "sch_1q3w5e7r9t2y4u6i8o0p",
    "scheduleName": "Lunch menu",
    "playlistId": "pls_6h8j0k2l4z1x3c5v7b9n",
    "playlistName": "Lunch"
  },
  "next": { "at": "2026-10-02T19:00:00.000Z", "playlistName": "Dinner" }
}

When no schedule applies and the screen has a default playlist, nowPlaying is { "playlistId", "playlistName", "default": true }. When nothing applies at all it is null. next is null when no change is coming up.

POST /screens/{id}/commands

Queues a remote command for the screen's display. Needs the Manage screens permission at the screen's location, and a display paired to the screen.

curl -s -X POST "$BASE/screens/scr_4k8m2q7v9x1c3b5n6p0w/commands" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"set_volume","payload":{"level":40}}'

{ "id": "cmd_7t2r9w4y6u1i3o5p8a0s", "type": "set_volume", "status": "pending" }

The display picks the command up on its next check-in. A command that is not picked up within 10 minutes expires. Sending the same command type again while one is still pending replaces the older one. Not every device supports every command; check the result with the endpoints below.

GET /screens/{id}/commands and GET /screens/{id}/commands/{commandId}

The screen's recent commands (newest first, ?limit= up to 100, default 20), or one command. status moves from pending to sent when the display picks it up, then to done, failed, unsupported or expired. A finished screenshot command includes screenshotUrl, an image link valid for at least an hour.

{
  "id": "cmd_7t2r9w4y6u1i3o5p8a0s",
  "type": "screenshot",
  "status": "done",
  "message": null,
  "createdAt": "2026-10-02T14:03:11.000Z",
  "sentAt": "2026-10-02T14:03:15.000Z",
  "completedAt": "2026-10-02T14:03:17.000Z",
  "createdBy": "[email protected]",
  "screenshotUrl": "https://…"
}

POST /screens/pair

Creates a screen and pairs it with the display showing a pairing code. Needs the Manage screens permission (at locationId, if given).

{ "id": "scr_0z2x4c6v8b1n3m5q7w9e", "name": "Drive-thru" }

Returns 400 if no display is currently showing that code.

Playlists

GET /playlists

Lists playlists, most recently updated first. items is the number of items.

{
  "data": [
    {
      "id": "pls_6h8j0k2l4z1x3c5v7b9n",
      "name": "Lunch",
      "items": 6,
      "shuffle": false,
      "updatedAt": "2026-10-01T16:42:05.118Z"
    }
  ]
}

GET /playlists/{id}

Returns a playlist and its items in play order.

{
  "id": "pls_6h8j0k2l4z1x3c5v7b9n",
  "name": "Lunch",
  "shuffle": false,
  "loop": true,
  "totalMs": 40000,
  "items": [
    {
      "id": "pli_5g7h9j1k3l2z4x6c8v0b",
      "kind": "scene",
      "title": "Soup of the day",
      "enabled": true,
      "durationMs": 10000,
      "designId": "scn_8u0i2o4p6a1s3d5f7g9h",
      "assetId": null,
      "playlistId": null
    },
    {
      "id": "pli_2w4e6r8t0y1u3i5o7p9a",
      "kind": "asset",
      "title": "promo.mp4",
      "enabled": true,
      "durationMs": 30000,
      "designId": null,
      "assetId": "ast_3s5d7f9g1h2j4k6l8z0x",
      "playlistId": null
    }
  ]
}

• kind: scene (a design), asset (media), playlist (a nested playlist) or url (a web page).
• durationMs: how long the item shows: its own duration if set, else the video's length for videos, else the playlist default. null for nested playlists and videos of unknown length.
• totalMs: the sum of durationMs for enabled items.

POST /playlists

Creates an empty playlist. Needs the Create designs permission.

New playlists use the default settings: 10-second items, fade transition, loop on, shuffle off. Change these in the dashboard.

{ "id": "pls_1a3s5d7f9g2h4j6k8l0z", "name": "Fall promos" }

POST /playlists/{id}/items

Appends 1 to 100 items to the end of a playlist. A playlist holds up to 500 items. Needs the Edit designs permission. If any item is invalid (an unknown kind, or a missing id), the request returns 400 and nothing is added.

curl -s -X POST "$BASE/playlists/pls_1a3s5d7f9g2h4j6k8l0z/items" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"kind":"scene","designId":"scn_8u0i2o4p6a1s3d5f7g9h"},{"kind":"url","url":"https://status.acme.example"}]}'

{ "added": 2 }

Designs and templates

GET /designs

Lists up to 200 designs, most recently updated first.

{
  "data": [
    {
      "id": "scn_8u0i2o4p6a1s3d5f7g9h",
      "name": "Soup of the day",
      "width": 1920,
      "height": 1080,
      "updatedAt": "2026-09-30T11:20:44.903Z"
    }
  ]
}

POST /designs

Creates a design from a template, or from a design document. Needs the Create designs permission.

curl -s -X POST "$BASE/designs" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Store closed","templateId":"builtin:announcement-alert"}'

{ "id": "scn_2p4o6i8u0y1t3r5e7w9q", "name": "Store closed" }

GET /templates

Lists your organization's saved templates (newest first), then the built-in templates. Built-in ids start with builtin:.

{
  "data": [
    {
      "id": "builtin:announcement-alert",
      "name": "Important notice",
      "category": "announcement",
      "description": "High-contrast notice for closures, weather and changes.",
      "builtIn": true,
      "width": 1920,
      "height": 1080
    }
  ]
}

Media

GET /assets

Lists up to 500 items from the media library, newest first. Failed uploads are left out.

{
  "data": [
    {
      "id": "ast_3s5d7f9g1h2j4k6l8z0x",
      "name": "promo.mp4",
      "kind": "video",
      "mime": "video/mp4",
      "bytes": 18432011,
      "status": "ready",
      "createdAt": "2026-09-28T09:12:37.440Z"
    }
  ]
}

kind is image, video or web. status is uploading, processing or ready. mime and bytes can be null (for example, for web pages).

Schedules and overrides

GET /schedules

Lists schedules that have not ended, highest priority first. Blocks that belong to a daypart program are not included.

{
  "data": [
    {
      "id": "sch_1q3w5e7r9t2y4u6i8o0p",
      "name": "Lunch menu",
      "kind": "standard",
      "priority": 10,
      "playlistId": "pls_6h8j0k2l4z1x3c5v7b9n",
      "enabled": true,
      "startsAt": null,
      "endsAt": null,
      "startDate": "2026-10-01",
      "endDate": null,
      "condition": null
    }
  ]
}

condition is the rule set on the schedule in the dashboard, or null.

POST /schedules

Creates a schedule and publishes it. Needs the Publish to screens permission, plus Manage schedules over every target: targeting all, a group or a tag needs organization-wide rights; location managers can target their own locations and the screens in them.

Targets. Each target is one of:

• { "kind": "all" }: every screen
• { "kind": "location", "refId": "loc_…" }: a location or region, including everything under it
• { "kind": "group", "refId": "grp_…" }: a screen group
• { "kind": "screen", "refId": "scr_…" }: one screen
• { "kind": "tag", "tag": "drive-thru" }: screens with a tag (up to 40 characters)

Rules. Each rule is { "recurrence": …, "start": "HH:MM", "end": "HH:MM" }. Times are 24-hour (00:00 to 24:00) in each screen's local time zone, and start and end must differ. recurrence is one of:

• { "type": "weekly", "days": [1, 2, 3, 4, 5] }: days of the week, 0 = Sunday to 6 = Saturday
• { "type": "monthly", "weekday": 2, "nth": 1 }: the nth weekday of the month; nth is 1 to 5, or -1 for the last
• { "type": "dates", "dates": ["2026-12-24", "2026-12-31"] }: specific dates (up to 366)

curl -s -X POST "$BASE/schedules" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday lunch",
    "playlistId": "pls_6h8j0k2l4z1x3c5v7b9n",
    "rules": [{ "recurrence": { "type": "weekly", "days": [1,2,3,4,5] }, "start": "11:00", "end": "14:00" }],
    "targets": [{ "kind": "tag", "tag": "menu" }]
  }'

{ "id": "sch_9o7i5u3y1t2r4e6w8q0a" }

DELETE /schedules/{id}

Deletes a schedule. Needs the same rights as creating it, over every place it currently targets.

{ "deleted": true }

POST /overrides

Plays a playlist right away for a set time, above normal schedules. Creates a schedule of kind override with priority 70, starting now. Same permissions as POST /schedules.

{ "id": "sch_4r6t8y0u2i1o3p5a7s9d" }

The id is a schedule id. To end the override early, delete it with DELETE /schedules/{id}.

Locations and groups

GET /locations

Lists regions and locations as a flat list, each region followed by what is under it. People limited to certain locations see only those and what is under them.

{
  "data": [
    {
      "id": "loc_7b9n1m3q5w2e4r6t8y0u",
      "name": "Texas",
      "kind": "region",
      "parentId": null,
      "timezone": "America/Chicago",
      "city": null
    },
    {
      "id": "loc_9d3f5h7j1k2l4z6x8c0v",
      "name": "Downtown",
      "kind": "location",
      "parentId": "loc_7b9n1m3q5w2e4r6t8y0u",
      "timezone": "America/Chicago",
      "city": "Austin"
    }
  ]
}

timezone is the effective time zone: the location's own, else its region's, else the organization's.

GET /groups

Lists screen groups, sorted by name.

{
  "data": [
    {
      "id": "grp_5v7b9n1m3q2w4e6r8t0y",
      "name": "Drive-thru boards",
      "kind": "smart",
      "description": null
    }
  ]
}

kind is manual (screens added by hand) or smart (screens matched by a rule).

POST /groups

Creates a screen group. Needs the Manage screens permission.

A rule has at least one of:

• locationIds: array of location ids (up to 200). Matches screens at any of them, including sub-locations.
• tags: array of tags (up to 30). Matches screens with any of them.
• orientation: landscape or portrait (flipped orientations match too).

A screen joins the group when it matches every part of the rule that is set. New screens join automatically.

curl -s -X POST "$BASE/groups" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Portrait menus","rule":{"tags":["menu"],"orientation":"portrait"}}'

{ "id": "grp_8q0w2e4r6t1y3u5i7o9p" }

A manual group from a list of screens:

curl -s -X POST "$BASE/groups" \
  -H "Authorization: Bearer $DS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Front counter","screenIds":["scr_4k8m2q7v9x1c3b5n6p0w","scr_0z2x4c6v8b1n3m5q7w9e"]}'

{ "id": "grp_1m3n5b7v9c2x4z6l8k0j" }

Data sources

GET /data-sources

Lists data connections (the feeds that power data-driven designs), sorted by name. Connection settings and secrets are not returned.

{
  "data": [
    {
      "id": "dsr_6y8u0i2o4p1a3s5d7f9g",
      "name": "Menu prices",
      "kind": "csv",
      "rows": 42,
      "fields": ["item", "price", "available"],
      "lastFetchedAt": "2026-10-02T13:55:00.000Z",
      "lastError": null
    }
  ]
}

kind is rest, rss, csv, webhook, square or shopify. rows and fields describe the most recent fetch.

Proof of play and campaigns

Both endpoints need the View analytics permission. Ranges are rolling: days=7 means the 7 × 24 hours before now.

GET /playback

Returns proof-of-play records: one row per item shown, oldest first.

{
  "data": [
    {
      "started_at": "2026-10-02T12:00:04.210Z",
      "ended_at": "2026-10-02T12:00:14.215Z",
      "seconds": "10",
      "completed": "yes",
      "screen": "Lobby",
      "location": "Downtown",
      "playlist": "Lunch",
      "content": "Soup of the day"
    }
  ],
  "truncated": false
}

• All values are strings. completed is yes or no; content is the design or media name.
• At most 10,000 rows are returned. If the range has more, you get the most recent 10,000 plays (still oldest first) and truncated: true. Ask for fewer days to see the whole range.

GET /campaigns

Plays, hours on screen and reach for each playlist in the range, most plays first.

{
  "data": [
    {
      "playlistId": "pls_6h8j0k2l4z1x3c5v7b9n",
      "name": "Lunch",
      "plays": 18240,
      "hours": 50.7,
      "screens": 12,
      "locations": 4,
      "first": "2026-09-02T15:00:02.004Z",
      "last": "2026-10-02T14:02:51.330Z"
    }
  ]
}

hours is rounded to one decimal. first and last are the first and last plays in the range. A playlist that has since been deleted shows as Deleted playlist.

Audit log

GET /audit-log

Returns audit log entries, newest first. Needs the Enterprise plan and the Manage organization settings permission.

{
  "data": [
    {
      "id": "aud_0p2o4i6u8y1t3r5e7w9q",
      "at": "2026-10-02T13:41:09.871Z",
      "actor": "[email protected]",
      "action": "schedule.created",
      "target": "sch_9o7i5u3y1t2r4e6w8q0a",
      "details": { "name": "Weekday lunch", "kind": "standard" }
    }
  ],
  "next": "2026-10-02T13:41:09.871Z|aud_0p2o4i6u8y1t3r5e7w9q"
}

Keep requesting with before=<next> (URL-encoded) until next is null.

See also

Webhooks: get a signed HTTP request when screens go offline, schedules publish, start or end, or content plays.