Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Brix Recall 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: recall
paths:
/v1/recall:
get:
operationId: getRecall
tags:
- recall
summary: List recalled content
description: 'Return everything currently held off screens, including its kind, name, when it was recalled, and who recalled it. Since a recall is reversible, this list is the record of what is being withheld and why, so nothing stays off screens indefinitely without anyone knowing. An item is listed only where the caller can view that kind of content at its location. Who recalled it is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example `user` or `staff`.
**Notes.**
- Newest first, not paginated. An item is listed only where the caller holds that kind''s view permission (`media.view`, `playlist.view`, …) at its location; a `screen.view`-only key gets an empty list.'
x-brix-permission: screen.view
x-brix-schema: verified
x-brix-notes:
- Newest first, not paginated. An item is listed only where the caller holds that kind's view permission (`media.view`, `playlist.view`, …) at its location; a `screen.view`-only key gets an empty list.
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
id:
type: string
name:
anyOf:
- type: string
- type: 'null'
recalledAt:
type: string
description: ISO-8601 timestamp (UTC).
recalledBy:
anyOf:
- type: string
- type: 'null'
description: 'An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. Without `user.view` at the item''s location, only the kind (`user`, `staff`, …).'
required:
- kind
- id
- name
- recalledAt
- recalledBy
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/recall/creative/{id}:
post:
operationId: postRecallCreative
tags:
- recall
summary: Recall a creative from all screens
description: 'Immediately remove a creative from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.
**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
x-brix-permission: creative.edit
x-brix-schema: verified
x-brix-notes:
- 'A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The creative's id.
example: crv_5e6f7a8b9c0d1e2f
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook.
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: string
description: ISO-8601 timestamp (UTC).
recalledBy:
type: string
description: 'Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`.'
required:
- id
- kind
- recalledAt
- recalledBy
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `creative.edit` where the creative lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such creative in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`already_recalled`: it is already recalled.'
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:
- creative.edit
/v1/recall/creative/{id}/restore:
post:
operationId: restoreRecallCreative
tags:
- recall
summary: Restore a recalled creative
description: Put a recalled creative back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.
x-brix-permission: creative.edit
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The creative's id.
example: crv_5e6f7a8b9c0d1e2f
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: 'null'
required:
- id
- kind
- recalledAt
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `creative.edit` where the creative lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such creative in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`not_recalled`: it is not recalled.'
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:
- creative.edit
/v1/recall/media/{id}:
post:
operationId: postRecallMedia
tags:
- recall
summary: Recall a media file from all screens
description: 'Immediately remove a media file from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.
**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
x-brix-permission: media.edit
x-brix-schema: verified
x-brix-notes:
- 'A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The media's id.
example: med_4d5e6f7a8b9c0d1e
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook.
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: string
description: ISO-8601 timestamp (UTC).
recalledBy:
type: string
description: 'Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`.'
required:
- id
- kind
- recalledAt
- recalledBy
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 media lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such media in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`already_recalled`: it is already recalled.'
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/recall/media/{id}/restore:
post:
operationId: restoreRecallMedia
tags:
- recall
summary: Restore a recalled media file
description: Put a recalled media file back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.
x-brix-permission: media.edit
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The media's id.
example: med_4d5e6f7a8b9c0d1e
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: 'null'
required:
- id
- kind
- recalledAt
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 media lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such media in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`not_recalled`: it is not recalled.'
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/recall/playlist/{id}:
post:
operationId: postRecallPlaylist
tags:
- recall
summary: Recall a playlist from all screens
description: 'Immediately remove a playlist from every screen it appears on, without deleting it or changing any other playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.
**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
x-brix-permission: playlist.edit
x-brix-schema: verified
x-brix-notes:
- 'A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The playlist's id.
example: pl_2b3c4d5e6f7a8b9c
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook.
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: string
description: ISO-8601 timestamp (UTC).
recalledBy:
type: string
description: 'Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`.'
required:
- id
- kind
- recalledAt
- recalledBy
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `playlist.edit` where the playlist lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such playlist in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`already_recalled`: it is already recalled.'
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:
- playlist.edit
/v1/recall/playlist/{id}/restore:
post:
operationId: restoreRecallPlaylist
tags:
- recall
summary: Restore a recalled playlist
description: Put a recalled playlist back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.
x-brix-permission: playlist.edit
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The playlist'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:
- media
- creative
- playlist
- schedule
recalledAt:
type: 'null'
required:
- id
- kind
- recalledAt
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `playlist.edit` where the playlist lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such playlist in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`not_recalled`: it is not recalled.'
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:
- playlist.edit
/v1/recall/schedule/{id}:
post:
operationId: postRecallSchedule
tags:
- recall
summary: Recall a schedule from all screens
description: 'Immediately remove a schedule from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.
**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
x-brix-permission: schedule.edit
x-brix-schema: verified
x-brix-notes:
- 'A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The schedule's id.
example: sch_6f7a8b9c0d1e2f3a
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook.
type: string
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: string
description: ISO-8601 timestamp (UTC).
recalledBy:
type: string
description: 'Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`.'
required:
- id
- kind
- recalledAt
- recalledBy
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `schedule.edit` where the schedule lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such schedule in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`already_recalled`: it is already recalled.'
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:
- schedule.edit
/v1/recall/schedule/{id}/restore:
post:
operationId: restoreRecallSchedule
tags:
- recall
summary: Restore a recalled schedule
description: Put a recalled schedule back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.
x-brix-permission: schedule.edit
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The schedule's id.
example: sch_6f7a8b9c0d1e2f3a
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
kind:
type: string
enum:
- media
- creative
- playlist
- schedule
recalledAt:
type: 'null'
required:
- id
- kind
- recalledAt
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: You do not hold `schedule.edit` where the schedule lives.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such schedule in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`not_recalled`: it is not recalled.'
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:
- schedule.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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.