Brix Signage Master Templates API

openapi: 3.2.0
info:
  title: Brix Signage Master Templates 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: signage-master-templates
paths:
  /v1/signage-master-templates:
    get:
      operationId: listSignageMasterTemplates
      tags:
      - signage-master-templates
      summary: List master signage templates
      description: 'Return the published catalog of signage templates curated by Brix. This catalog is shared across all workspaces rather than scoped to one, and is the only source of the masterId values required when creating a signage template. Drafts and deleted entries are not included.


        **Notes.**

        - Not paginated: the whole published catalog comes back, sorted by `sortOrder` then name.'
      x-brix-permission: creative.view
      x-brix-schema: verified
      x-brix-notes:
      - 'Not paginated: the whole published catalog comes back, sorted by `sortOrder` then name.'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignageMasterTemplate'
                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'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - creative.view
components:
  schemas:
    SignageMasterTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          anyOf:
          - type: string
          - type: 'null'
        industry:
          anyOf:
          - type: string
          - type: 'null'
        archetype:
          anyOf:
          - type: string
          - type: 'null'
        sortOrder:
          type: integer
        format:
          type: string
          enum:
          - engine
          - creative
          description: '`engine`: `config` is the template. `creative`: `creative` is a finished design to create a creative from.'
        config:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
          description: 'The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write.'
        creative:
          anyOf:
          - {}
          - type: 'null'
          description: '`creative` format: the design (the body `POST /v1/creatives` takes). Null otherwise.'
        updatedAt:
          type: string
          description: ISO-8601 timestamp (UTC).
      required:
      - id
      - name
      - description
      - industry
      - archetype
      - sortOrder
      - format
      - config
      - creative
      - updatedAt
      description: A published template from the Brix catalog.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.