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.
View as Markdown · For AI agents: the full docs index is at /llms.txt
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
Every 4xx and 5xx response below returns this body:
| 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
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.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 5XX: Server error. The body carries a requestId to quote 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.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 5XX: Server error. The body carries a requestId to quote 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.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 5XX: Server error. The body carries a requestId to quote 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.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 5XX: Server error. The body carries a requestId to quote to support.