The CastWize API

A small, focused API for automating what you'd otherwise click through in Studio — no separate SDK to install.

What you can do

View your screens

List every screen on your team — name, resolution, last-seen time, and app version.

Manage playlists

List existing playlists, or create a new empty playlist by name.

Assign content to a screen

Point a screen's zone at a playlist — the same thing the Studio's assignment dropdown does, callable from your own code.

Getting an API key

1. In CastWize, go to Settings → API Keys.
2. Click Create key and give it a name so you remember what it's for.
3. Copy the key right away — it's shown to you only once and can't be retrieved again (you'd need to create a new one).

Authentication

Every request needs your API key in an Authorization header, as a Bearer token. All endpoints below are relative to /api/v1.

curl https://castwize.tv/api/v1/screens \
  -H "Authorization: Bearer cw_live_..."

Endpoints

GET/screens

Lists the screens on your team.

[
  {
    "id": "scr_abc123",
    "name": "Lobby TV",
    "orientation": "landscape",
    "resolutionWidth": 1920,
    "resolutionHeight": 1080,
    "zoneLayoutId": "zl_xyz",
    "appVersion": "1.4.2",
    "lastSeenAt": "2026-08-12T14:03:00.000Z"
  }
]

GET/zone-layouts

Lists the zone layouts available to your team — built-in ones (shared across every team) plus any custom ones you've created in Studio. A screen's zoneLayoutId (from GET /screens) refers to one of these. If a screen's layout has more than one zone, use one of its zones[].key values as the zoneKey in POST /schedules below.

[
  {
    "id": "builtin-fullscreen",
    "name": "Full Screen",
    "isBuiltIn": true,
    "aspectRatio": "16 / 9",
    "zones": [
      { "key": "main", "name": "Main", "xPct": 0, "yPct": 0, "widthPct": 100, "heightPct": 100 }
    ]
  },
  {
    "id": "zl_xyz",
    "name": "Image + Ticker",
    "isBuiltIn": false,
    "aspectRatio": "16 / 9",
    "zones": [
      { "key": "main", "name": "Main", "xPct": 0, "yPct": 0, "widthPct": 60, "heightPct": 100 },
      { "key": "zone-2", "name": "Side panel", "xPct": 60, "yPct": 0, "widthPct": 40, "heightPct": 100 }
    ]
  }
]

GET/playlists

Lists the playlists on your team.

[
  {
    "id": "pl_abc123",
    "name": "Weekly specials",
    "isTemplate": false,
    "shuffle": false,
    "createdAt": "2026-08-01T09:00:00.000Z"
  }
]

POST/playlists

Creates a new, empty playlist. Add slides to it from Studio.

// Request body
{ "name": "Weekly specials" }

// 201 Response
{
  "id": "pl_abc123",
  "name": "Weekly specials",
  "isTemplate": false,
  "shuffle": false,
  "createdAt": "2026-08-12T14:03:00.000Z"
}

POST/schedules

Assigns a playlist to one of a screen's zones, effective immediately with no end date — the same result as picking a playlist in the Studio's assignment dropdown. Calling this again for the same screen + zone replaces the previous assignment (it doesn't stack a second one on top). zoneKey defaults to "main" if omitted, which is all you need for a typical single-zone screen. If a screen's layout has more than one zone, see GET /zone-layouts above to find its zone keys. Day/time recurrence and priority rules are only configurable from Studio today.

// Request body
{
  "screenId": "scr_abc123",
  "zoneKey": "main",
  "playlistId": "pl_abc123"
}

// 201 Response
{
  "id": "sch_abc123",
  "screenId": "scr_abc123",
  "zoneKey": "main",
  "playlistId": "pl_abc123",
  "priority": 0,
  "createdAt": "2026-08-12T14:03:00.000Z"
}

DELETE/schedules

Removes the current assignment for a screen's zone, leaving it with nothing scheduled. Pass screenId and zoneKey as query parameters — zoneKey defaults to "main" if omitted, same as POST /schedules.

DELETE /api/v1/schedules?screenId=scr_abc123&zoneKey=main

// 200 Response
{ "ok": true }

Errors

Errors come back as JSON, { "error": "message" }, with one of these status codes:

401 — missing, invalid, or revoked API key.
400 — the request body didn't pass validation.
404 — the screen or playlist ID doesn't exist on your team.