---
title: "Cast content to screens"
method: POST
path: "/v1/casts"
tags: ["casts"]
---

# Cast content to screens

`POST /v1/casts`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/casts`
- Auth: HTTP bearer

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

- object
  - `contentKind` 'media' | 'playlist' | 'app' | 'creative' | 'schedule', required: What kind of thing `contentId` names.
  - `contentId` string, required: The media, playlist, app instance, creative or schedule to put on air.
  - `contentName` string: Label for the cast (shown in the console). Defaults to "Cast".
  - `scopeKind` 'all' | 'node' | 'screens': 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: Location id, with `scopeKind: node`.
  - `screenIds` string[]: Screen ids, with `scopeKind: screens`.
  - `expiresAt` union: When the cast ends by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.
    - string
    - number

## Response `201`

Success.

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

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: `not_shared`: the content is not shared to one or more target locations.
- `404`: The content does not exist in this workspace.
- `422`: Invalid body, the scope matched no screens you can reach (`no_screens`), or the content cannot play (empty playlist, unprocessed media).
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)