Brix Media Sync API

openapi: 3.2.0
info:
  title: Brix Media Sync 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: media-sync
paths:
  /v1/media-sync:
    get:
      operationId: listMediaSync
      tags:
      - media-sync
      summary: List synced folders
      description: Return the workspace's synced folders, including the remote path, the destination folder in Brix, the connected account, sync status, the last error, the last check time, and the number of files synced. Only folders connected at locations where the caller holds the integration view permission are returned.
      x-brix-permission: integration.view
      x-brix-schema: verified
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        provider:
                          type: string
                          description: '`onedrive` or `sharepoint`.'
                        remotePath:
                          type: string
                        folderId:
                          type: string
                          description: The library folder the files land in.
                        folderName:
                          anyOf:
                          - type: string
                          - type: 'null'
                        accountLabel:
                          anyOf:
                          - type: string
                          - type: 'null'
                        accountConnected:
                          type: boolean
                          description: 'False when the connected account was removed: syncing stops until it is connected again.'
                        status:
                          type: string
                          enum:
                          - ok
                          - error
                          - paused
                        lastError:
                          anyOf:
                          - type: string
                          - type: 'null'
                        lastSyncAt:
                          anyOf:
                          - type: string
                            description: ISO-8601 timestamp (UTC).
                          - type: 'null'
                        itemsSynced:
                          type: integer
                        createdAt:
                          type: string
                          description: ISO-8601 timestamp (UTC).
                        updatedAt:
                          type: string
                          description: ISO-8601 timestamp (UTC).
                      required:
                      - id
                      - provider
                      - remotePath
                      - folderId
                      - folderName
                      - accountLabel
                      - accountConnected
                      - status
                      - lastError
                      - lastSyncAt
                      - itemsSynced
                      - createdAt
                      - updatedAt
                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:
        - integration.view
  /v1/media-sync/{id}:
    delete:
      operationId: deleteMediaSync
      tags:
      - media-sync
      summary: Stop syncing a folder
      description: 'Stop following a remote folder. The sync source is removed, but files already imported are not affected. This action is recorded in the activity log.


        **Notes.**

        - The files already synced stay in the library.'
      x-brix-permission: integration.delete
      x-brix-schema: verified
      x-brix-notes:
      - The files already synced stay in the library.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synced folder id.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        const: true
                    required:
                    - ok
                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:
        - integration.delete
  /v1/media-sync/{id}/sync:
    post:
      operationId: syncMediaSync
      tags:
      - media-sync
      summary: Sync a folder now
      description: 'Trigger an immediate sync of one connected folder, bounded to a fixed number of files for the run, and return a summary of what happened. This action is recorded in the activity log.


        **Notes.**

        - A failed run still answers 200: read `error`.'
      x-brix-permission: integration.create
      x-brix-schema: verified
      x-brix-notes:
      - 'A failed run still answers 200: read `error`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synced folder id.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      imported:
                        type: integer
                      updated:
                        type: integer
                      removed:
                        type: integer
                      skipped:
                        type: integer
                      failed:
                        type: integer
                      caughtUp:
                        type: boolean
                        description: False when more changes remain for the next run.
                      error:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: Why the run stopped, in words; null when it did not.
                    required:
                    - imported
                    - updated
                    - removed
                    - skipped
                    - failed
                    - caughtUp
                    - error
                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 synced folder with this id.
          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:
        - integration.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.