Emergencies API

Emergencies endpoints in the Brix REST API: 5 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/emergencies
POST /v1/emergencies
GET /v1/emergencies/{id}
POST /v1/emergencies/{id}/clear
POST /v1/emergencies/from-template/{templateId}

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/emergencies

Auth: Bearer token. Permission: emergency-override.view.

List emergency overrides, newest first. Use ?status=active to filter to overrides currently taking over screens.

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

curl "https://api.brixsignage.com/v1/emergencies" \
  -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": "emg_4d5e6f7a8b9c0d1e",
      "spaceId": "space_1a2b3c4d5e6f7a8b",
      "kind": "emergency",
      "status": "active",
      "severity": "critical",
      "headline": "Evacuate the building now",
      "body": "Use the nearest exit. Do not use the lifts.",
      "contentKind": null,
      "contentId": null,
      "contentName": null,
      "scopeKind": "all",
      "scopeNodeId": null,
      "nodeId": null,
      "screenCount": 42,
      "triggeredBy": "usr_5e6f7a8b9c0d1e2f",
      "triggeredAt": "2026-09-28T11:30:00.000Z",
      "expiresAt": null,
      "clearedBy": null,
      "clearedAt": null,
      "triggeredByName": "Sam Rivera",
      "clearedByName": null,
      "scopeName": "All screens",
      "confirmedCount": 0
    }
  ]
}

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/emergencies

Auth: Bearer token. Permission: emergency-override.create.

Trigger an emergency takeover across a set of screens. An emergency takes the highest priority and layers over each screen's normal content, so clearing it restores exactly what was playing before. Takes over the chosen screens now, above every schedule and cast, until cleared or expired. Clearing restores exactly what was playing. Notes. - The route is gated by emergency-override.create; the route registry's description names emergency-override.trigger, which is not a permission the API checks.

Request body: application/json

Field	Type	Required	Description
`headline`	string	yes	The message on every targeted screen. Required, non-blank.
`body`	string	no	Optional second line.
`severity`	"info" \| "warning" \| "critical"	no	Default `critical`.
`contentKind`	"media" \| "creative"	no	Attach content to show under the banner. Needs `contentId`.
`contentId`	string	no	The media or creative id. Needs `contentKind`.
`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 emergency 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 it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.

curl -X POST "https://api.brixsignage.com/v1/emergencies" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headline":"Evacuate the building now","body":"Use the nearest exit. Do not use the lifts.","severity":"critical","scopeKind":"all"}'

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": "emg_4d5e6f7a8b9c0d1e",
    "spaceId": "space_1a2b3c4d5e6f7a8b",
    "kind": "emergency",
    "status": "active",
    "severity": "critical",
    "headline": "Evacuate the building now",
    "body": "Use the nearest exit. Do not use the lifts.",
    "contentKind": null,
    "contentId": null,
    "contentName": null,
    "scopeKind": "all",
    "scopeNodeId": null,
    "nodeId": null,
    "screenCount": 42,
    "triggeredBy": "usr_5e6f7a8b9c0d1e2f",
    "triggeredAt": "2026-09-28T11:30:00.000Z",
    "expiresAt": null,
    "clearedBy": null,
    "clearedAt": null,
    "triggeredByName": "Sam Rivera",
    "clearedByName": null,
    "scopeName": "All screens",
    "confirmedCount": 0
  }
}

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: Missing headline, a half content pointer, a bad expiresAt, no reachable screens (no_screens), or content that cannot play (content_unplayable).

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

GET /v1/emergencies/{id}

Auth: Bearer token. Permission: emergency-override.view.

Retrieve one emergency override, including its scope, content, and expiry.

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

curl "https://api.brixsignage.com/v1/emergencies/{id}" \
  -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 emergency in this workspace (or outside your locations).

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

POST /v1/emergencies/{id}/clear

Auth: Bearer token. Permission: emergency-override.create.

Clear an active emergency override. This releases its screens back to their normal content, and the action is recorded in the activity log.

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

curl -X POST "https://api.brixsignage.com/v1/emergencies/{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 emergency in this workspace.

Response 409: already_inactive: already cleared or expired.

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

POST /v1/emergencies/from-template/{templateId}

Auth: Bearer token. Permission: emergency-override.create.

Trigger an emergency using a stored template. Any scope or expiry sent with the request overrides the template's defaults. Fires a stored template. Scope and expiry given here override the template's defaults. Send {} to use the template as stored.

Parameter	In	Type	Required	Description
`templateId`	path	string	yes	Emergency template id.

Request body: application/json

Field	Type	Required	Description
`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 emergency 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 it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.

curl -X POST "https://api.brixsignage.com/v1/emergencies/from-template/{templateId}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

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.

Response 401: Missing, expired or revoked bearer token.

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

Response 404: No such template, or its content is gone.

Response 422: Bad expiresAt, no reachable screens (no_screens), or content that cannot play.

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

GET /v1/emergencies

POST /v1/emergencies

GET /v1/emergencies/{id}

POST /v1/emergencies/{id}/clear

POST /v1/emergencies/from-template/{templateId}

Connect With Us

Message Received!