Brix Web Recorder API

openapi: 3.2.0
info:
  title: Brix Web Recorder 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: web-recorder
paths:
  /v1/web-recorder/{sid}:
    get:
      operationId: getWebRecorder
      tags:
      - web-recorder
      summary: Get a recording session
      description: Return the steps recorded so far in an in-progress sign-in recording session.
      x-brix-permission: media.edit
      x-brix-schema: verified
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
        description: Recording session id, from `start`.
        example: rec_3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        description: The page the recording is on now.
                      steps:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecordedStep'
                      startedAt:
                        type: integer
                        description: Milliseconds since the Unix epoch (not an ISO timestamp).
                      spaceId:
                        type: string
                    required:
                    - url
                    - steps
                    - startedAt
                    - spaceId
                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 active session with this id in this workspace (it expired, was finished, or never started).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Recording is not available in this environment.
          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.edit
  /v1/web-recorder/{sid}/abort:
    post:
      operationId: abortWebRecorder
      tags:
      - web-recorder
      summary: Cancel a recording
      description: 'Discard an in-progress sign-in recording session without changing the associated media asset.


        **Notes.**

        - Always answers `{ ok: true }`, for an unknown session too.'
      x-brix-permission: media.edit
      x-brix-schema: verified
      x-brix-notes:
      - 'Always answers `{ ok: true }`, for an unknown session too.'
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
        description: Recording session id, from `start`.
        example: rec_3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
      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:
        - media.edit
  /v1/web-recorder/{sid}/action:
    post:
      operationId: createWebRecorderAction
      tags:
      - web-recorder
      summary: Record a sign-in step
      description: Append one recorded interaction, such as a click, typed text, or a wait, to an open sign-in recording session.
      x-brix-permission: media.edit
      x-brix-schema: verified
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
        description: Recording session id, from `start`.
        example: rec_3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  enum:
                  - click
                  - type
                  - scroll
                  - navigate
                  - accept-cookies
                  - wait
                  - pick
                selector:
                  type: string
                label:
                  type: string
                text:
                  description: 'For `type`: the typed text (not stored when `isSecret`).'
                  type: string
                isSecret:
                  description: 'For `type`: store a reference instead of the text.'
                  type: boolean
                url:
                  type: string
                dy:
                  type: number
                ms:
                  type: number
                mode:
                  type: string
                x:
                  type: number
                y:
                  type: number
              required:
              - kind
              additionalProperties: {}
              description: One browser action.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        description: The page the recording is on now.
                      steps:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecordedStep'
                      startedAt:
                        type: integer
                        description: Milliseconds since the Unix epoch (not an ISO timestamp).
                      spaceId:
                        type: string
                    required:
                    - url
                    - steps
                    - startedAt
                    - spaceId
                required:
                - data
        '400':
          description: The body is not JSON.
          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'
        '404':
          description: No active session with this id in this workspace (it expired, was finished, or never started).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Recording is not available in this environment.
          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.edit
  /v1/web-recorder/{sid}/finalize:
    post:
      operationId: createWebRecorderFinalize
      tags:
      - web-recorder
      summary: Save a recorded sign-in
      description: 'Save a completed recording to a web asset, using mediaId and optional secrets. The recorded steps are stored on the asset''s web configuration, secrets are encrypted and referenced by name, and the session ends.


        **Notes.**

        - The asset''s sign-in is replayed later to refresh its cookies; call `links/:mediaId/verify` to test it now.'
      x-brix-permission: media.edit
      x-brix-schema: verified
      x-brix-notes:
      - The asset's sign-in is replayed later to refresh its cookies; call `links/:mediaId/verify` to test it now.
      parameters:
      - name: sid
        in: path
        required: true
        schema:
          type: string
        description: Recording session id, from `start`.
        example: rec_3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mediaId:
                  type: string
                  description: The web page asset to save the steps to.
                secrets:
                  description: '`valueRef` → secret value. Encrypted; never returned. Null or empty removes one.'
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    anyOf:
                    - type: string
                    - type: 'null'
                expect:
                  description: The asset's `url` and `webConfig` as you last read them. The save is refused (409) if the address or sign-in steps changed since, so secrets are never stored for a link you did not see.
                  type: object
                  properties:
                    url:
                      type: string
                    webConfig: {}
                  required:
                  - url
                  - webConfig
                removeSteps:
                  description: Indices into the session's steps to leave out of the saved recording.
                  type: array
                  items:
                    type: integer
                    minimum: 0
              required:
              - mediaId
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        const: true
                      stepCount:
                        type: integer
                      steps:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecordedStep'
                        description: The steps saved on the asset (the session's, minus `removeSteps`).
                      secretRefs:
                        type: array
                        items:
                          type: object
                          properties:
                            ref:
                              type: string
                            label:
                              type: string
                          required:
                          - ref
                          - label
                        description: Every secret step, so you can send values you have not sent yet.
                    required:
                    - ok
                    - stepCount
                    - steps
                    - secretRefs
                required:
                - data
        '400':
          description: '`mediaId` is missing.'
          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: You do not hold `media.edit` where the asset lives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The session expired or never started, or no such asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The asset's address or sign-in steps changed (or are not what `expect` says). Nothing was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Recording is not available in this environment.
          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.edit
  /v1/web-recorder/links/{mediaId}/verify:
    post:
      operationId: verifyWebRecorderLink
      tags:
      - web-recorder
      summary: Test a recorded sign-in
      description: 'Run the finalized sign-in recording for a web asset and report whether the resulting session looks successfully logged in. This lets a caller confirm the recording works right after capturing it, rather than waiting until the content plays on a screen.


        **Notes.**

        - Runs the sign-in in a headless browser now (this can take 30 seconds or more). Answers 200 with `ok: false` when it fails.'
      x-brix-permission: media.edit
      x-brix-schema: verified
      x-brix-notes:
      - 'Runs the sign-in in a headless browser now (this can take 30 seconds or more). Answers 200 with `ok: false` when it fails.'
      parameters:
      - name: mediaId
        in: path
        required: true
        schema:
          type: string
        description: Web page asset id.
        example: med_4d5e6f7a8b9c0d1e
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                    - type: object
                      properties:
                        ok:
                          type: boolean
                          const: false
                        failedStep:
                          type: integer
                          description: The step that failed (0-based).
                        reason:
                          type: string
                        failureScreenshotB64:
                          description: A base64 JPEG of the page where it stopped, when one could be taken.
                          type: string
                      required:
                      - ok
                      - failedStep
                      - reason
                    - type: object
                      properties:
                        ok:
                          type: boolean
                          const: true
                        cookieCount:
                          type: integer
                          description: Cookies captured and stored (encrypted) for rendering.
                      required:
                      - ok
                      - cookieCount
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: You do not hold `media.edit` where the asset lives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The headless browser is not available.
          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.edit
  /v1/web-recorder/start:
    post:
      operationId: startWebRecorder
      tags:
      - web-recorder
      summary: Start recording a sign-in
      description: 'Begin a sign-in recording session for a web asset, given a url. Returns a session id, the url, and the steps recorded so far, which starts empty. Steps are then submitted using the Brix Recorder browser extension.


        **Notes.**

        - The recorder browser extension then sends each step with `action`. Invalid input answers 400, not 422.'
      x-brix-permission: media.edit
      x-brix-schema: verified
      x-brix-notes:
      - The recorder browser extension then sends each step with `action`. Invalid input answers 400, not 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The sign-in page (http or https, a public host).
              required:
              - url
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        description: The page the recording is on now.
                      steps:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecordedStep'
                      startedAt:
                        type: integer
                        description: Milliseconds since the Unix epoch (not an ISO timestamp).
                      spaceId:
                        type: string
                      sid:
                        type: string
                      ok:
                        type: boolean
                        const: true
                    required:
                    - url
                    - steps
                    - startedAt
                    - spaceId
                    - sid
                    - ok
                required:
                - data
        '400':
          description: '`url` is not http(s), or not a public address.'
          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'
        '503':
          description: Recording is not available in this environment.
          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.edit
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.
    RecordedStep:
      type: object
      properties:
        kind:
          type: string
          description: '`navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step.'
        url:
          type: string
        selector:
          type: string
        label:
          type: string
        value:
          description: Typed text that is not secret.
          type: string
        valueRef:
          description: 'For secret text: a reference; the value is never recorded. Send it in `finalize`''s `secrets`.'
          type: string
        pixels:
          type: number
        ms:
          type: number
      required:
      - kind
      additionalProperties: {}
      description: One recorded step of a website sign-in.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.