Casts API

Casts endpoints in the Brix REST API for digital signage: 3 operations (GET, POST). Each lists its path, auth, required permission and a curl example.

View as Markdown · For AI agents: the full docs index is at /llms.txt

Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.

GET /v1/casts
POST /v1/casts
POST /v1/casts/{id}/clear

Every 4xx and 5xx response below returns this body:

Field	Type	Description
`error`	string	Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …
`message`	string	Human-readable explanation. Safe to show an operator.
`requestId`	string	Present on 5xx: quote it to support.

GET /v1/casts

Auth: Bearer token. Permission: screen.cast.

List casts, which are timed content takeovers, newest first. Use ?status=active to filter to casts currently on air, and ?limit (up to 500, default 200) to bound the number of results. Cast history is kept indefinitely.

Parameter	In	Type	Required	Description
`status`	query	"active" \| "cleared" \| "expired"	no	Only casts in this state.
`limit`	query	integer	no	At most this many, newest first (default 200, max 500).

curl "https://api.brixsignage.com/v1/casts" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	array of Override
`data[].id`	string	Override (cast_… or emg_…) id.
`data[].spaceId`	string	Workspace id.
`data[].kind`	"emergency" \| "cast"
`data[].status`	"active" \| "cleared" \| "expired"
`data[].severity`	"info" \| "warning" \| "critical"	Always `info` for a cast.
`data[].headline`	string	An emergency's message; for a cast, the content's name (or "Cast").
`data[].body`	string \| null
`data[].contentKind`	"media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null
`data[].contentId`	string \| null
`data[].contentName`	string \| null	Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists.
`data[].scopeKind`	"all" \| "node" \| "screens"
`data[].scopeNodeId`	string \| null	The location, when `scopeKind` is `node`.
`data[].nodeId`	string \| null	Location the override is attributed to (null = workspace root).
`data[].screenCount`	integer	Screens targeted, snapshotted when it started.
`data[].triggeredBy`	string	User id, or `system`.
`data[].triggeredAt`	string	ISO-8601 timestamp (UTC).
`data[].expiresAt`	string \| null	Auto-clear time; null = until cleared.
`data[].clearedBy`	string \| null
`data[].clearedAt`	string \| null
`data[].triggeredByName`	string	Display name of `triggeredBy`.
`data[].clearedByName`	string \| null
`data[].scopeName`	string \| null	Location name, `All screens`, or null for a screen list.
`data[].confirmedCount`	integer \| null	Active emergencies only: screens confirmed showing it now. Null otherwise.

{
  "data": [
    {
      "id": "cast_9f2c4a1b7d3e5f60",
      "spaceId": "space_1a2b3c4d5e6f7a8b",
      "kind": "cast",
      "status": "active",
      "severity": "info",
      "headline": "Friday lunch special",
      "body": null,
      "contentKind": "media",
      "contentId": "med_0c1d2e3f4a5b6c7d",
      "contentName": "Friday lunch special",
      "scopeKind": "screens",
      "scopeNodeId": null,
      "nodeId": null,
      "screenCount": 2,
      "triggeredBy": "usr_5e6f7a8b9c0d1e2f",
      "triggeredAt": "2026-09-28T11:30:00.000Z",
      "expiresAt": "2026-09-28T13:30:00.000Z",
      "clearedBy": null,
      "clearedAt": null,
      "triggeredByName": "Sam Rivera",
      "clearedByName": null,
      "scopeName": null,
      "confirmedCount": null
    }
  ]
}

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 5XX: Server error. The body carries a requestId to quote to support.

POST /v1/casts

Auth: Bearer token. Permission: screen.cast.

Put content on air across a set of screens for a period of time, after which the screens automatically revert to their normal content. Send contentKind (media, playlist, app, creative, or schedule), contentId, scopeKind, and optionally scopeNodeId, screenIds, and expiresAt. scopeKind accepts all, node, or screens and defaults to all: a request sent with no scope casts to every screen the caller can reach. An active emergency override takes priority over a cast, and the cast resumes automatically once the emergency is cleared. Puts one piece of content on the chosen screens now, above their schedule, until it expires or is cleared. An emergency still pre-empts a cast.

Request body: application/json

Field	Type	Required	Description
`contentKind`	"media" \| "playlist" \| "app" \| "creative" \| "schedule"	yes	What kind of thing `contentId` names.
`contentId`	string	yes	The media, playlist, app instance, creative or schedule to put on air.
`contentName`	string	no	Label for the cast (shown in the console). Defaults to "Cast".
`scopeKind`	"all" \| "node" \| "screens"	no	Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). Defaults to `all`: omit it and the cast goes to EVERY screen you can reach.
`scopeNodeId`	string	no	Location id, with `scopeKind: node`.
`screenIds`	array of string	no	Screen ids, with `scopeKind: screens`.
`expiresAt`	string \| number \| null	no	When the cast ends by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.

curl -X POST "https://api.brixsignage.com/v1/casts" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentKind":"media","contentId":"med_0c1d2e3f4a5b6c7d","contentName":"Friday lunch special","scopeKind":"screens","screenIds":["scr_1a2b3c4d5e6f7a8b","scr_2b3c4d5e6f7a8b9c"],"expiresAt":"2026-09-28T13:30:00.000Z"}'

Response 201: Success.

Field	Type	Description
`data`	Override	A cast or an emergency override.
`data.id`	string	Override (cast_… or emg_…) id.
`data.spaceId`	string	Workspace id.
`data.kind`	"emergency" \| "cast"
`data.status`	"active" \| "cleared" \| "expired"
`data.severity`	"info" \| "warning" \| "critical"	Always `info` for a cast.
`data.headline`	string	An emergency's message; for a cast, the content's name (or "Cast").
`data.body`	string \| null
`data.contentKind`	"media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null
`data.contentId`	string \| null
`data.contentName`	string \| null	Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists.
`data.scopeKind`	"all" \| "node" \| "screens"
`data.scopeNodeId`	string \| null	The location, when `scopeKind` is `node`.
`data.nodeId`	string \| null	Location the override is attributed to (null = workspace root).
`data.screenCount`	integer	Screens targeted, snapshotted when it started.
`data.triggeredBy`	string	User id, or `system`.
`data.triggeredAt`	string	ISO-8601 timestamp (UTC).
`data.expiresAt`	string \| null	Auto-clear time; null = until cleared.
`data.clearedBy`	string \| null
`data.clearedAt`	string \| null
`data.triggeredByName`	string	Display name of `triggeredBy`.
`data.clearedByName`	string \| null
`data.scopeName`	string \| null	Location name, `All screens`, or null for a screen list.
`data.confirmedCount`	integer \| null	Active emergencies only: screens confirmed showing it now. Null otherwise.

{
  "data": {
    "id": "cast_9f2c4a1b7d3e5f60",
    "spaceId": "space_1a2b3c4d5e6f7a8b",
    "kind": "cast",
    "status": "active",
    "severity": "info",
    "headline": "Friday lunch special",
    "body": null,
    "contentKind": "media",
    "contentId": "med_0c1d2e3f4a5b6c7d",
    "contentName": "Friday lunch special",
    "scopeKind": "screens",
    "scopeNodeId": null,
    "nodeId": null,
    "screenCount": 2,
    "triggeredBy": "usr_5e6f7a8b9c0d1e2f",
    "triggeredAt": "2026-09-28T11:30:00.000Z",
    "expiresAt": "2026-09-28T13:30:00.000Z",
    "clearedBy": null,
    "clearedAt": null,
    "triggeredByName": "Sam Rivera",
    "clearedByName": null,
    "scopeName": null,
    "confirmedCount": null
  }
}

Response 401: Missing, expired or revoked bearer token.

Response 403: not_shared: the content is not shared to one or more target locations.

Response 404: The content does not exist in this workspace.

Response 422: Invalid body, the scope matched no screens you can reach (no_screens), or the content cannot play (empty playlist, unprocessed media).

Response 5XX: Server error. The body carries a requestId to quote to support.

POST /v1/casts/{id}/clear

Auth: Bearer token. Permission: screen.cast.

End a cast immediately and return its screens to their scheduled content. Ends an active cast; its screens return to their scheduled content immediately.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Cast id.

curl -X POST "https://api.brixsignage.com/v1/casts/{id}/clear" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	Override	A cast or an emergency override.
`data.id`	string	Override (cast_… or emg_…) id.
`data.spaceId`	string	Workspace id.
`data.kind`	"emergency" \| "cast"
`data.status`	"active" \| "cleared" \| "expired"
`data.severity`	"info" \| "warning" \| "critical"	Always `info` for a cast.
`data.headline`	string	An emergency's message; for a cast, the content's name (or "Cast").
`data.body`	string \| null
`data.contentKind`	"media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null
`data.contentId`	string \| null
`data.contentName`	string \| null	Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists.
`data.scopeKind`	"all" \| "node" \| "screens"
`data.scopeNodeId`	string \| null	The location, when `scopeKind` is `node`.
`data.nodeId`	string \| null	Location the override is attributed to (null = workspace root).
`data.screenCount`	integer	Screens targeted, snapshotted when it started.
`data.triggeredBy`	string	User id, or `system`.
`data.triggeredAt`	string	ISO-8601 timestamp (UTC).
`data.expiresAt`	string \| null	Auto-clear time; null = until cleared.
`data.clearedBy`	string \| null
`data.clearedAt`	string \| null
`data.triggeredByName`	string	Display name of `triggeredBy`.
`data.clearedByName`	string \| null
`data.scopeName`	string \| null	Location name, `All screens`, or null for a screen list.
`data.confirmedCount`	integer \| null	Active emergencies only: screens confirmed showing it now. Null otherwise.

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No such cast in this workspace.

Response 409: already_inactive: the cast is already cleared or expired.

Response 5XX: Server error. The body carries a requestId to quote to support.

GET /v1/casts

POST /v1/casts

POST /v1/casts/{id}/clear

Connect With Us

Message Received!