Brix Device Preassignments API

openapi: 3.2.0
info:
  title: Brix Device Preassignments 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: device-preassignments
paths:
  /v1/device-preassignments:
    get:
      operationId: listDevicePreassignments
      tags:
      - device-preassignments
      summary: List pre-assigned devices
      description: 'List devices pre-assigned to locations in your workspace. Each entry shows the end of the device serial number, the location, the screen name, and whether the device is still waiting to be claimed or has already been claimed. Results are limited to the organization nodes you can see.


        **Notes.**

        - Carries `available` beside `data`.'
      x-brix-permission: screen.view
      x-brix-schema: verified
      x-brix-notes:
      - Carries `available` beside `data`.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        serialHint:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The last 4 characters of the serial. The full serial is not stored.
                        nodeId:
                          type: string
                        locationName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        locationId:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The location's own id (its Location ID), when set.
                        name:
                          anyOf:
                          - type: string
                          - type: 'null'
                        status:
                          type: string
                          enum:
                          - waiting
                          - claimed
                        claimedAt:
                          anyOf:
                          - type: string
                            description: ISO-8601 timestamp (UTC).
                          - type: 'null'
                        claimedScreenId:
                          anyOf:
                          - type: string
                          - type: 'null'
                        createdAt:
                          type: string
                          description: ISO-8601 timestamp (UTC).
                      required:
                      - id
                      - serialHint
                      - nodeId
                      - locationName
                      - locationId
                      - name
                      - status
                      - claimedAt
                      - claimedScreenId
                      - createdAt
                  available:
                    type: boolean
                    description: False when the workspace's data region does not support pre-assignment yet (`data` is then empty).
                required:
                - data
                - available
        '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.view
    post:
      operationId: createDevicePreassignment
      tags:
      - device-preassignments
      summary: Pre-assign devices to locations
      description: Pre-assign device serial numbers to locations, identified by Location ID or `nodeId`, so each device pairs automatically into its assigned location the first time it is plugged in. Submit up to 1000 rows in one request; all rows are validated before any are saved. Re-uploading the same rows is safe and does not create duplicates, and `dryRun` validates rows without saving them. A serial number already assigned to another workspace is refused with a conflict error, and the action is recorded in the activity log.
      x-brix-permission: screen.create
      x-brix-schema: verified
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rows:
                  minItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      serial:
                        type: string
                        description: The device serial number.
                      locationId:
                        description: The location's Location ID (case-insensitive). Give this or `nodeId`.
                        type: string
                      nodeId:
                        type: string
                      name:
                        description: 'Screen name; default: the location name and the serial''s last 4 characters.'
                        type: string
                    required:
                    - serial
                dryRun:
                  description: 'True: check and report, change nothing (answers 200).'
                  type: boolean
              required:
              - rows
      responses:
        '200':
          description: 'Success: a dry run (`dryRun: true`): the same report, nothing changed.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      dryRun:
                        type: boolean
                      counts:
                        type: object
                        properties:
                          claimed:
                            type: integer
                          created:
                            type: integer
                          updated:
                            type: integer
                          unchanged:
                            type: integer
                        required:
                        - claimed
                        - created
                        - updated
                        - unchanged
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                            serial:
                              type: string
                              description: The serial's last 4 characters.
                            outcome:
                              type: string
                              enum:
                              - claimed
                              - created
                              - updated
                              - unchanged
                            nodeId:
                              type: string
                            locationName:
                              type: string
                            locationId:
                              anyOf:
                              - type: string
                              - type: 'null'
                            name:
                              type: string
                          required:
                          - index
                          - serial
                          - outcome
                          - nodeId
                          - locationName
                          - locationId
                          - name
                    required:
                    - dryRun
                    - counts
                    - rows
                required:
                - data
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      dryRun:
                        type: boolean
                      counts:
                        type: object
                        properties:
                          claimed:
                            type: integer
                          created:
                            type: integer
                          updated:
                            type: integer
                          unchanged:
                            type: integer
                        required:
                        - claimed
                        - created
                        - updated
                        - unchanged
                      rows:
                        type: array
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                            serial:
                              type: string
                              description: The serial's last 4 characters.
                            outcome:
                              type: string
                              enum:
                              - claimed
                              - created
                              - updated
                              - unchanged
                            nodeId:
                              type: string
                            locationName:
                              type: string
                            locationId:
                              anyOf:
                              - type: string
                              - type: 'null'
                            name:
                              type: string
                          required:
                          - index
                          - serial
                          - outcome
                          - nodeId
                          - locationName
                          - locationId
                          - name
                    required:
                    - dryRun
                    - counts
                    - rows
                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'
        '409':
          description: A serial is held by another workspace, or the data region does not support pre-assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: No rows, too many rows, or a row is invalid; `data.errors` lists each by `index` and `code`.
          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.create
  /v1/device-preassignments/{id}:
    delete:
      operationId: deleteDevicePreassignment
      tags:
      - device-preassignments
      summary: Cancel a device pre-assignment
      description: Cancel a pending device pre-assignment. If the device has already been claimed and turned into a screen, that screen is not affected. The action is recorded in the activity log.
      x-brix-permission: screen.create
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Pre-assignment id.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      deleted:
                        type: boolean
                        const: true
                    required:
                    - id
                    - deleted
                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:
        - screen.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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.