Brix Casts API

openapi: 3.2.0
info:
  title: Brix Casts API
  version: '1'
  summary: 'Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.'
  description: 'Generated from the route table the API actually mounts

    (`apps/api/routes.snapshot.json`), the description each route is required to

    carry (`tests/contracts/route-registry.json`), and request/response schemas

    (`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a

    route that does not exist or omit one that does.


    **Schemas.** 447 operations carry request and response schemas

    (`x-brix-schema: verified`). Each is checked in CI against the response the

    real handler returns — a missing, mistyped or undeclared field fails the build.

    The remaining operations are route-level only (`x-brix-schema: none`): their

    path, method, permission and purpose are exact, but the shape of `data` is not

    yet modelled, and we would rather say so than publish a schema that validates

    against nothing. Objects are open: a new field is not a breaking change.


    **Envelope.** Success bodies are `{ "data": … }`. Failures are

    `{ "error": "", "message": "…" }`, plus `requestId` on a 5xx.

    Many list routes page opt-in (see each operation): pass `?limit=` and

    follow `nextCursor` via `?cursor=` until it is null.


    **Authentication.** `Authorization: Bearer ` with an API key

    (`ak_…`, created in the console under Settings → API & MCP) or a user session. An

    API key carries a creator-chosen set of `resource.verb` permissions and may be

    pinned to one location''s subtree; a key can never be granted a permission its

    creator does not hold. The permission an operation needs is in

    `x-brix-permission` and in its security requirement.


    **Tenancy.** Every request resolves to one workspace. A resource belonging to

    another tenant returns 404, never 403, so a response never confirms that an

    account exists.


    **Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry

    after the `Retry-After` interval.'
servers:
- url: https://api.brixsignage.com
  description: Production
security:
- bearerAuth: []
tags:
- name: casts
paths:
  /v1/casts:
    get:
      operationId: listCasts
      tags:
      - casts
      summary: List casts
      description: 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.
      x-brix-permission: screen.cast
      x-brix-schema: verified
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - cleared
          - expired
        description: Only casts in this state.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
        description: At most this many, newest first (default 200, max 500).
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Override'
                required:
                - data
              example:
                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
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - screen.cast
    post:
      operationId: castContent
      tags:
      - casts
      summary: Cast content to screens
      description: '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.'
      x-brix-permission: screen.cast
      x-brix-schema: verified
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contentKind:
                  type: string
                  enum:
                  - media
                  - playlist
                  - app
                  - creative
                  - schedule
                  description: What kind of thing `contentId` names.
                contentId:
                  type: string
                  description: The media, playlist, app instance, creative or schedule to put on air.
                contentName:
                  description: Label for the cast (shown in the console). Defaults to "Cast".
                  type: string
                scopeKind:
                  description: '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.**'
                  type: string
                  enum:
                  - all
                  - node
                  - screens
                scopeNodeId:
                  description: 'Location id, with `scopeKind: node`.'
                  type: string
                screenIds:
                  description: 'Screen ids, with `scopeKind: screens`.'
                  type: array
                  items:
                    type: string
                expiresAt:
                  description: 'When the cast ends by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.'
                  anyOf:
                  - anyOf:
                    - type: string
                    - type: number
                  - type: 'null'
              required:
              - contentKind
              - contentId
            example:
              contentKind: media
              contentId: med_0c1d2e3f4a5b6c7d
              contentName: Friday lunch special
              scopeKind: screens
              screenIds:
              - scr_1a2b3c4d5e6f7a8b
              - scr_2b3c4d5e6f7a8b9c
              expiresAt: '2026-09-28T13:30:00.000Z'
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Override'
                required:
                - data
              example:
                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
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`not_shared`: the content is not shared to one or more target locations.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The content does not exist in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid body, the scope matched no screens you can reach (`no_screens`), or the content cannot play (empty playlist, unprocessed media).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - screen.cast
  /v1/casts/{id}/clear:
    post:
      operationId: endCast
      tags:
      - casts
      summary: End a cast
      description: 'End a cast immediately and return its screens to their scheduled content.


        Ends an active cast; its screens return to their scheduled content immediately.'
      x-brix-permission: screen.cast
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Cast id.
        example: cast_9f2c4a1b7d3e5f60
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Override'
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such cast in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`already_inactive`: the cast is already cleared or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - screen.cast
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: 'Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …'
        message:
          description: Human-readable explanation. Safe to show an operator.
          type: string
        requestId:
          description: 'Present on 5xx: quote it to support.'
          type: string
      required:
      - error
      additionalProperties: {}
      description: Error envelope returned by every failing request.
    Override:
      type: object
      properties:
        id:
          type: string
          description: Override (cast_… or emg_…) id.
          examples:
          - cast_9f2c4a1b7d3e5f60
        spaceId:
          type: string
          description: Workspace id.
        kind:
          type: string
          enum:
          - emergency
          - cast
        status:
          type: string
          enum:
          - active
          - cleared
          - expired
        severity:
          type: string
          enum:
          - info
          - warning
          - critical
          description: Always `info` for a cast.
        headline:
          type: string
          description: An emergency's message; for a cast, the content's name (or "Cast").
        body:
          anyOf:
          - type: string
          - type: 'null'
        contentKind:
          anyOf:
          - type: string
            enum:
            - media
            - creative
            - playlist
            - app
            - schedule
          - type: 'null'
        contentId:
          anyOf:
          - type: string
          - type: 'null'
        contentName:
          anyOf:
          - type: string
          - type: 'null'
          description: '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.'
        scopeKind:
          type: string
          enum:
          - all
          - node
          - screens
        scopeNodeId:
          anyOf:
          - type: string
          - type: 'null'
          description: The location, when `scopeKind` is `node`.
        nodeId:
          anyOf:
          - type: string
          - type: 'null'
          description: Location the override is attributed to (null = workspace root).
        screenCount:
          type: integer
          description: Screens targeted, snapshotted when it started.
        triggeredBy:
          type: string
          description: User id, or `system`.
        triggeredAt:
          type: string
          description: ISO-8601 timestamp (UTC).
        expiresAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
          description: Auto-clear time; null = until cleared.
        clearedBy:
          anyOf:
          - type: string
          - type: 'null'
        clearedAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
        triggeredByName:
          type: string
          description: Display name of `triggeredBy`.
        clearedByName:
          anyOf:
          - type: string
          - type: 'null'
        scopeName:
          anyOf:
          - type: string
          - type: 'null'
          description: Location name, `All screens`, or null for a screen list.
        confirmedCount:
          anyOf:
          - type: integer
          - type: 'null'
          description: 'Active emergencies only: screens confirmed showing it now. Null otherwise.'
      required:
      - id
      - spaceId
      - kind
      - status
      - severity
      - headline
      - body
      - contentKind
      - contentId
      - contentName
      - scopeKind
      - scopeNodeId
      - nodeId
      - screenCount
      - triggeredBy
      - triggeredAt
      - expiresAt
      - clearedBy
      - clearedAt
      - triggeredByName
      - clearedByName
      - scopeName
      - confirmedCount
      description: A cast or an emergency override.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.