AI API
AI endpoints in the Brix REST API for digital signage: 4 operations (GET). Each lists its path, auth, required permission and a curl example.
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
GET/v1/ai/events
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
feature | query | string | no | Only this feature (an unknown value is ignored). |
outcome | query | "ok" | "blocked" | "error" | "quota" | "disabled" | no | Only this outcome (an unknown value is ignored). |
since | query | string | no | Only events at or after this ISO 8601 time. |
cursor | query | string | no | `nextCursor` from the previous page. |
limit | query | integer | no | Page size. |
curl "https://api.brixsignage.com/v1/ai/events" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | array of AiEvent | |
data[].id | string | |
data[].spaceId | string | |
data[].nodeId | string | null | The location of the content the call was about; null for the workspace root. |
data[].actor | string | 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`, …). |
data[].feature | string | `tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`, … |
data[].featureLabel | string | The feature's display name (the raw key for an unknown feature). |
data[].sends | string | null | What the feature sends to the model; null for an unknown feature. |
data[].model | string | |
data[].provider | string | |
data[].outcome | "ok" | "blocked" | "error" | "quota" | "disabled" | |
data[].durationMs | number | null | |
data[].inputKind | string | null | `image`, `text` or `audio`: what was sent, never the content. |
data[].redactions | integer | Personal-data patterns masked before the call. |
data[].detail | string | null | |
data[].createdAt | string | ISO-8601 timestamp (UTC). |
nextCursor | string | null | Pass as `cursor` for the next (older) page; null on the last page. |
Response 401 Missing, expired or revoked bearer token.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
GET/v1/ai/events.csv
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
feature | query | string | no | Only this feature (an unknown value is ignored). |
outcome | query | "ok" | "blocked" | "error" | "quota" | "disabled" | no | Only this outcome (an unknown value is ignored). |
since | query | string | no | Only events at or after this ISO 8601 time. |
cursor | query | string | no | `nextCursor` from the previous page. |
limit | query | integer | no | Rows (default and maximum: the largest page). |
curl "https://api.brixsignage.com/v1/ai/events.csv" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 401 Missing, expired or revoked bearer token.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
GET/v1/ai/models
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.
curl "https://api.brixsignage.com/v1/ai/models" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.fingerprint | string | Changes whenever any model below changes. |
data.providers | array of string | |
data.firstParty | string | A plain statement of who runs the models. |
data.safeUse | array of string | The safe-use guidance shown with AI features. |
data.features | array of object | |
data.features[].feature | string | |
data.features[].label | string | |
data.features[].sends | string | |
data.features[].model | string | |
data.features[].provider | string | |
data.features[].since | string | When this model started running the feature (a date). |
data.features[].what | string | |
data.features[].previous | array of object | |
data.features[].previous[].model | string | |
data.features[].previous[].until | string | |
data.features[].previous[].why | string | |
data.features[].fallback | object | |
data.features[].fallback.model | string | |
data.features[].fallback.provider | string | |
data.features[].fallback.when | string | |
data.features[].configuredBy | string | |
data.safety | array of object | Models that screen text before it is sent. |
data.safety[].key | string | |
data.safety[].model | string | |
data.safety[].provider | string | |
data.safety[].since | string | When this model started running the feature (a date). |
data.safety[].what | string | |
data.safety[].runsWhen | string | |
data.rollback | string |
Response 401 Missing, expired or revoked bearer token.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
GET/v1/ai/summary
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
days | query | integer | no | Window in days, 1–365 (default 30). |
curl "https://api.brixsignage.com/v1/ai/summary" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.windowDays | integer | |
data.since | string | ISO-8601 timestamp (UTC). |
data.totals | object | |
data.totals.ran | integer | |
data.totals.failed | integer | |
data.totals.refusedByPolicy | integer | |
data.totals.refusedByLimit | integer | |
data.totals.redactions | integer | |
data.byFeature | array of object | One row per feature, model and outcome. |
data.byFeature[].feature | string | |
data.byFeature[].featureLabel | string | |
data.byFeature[].model | string | |
data.byFeature[].outcome | string | |
data.byFeature[].calls | integer | |
data.byFeature[].redactions | integer |
Response 401 Missing, expired or revoked bearer token.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |