Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Brix AI 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: AI
paths:
/v1/ai/events:
get:
operationId: listAiEvents
tags:
- AI
summary: List AI activity events
description: 'Return the workspace''s record of every AI-powered call it made, including the feature, model, outcome, actor, duration, and number of redactions. Calls that were refused, for example because the feature is disabled or a usage limit was reached, also appear as entries, since a blocked request is only evidenced by a record of the refusal. The prompt and output text are never stored. Only events at locations where the caller holds the audit log view permission are returned, as in the audit log. The actor is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example `user` or `staff`. Results are paginated and can be filtered by feature, outcome, and a starting point in time; a page can hold fewer entries than the limit.
**Notes.**
- `nextCursor` sits beside `data`, outside the usual envelope.
- Only events where the caller''s `audit-log.view` reaches the event''s location are returned, so a page can hold fewer than `limit` events while `nextCursor` is still set.'
x-brix-permission: audit-log.view
x-brix-schema: verified
x-brix-notes:
- '`nextCursor` sits beside `data`, outside the usual envelope.'
- Only events where the caller's `audit-log.view` reaches the event's location are returned, so a page can hold fewer than `limit` events while `nextCursor` is still set.
parameters:
- name: feature
in: query
required: false
schema:
type: string
description: Only this feature (an unknown value is ignored).
- name: outcome
in: query
required: false
schema:
type: string
enum:
- ok
- blocked
- error
- quota
- disabled
description: Only this outcome (an unknown value is ignored).
- name: since
in: query
required: false
schema:
type: string
description: Only events at or after this ISO 8601 time.
- name: cursor
in: query
required: false
schema:
type: string
description: '`nextCursor` from the previous page.'
- name: limit
in: query
required: false
schema:
type: integer
description: Page size.
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AiEvent'
nextCursor:
anyOf:
- type: string
- type: 'null'
description: Pass as `cursor` for the next (older) page; null on the last page.
required:
- data
- nextCursor
'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:
- audit-log.view
/v1/ai/events.csv:
get:
operationId: getAiEventsCsv
tags:
- AI
summary: Export AI activity events as CSV
description: 'Return the same AI activity data as a CSV file, suitable for sharing or importing elsewhere. It applies the same filters, the same location scope and the same actor rule as the JSON list, so the export always matches what the list view shows.
**Notes.**
- One page, as a file (`content-disposition: attachment`). Columns: when, feature, model, provider, outcome, actor, duration_ms, input, redactions, detail. There is no next-page cursor: page with `since` or the JSON list.'
x-brix-permission: audit-log.view
x-brix-schema: verified
x-brix-notes:
- 'One page, as a file (`content-disposition: attachment`). Columns: when, feature, model, provider, outcome, actor, duration_ms, input, redactions, detail. There is no next-page cursor: page with `since` or the JSON list.'
parameters:
- name: feature
in: query
required: false
schema:
type: string
description: Only this feature (an unknown value is ignored).
- name: outcome
in: query
required: false
schema:
type: string
enum:
- ok
- blocked
- error
- quota
- disabled
description: Only this outcome (an unknown value is ignored).
- name: since
in: query
required: false
schema:
type: string
description: Only events at or after this ISO 8601 time.
- name: cursor
in: query
required: false
schema:
type: string
description: '`nextCursor` from the previous page.'
- name: limit
in: query
required: false
schema:
type: integer
description: 'Rows (default and maximum: the largest page).'
responses:
'200':
description: Success. The body is the file itself.
content:
text/csv:
schema:
type: string
format: binary
'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:
- audit-log.view
/v1/ai/models:
get:
operationId: listAiModels
tags:
- AI
summary: List AI models in use
description: Return which AI model powers each AI feature, when it was adopted, what it replaced, and the safe-use guidance shown to users at the point of use. This reflects the exact configuration currently enforced, so it cannot drift out of step with actual behavior.
x-brix-permission: settings.view
x-brix-schema: verified
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
fingerprint:
type: string
description: Changes whenever any model below changes.
providers:
type: array
items:
type: string
firstParty:
type: string
description: A plain statement of who runs the models.
safeUse:
type: array
items:
type: string
description: The safe-use guidance shown with AI features.
features:
type: array
items:
type: object
properties:
feature:
type: string
label:
type: string
sends:
type: string
model:
type: string
provider:
type: string
since:
type: string
description: When this model started running the feature (a date).
what:
type: string
previous:
type: array
items:
type: object
properties:
model:
type: string
until:
type: string
why:
type: string
required:
- model
- until
- why
fallback:
type: object
properties:
model:
type: string
provider:
type: string
when:
type: string
required:
- model
- provider
- when
configuredBy:
type: string
required:
- feature
- label
- sends
- model
- provider
- since
- what
- previous
safety:
type: array
items:
type: object
properties:
key:
type: string
model:
type: string
provider:
type: string
since:
type: string
description: When this model started running the feature (a date).
what:
type: string
runsWhen:
type: string
required:
- key
- model
- provider
- since
- what
- runsWhen
description: Models that screen text before it is sent.
rollback:
type: string
required:
- fingerprint
- providers
- firstParty
- safeUse
- features
- safety
- rollback
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:
- settings.view
/v1/ai/summary:
get:
operationId: getAiSummary
tags:
- AI
summary: Summarize AI activity
description: 'Return counts of AI calls grouped by feature, model, and outcome over a time window that defaults to 30 days. Totals separate calls that ran successfully, calls that failed, and calls that were refused due to policy or usage limits, so a refusal is never confused with a failure. Only calls at locations where the caller holds the audit log view permission are counted.
**Notes.**
- `blocked` calls count in no total but appear in `byFeature`.'
x-brix-permission: audit-log.view
x-brix-schema: verified
x-brix-notes:
- '`blocked` calls count in no total but appear in `byFeature`.'
parameters:
- name: days
in: query
required: false
schema:
type: integer
description: Window in days, 1–365 (default 30).
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
windowDays:
type: integer
since:
type: string
description: ISO-8601 timestamp (UTC).
totals:
type: object
properties:
ran:
type: integer
failed:
type: integer
refusedByPolicy:
type: integer
refusedByLimit:
type: integer
redactions:
type: integer
required:
- ran
- failed
- refusedByPolicy
- refusedByLimit
- redactions
byFeature:
type: array
items:
type: object
properties:
feature:
type: string
featureLabel:
type: string
model:
type: string
outcome:
type: string
calls:
type: integer
redactions:
type: integer
required:
- feature
- featureLabel
- model
- outcome
- calls
- redactions
description: One row per feature, model and outcome.
required:
- windowDays
- since
- totals
- byFeature
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:
- audit-log.view
components:
schemas:
AiEvent:
type: object
properties:
id:
type: string
spaceId:
type: string
nodeId:
anyOf:
- type: string
- type: 'null'
description: The location of the content the call was about; null for the workspace root.
actor:
type: string
description: 'Who made the call. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. Without `user.view` at the event''s location, only the kind (`user`, `staff`, …).'
feature:
type: string
description: '`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`, …'
featureLabel:
type: string
description: The feature's display name (the raw key for an unknown feature).
sends:
anyOf:
- type: string
- type: 'null'
description: What the feature sends to the model; null for an unknown feature.
model:
type: string
provider:
type: string
outcome:
type: string
enum:
- ok
- blocked
- error
- quota
- disabled
durationMs:
anyOf:
- type: number
- type: 'null'
inputKind:
anyOf:
- type: string
- type: 'null'
description: '`image`, `text` or `audio`: what was sent, never the content.'
redactions:
type: integer
description: Personal-data patterns masked before the call.
detail:
anyOf:
- type: string
- type: 'null'
createdAt:
type: string
description: ISO-8601 timestamp (UTC).
required:
- id
- spaceId
- nodeId
- actor
- feature
- featureLabel
- sends
- model
- provider
- outcome
- durationMs
- inputKind
- redactions
- detail
- createdAt
description: One AI call (or refusal) the workspace made.
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.