Brix Status API

openapi: 3.2.0
info:
  title: Brix Status 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: Status
paths:
  /v1/status:
    get:
      operationId: getStatus
      tags:
      - Status
      summary: Get platform status
      description: 'Get the current platform status, including overall state, 30-day latency attainment, open and recent published incidents, and a 90-day history strip. This endpoint requires no authentication. If the underlying status data is more than three hours old, the state is reported as `unknown` rather than `operational`. Pass `format=text` for a plain-text response.


        **Notes.**

        - Answers 200 during an outage too: the state is in the body.

        - With `format=text` the body is `text/plain`.'
      x-brix-schema: verified
      x-brix-notes:
      - 'Answers 200 during an outage too: the state is in the body.'
      - With `format=text` the body is `text/plain`.
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - text
        description: '`text` answers a plain-text summary instead of JSON.'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                        - operational
                        - degraded
                        - outage
                        - unknown
                      computedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                        description: When the status was measured; null when never.
                      stale:
                        type: boolean
                        description: True when the measurement is more than three hours old (the state is then `unknown`).
                      latency:
                        anyOf:
                        - type: object
                          properties:
                            windowDays:
                              type: integer
                            targetMs:
                              type: number
                            targetShare:
                              type: number
                              description: The target share of requests under `targetMs`, 0–1.
                            share:
                              anyOf:
                              - type: number
                              - type: 'null'
                              description: The measured share, 0–1; null when not measured.
                            met:
                              anyOf:
                              - type: boolean
                              - type: 'null'
                          required:
                          - windowDays
                          - targetMs
                          - targetShare
                          - share
                          - met
                        - type: 'null'
                      incidents:
                        type: array
                        items:
                          $ref: '#/components/schemas/StatusIncident'
                        description: Open incidents.
                      recent:
                        type: array
                        items:
                          $ref: '#/components/schemas/StatusIncident'
                        description: Recently resolved incidents.
                      days:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              description: '`YYYY-MM-DD`.'
                            state:
                              type: string
                              enum:
                              - operational
                              - degraded
                              - outage
                          required:
                          - date
                          - state
                        description: One entry per day, for the last 90 days.
                    required:
                    - state
                    - computedAt
                    - stale
                    - latency
                    - incidents
                    - recent
                    - days
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          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: []
  /v1/status/deprecations:
    get:
      operationId: listStatusDeprecations
      tags:
      - Status
      summary: List API deprecations
      description: List every API route scheduled for retirement, when it stops working, and its replacement. This endpoint requires no authentication and is safe to poll from a script. An empty list means no routes are currently scheduled for retirement.
      x-brix-schema: verified
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      noticeDays:
                        type: integer
                        description: The minimum notice a retired route gets.
                      policy:
                        type: string
                      deprecations:
                        type: array
                        items:
                          type: object
                          properties:
                            route:
                              type: string
                              description: '`METHOD /path`.'
                            announced:
                              type: string
                              description: Date (`YYYY-MM-DD`) it was listed.
                            sunset:
                              type: string
                              description: Date (`YYYY-MM-DD`) it stops working.
                            replacement:
                              anyOf:
                              - type: string
                              - type: 'null'
                            why:
                              type: string
                            noticeDays:
                              type: integer
                              description: Days between `announced` and `sunset`.
                          required:
                          - route
                          - announced
                          - sunset
                          - replacement
                          - why
                          - noticeDays
                    required:
                    - noticeDays
                    - policy
                    - deprecations
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          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: []
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.
    StatusIncident:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        status:
          type: string
          enum:
          - investigating
          - identified
          - monitoring
          - resolved
        impact:
          type: string
          enum:
          - degraded
          - outage
          - none
        startedAt:
          type: string
          description: ISO-8601 timestamp (UTC).
        resolvedAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
        updates:
          type: array
          items:
            type: object
            properties:
              at:
                type: string
                description: ISO-8601 timestamp (UTC).
              status:
                type: string
                enum:
                - investigating
                - identified
                - monitoring
                - resolved
              message:
                type: string
            required:
            - at
            - status
            - message
          description: Oldest first.
        screensPlaying:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Whether screens kept playing during the incident; null when not stated.
      required:
      - id
      - title
      - status
      - impact
      - startedAt
      - resolvedAt
      - updates
      - screensPlaying
      description: A published incident.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.