Brix Recycle Bin API

openapi: 3.2.0
info:
  title: Brix Recycle Bin 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: recycle bin
paths:
  /v1/recycle-bin:
    get:
      operationId: getRecycleBin
      tags:
      - recycle bin
      summary: List the recycle bin
      description: 'List every deleted item across your workspace, including media, playlists, schedules, layouts, creatives, apps, and data sources. Each entry includes the deletion time and size, so items can be restored or permanently erased within the 30-day recovery window. Deleted screens are not included; screens have their own recovery endpoints.


        **Notes.**

        - Items deleted in the last 30 days, newest first. Each kind is listed only if the caller holds its view permission (`playlist.view`, `media.view`, …) where the item lives; a `screen.view`-only key sees only screens.'
      x-brix-permission: screen.view
      x-brix-schema: verified
      x-brix-notes:
      - Items deleted in the last 30 days, newest first. Each kind is listed only if the caller holds its view permission (`playlist.view`, `media.view`, …) where the item lives; a `screen.view`-only key sees only screens.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                          - screen
                          - playlist
                          - schedule
                          - layout
                          - creative
                          - app
                          - media
                          - signage
                          - data-source
                          - banner
                          - media-folder
                        id:
                          type: string
                        name:
                          type: string
                        deletedAt:
                          type: string
                          description: ISO-8601 timestamp (UTC).
                        nodeId:
                          anyOf:
                          - type: string
                          - type: 'null'
                        sizeBytes:
                          type: integer
                          description: Stored bytes (media); 0 for other kinds.
                        usageBeforeDelete:
                          type: integer
                          description: How many places used it when it was deleted.
                        thumbnailUrl:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: 'For media: its stored address (may be an internal `r2://` reference, not a public URL).'
                      required:
                      - kind
                      - id
                      - name
                      - deletedAt
                      - nodeId
                      - sizeBytes
                      - usageBeforeDelete
                      - thumbnailUrl
                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.view
  /v1/recycle-bin/{kind}/{id}/purge:
    post:
      operationId: createRecycleBinPurge
      tags:
      - recycle bin
      summary: Permanently delete from the recycle bin
      description: 'Permanently erase one deleted item before the 30-day recovery window would otherwise remove it. For media, this also deletes the stored file. This action cannot be undone.


        **Notes.**

        - Irreversible. Besides the `screen.view` gate, the caller needs the kind''s delete permission (`media.delete`, `integration.delete` for a banner, …).'
      x-brix-permission: screen.view
      x-brix-schema: verified
      x-brix-notes:
      - Irreversible. Besides the `screen.view` gate, the caller needs the kind's delete permission (`media.delete`, `integration.delete` for a banner, …).
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
        description: '`screen`, `playlist`, `schedule`, `layout`, `creative`, `app`, `media`, `signage`, `data-source`, `banner` or `media-folder`.'
        example: playlist
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The deleted item's id.
        example: pl_2b3c4d5e6f7a8b9c
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      kind:
                        type: string
                        enum:
                        - screen
                        - playlist
                        - schedule
                        - layout
                        - creative
                        - app
                        - media
                        - signage
                        - data-source
                        - banner
                        - media-folder
                      purged:
                        type: boolean
                        const: true
                    required:
                    - id
                    - kind
                    - purged
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: You lack the kind's delete permission (`playlist.delete`, …) where the item lives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such item in the recycle bin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unknown `kind`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: A stored file could not be removed; nothing was deleted.
          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
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.