Brix Import API

openapi: 3.2.0
info:
  title: Brix Import 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: Import
paths:
  /v1/import/bundle:
    post:
      operationId: createImportBundle
      tags:
      - Import
      summary: Import a migration bundle
      description: 'Performs a bulk import from a multipart upload containing a manifest JSON file and a zip of media files. In one operation, this creates the location tree, media library, playlists, and screens (initially unpaired) described by the manifest. Physical screens are paired into these pre-created entries later. Requires the import-create permission on the API key.


        **Notes.**

        - Re-importing the same manifest is safe: items it already created are counted as `…Existing`, not created again.

        - All or nothing: a validation failure writes nothing.'
      x-brix-permission: import.create
      x-brix-schema: verified
      x-brix-notes:
      - 'Re-importing the same manifest is safe: items it already created are counted as `…Existing`, not created again.'
      - 'All or nothing: a validation failure writes nothing.'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                manifest:
                  type: string
                  description: 'The manifest, as a JSON string: `orgTree`, `media`, `apps`, `playlists`, `layouts`, `schedules`, `screens`, … Each item has your own `id`, used to link items and to recognise them on a re-import.'
                bundle:
                  description: A zip with the media files the manifest names by `bundlePath`.
                  type: string
                  format: binary
                  contentEncoding: binary
              required:
              - manifest
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      orgNodesCreated:
                        type: integer
                      foldersCreated:
                        type: integer
                      mediaCreated:
                        type: integer
                      appsCreated:
                        type: integer
                      billingGroupsCreated:
                        type: integer
                      playlistsCreated:
                        type: integer
                      layoutsCreated:
                        type: integer
                      zonesFilledOnReuse:
                        type: integer
                      schedulesCreated:
                        type: integer
                      foldersExisting:
                        type: integer
                      mediaExisting:
                        type: integer
                      appsExisting:
                        type: integer
                      billingGroupsExisting:
                        type: integer
                      playlistsExisting:
                        type: integer
                      layoutsExisting:
                        type: integer
                      schedulesExisting:
                        type: integer
                      screens:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            pairingCode:
                              type: string
                              description: 'A six-digit code shown with the new screen. Not a credential: nothing redeems it; pair the device as usual.'
                          required:
                          - id
                          - name
                          - pairingCode
                        description: Screens created by this import.
                      screensExisting:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            pairingCode:
                              anyOf:
                              - type: string
                              - type: 'null'
                          required:
                          - id
                          - name
                          - pairingCode
                        description: Screens a previous import already created (matched by your id).
                      pendingDevicesClaimed:
                        type: array
                        items:
                          type: object
                          properties:
                            pairingId:
                              type: string
                            screenId:
                              type: string
                            name:
                              type: string
                          required:
                          - pairingId
                          - screenId
                          - name
                        description: Waiting devices that were matched to an imported screen and paired.
                    required:
                    - orgNodesCreated
                    - foldersCreated
                    - mediaCreated
                    - appsCreated
                    - billingGroupsCreated
                    - playlistsCreated
                    - layoutsCreated
                    - zonesFilledOnReuse
                    - schedulesCreated
                    - foldersExisting
                    - mediaExisting
                    - appsExisting
                    - billingGroupsExisting
                    - playlistsExisting
                    - layoutsExisting
                    - schedulesExisting
                    - screens
                    - screensExisting
                    - pendingDevicesClaimed
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: You do not hold `import.create` for the whole workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The body, the zip, a file or the number of new media items is over its limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A missing or invalid manifest, an invalid zip, or a reference to an item, upload or zip entry that does not exist (`upload_not_found`, `missing_bundle_entry`, `unknown_media_ref`, …). Nothing is written.
          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:
        - import.create
  /v1/import/upload-urls:
    post:
      operationId: createImportUploadUrl
      tags:
      - Import
      summary: Get upload slots for an import
      description: 'Creates up to 500 upload slots for a large-scale import. Each slot returns a URL you upload file bytes to directly and in parallel, and your import manifest then references the file by its `uploadId`. Use this instead of a single bundle upload when importing 10,000 or more files, since a single request cannot hold that much data.


        **Notes.**

        - A bad `count` answers 400, not 422.'
      x-brix-permission: import.create
      x-brix-schema: verified
      x-brix-notes:
      - A bad `count` answers 400, not 422.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                count:
                  description: Slots to create, 1–500 (default 100).
                  type: number
                contentType:
                  description: Media type recorded for each slot (default `application/octet-stream`).
                  type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uploads:
                        type: array
                        items:
                          type: object
                          properties:
                            uploadId:
                              type: string
                              description: Reference it as `uploadId` in the bundle manifest.
                            putUrl:
                              type: string
                              description: PUT the file's bytes here, with your API key.
                            expiresInSec:
                              type: integer
                          required:
                          - uploadId
                          - putUrl
                          - expiresInSec
                    required:
                    - uploads
                required:
                - data
        '400':
          description: '`count` is not a number.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
        - import.create
  /v1/import/zm-originals:
    post:
      operationId: createImportZmOriginal
      tags:
      - Import
      summary: Import originals from another console
      description: 'Fetches a Zeetaminds account''s original media files, which cannot normally be downloaded directly by a browser, into this workspace''s pending upload slots. Processes files in batches and reports a per-file result. Widget and layout items have no underlying file and are reported as skipped. Only affects the workspace that owns the calling API key.


        **Notes.**

        - Files go to upload slots (like `upload-urls`); import them with a bundle manifest that names each `uploadId`.'
      x-brix-permission: media.create
      x-brix-schema: verified
      x-brix-notes:
      - Files go to upload slots (like `upload-urls`); import them with a bundle manifest that names each `uploadId`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                consoleCookie:
                  type: string
                  description: A signed-in session cookie for the other console. Used for this call only; not stored.
                orgId:
                  type: integer
                  description: The organisation id in the other console.
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      mediaId:
                        anyOf:
                        - type: string
                        - type: number
                      ext:
                        anyOf:
                        - type: string
                        - type: 'null'
                      name:
                        anyOf:
                        - type: string
                        - type: 'null'
                    required:
                    - mediaId
                  description: The media to pull (a limited number per call; loop for more).
              required:
              - consoleCookie
              - orgId
              - items
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            mediaId:
                              type: string
                            uploadId:
                              description: 'Set when the file was fetched: reference it in a bundle manifest.'
                              type: string
                            bytes:
                              type: integer
                            skipped:
                              description: Why the item has no file to fetch.
                              type: string
                            error:
                              type: string
                          required:
                          - mediaId
                        description: 'One result per item, in order: `uploadId` + `bytes`, or `skipped`, or `error`.'
                    required:
                    - results
                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'
        '422':
          description: '`consoleCookie` or `orgId` missing, `items` empty or too many.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: '`zm_session_failed`: the other console refused the session.'
          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:
        - media.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.