Brix Emergencies API

openapi: 3.2.0
info:
  title: Brix Emergencies 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: emergencies
paths:
  /v1/emergencies:
    get:
      operationId: listEmergencies
      tags:
      - emergencies
      summary: List emergency overrides
      description: List emergency overrides, newest first. Use `?status=active` to filter to overrides currently taking over screens.
      x-brix-permission: emergency-override.view
      x-brix-schema: verified
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - cleared
          - expired
        description: Only overrides 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: 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
        '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:
        - emergency-override.view
    post:
      operationId: triggerEmergency
      tags:
      - emergencies
      summary: Trigger an emergency takeover
      description: '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.'
      x-brix-permission: emergency-override.create
      x-brix-schema: verified
      x-brix-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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                headline:
                  type: string
                  description: The message on every targeted screen. Required, non-blank.
                body:
                  description: Optional second line.
                  type: string
                severity:
                  description: Default `critical`.
                  type: string
                  enum:
                  - info
                  - warning
                  - critical
                contentKind:
                  description: Attach content to show under the banner. Needs `contentId`.
                  type: string
                  enum:
                  - media
                  - creative
                contentId:
                  description: The media or creative id. Needs `contentKind`.
                  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 emergency 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 it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.'
                  anyOf:
                  - anyOf:
                    - type: string
                    - type: number
                  - type: 'null'
              required:
              - headline
            example:
              headline: Evacuate the building now
              body: Use the nearest exit. Do not use the lifts.
              severity: critical
              scopeKind: all
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Override'
                required:
                - data
              example:
                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
        '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: Missing headline, a half content pointer, a bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play (`content_unplayable`).
          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:
        - emergency-override.create
  /v1/emergencies/{id}:
    get:
      operationId: getEmergency
      tags:
      - emergencies
      summary: Get an emergency override
      description: Retrieve one emergency override, including its scope, content, and expiry.
      x-brix-permission: emergency-override.view
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Emergency id.
        example: emg_4d5e6f7a8b9c0d1e
      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 emergency in this workspace (or outside your locations).
          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:
        - emergency-override.view
  /v1/emergencies/{id}/clear:
    post:
      operationId: clearEmergency
      tags:
      - emergencies
      summary: Clear an emergency override
      description: Clear an active emergency override. This releases its screens back to their normal content, and the action is recorded in the activity log.
      x-brix-permission: emergency-override.create
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Emergency id.
        example: emg_4d5e6f7a8b9c0d1e
      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 emergency in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`already_inactive`: 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:
        - emergency-override.create
  /v1/emergencies/from-template/{templateId}:
    post:
      operationId: triggerEmergencyTemplate
      tags:
      - emergencies
      summary: Trigger an emergency from a template
      description: '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.'
      x-brix-permission: emergency-override.create
      x-brix-schema: verified
      parameters:
      - name: templateId
        in: path
        required: true
        schema:
          type: string
        description: Emergency template id.
        example: etpl_7a8b9c0d1e2f3a4b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                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 emergency 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 it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.'
                  anyOf:
                  - anyOf:
                    - type: string
                    - type: number
                  - type: 'null'
              description: Trigger-time overrides. Omitted scope fields fall back to the template's own scope.
      responses:
        '201':
          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: '`not_shared`: the template''s content is not shared to one or more target locations.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such template, or its content is gone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play.
          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:
        - emergency-override.create
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.