# AI

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/ai/events](#get-v1-ai-events)
- [GET /v1/ai/events.csv](#get-v1-ai-events-csv)
- [GET /v1/ai/models](#get-v1-ai-models)
- [GET /v1/ai/summary](#get-v1-ai-summary)

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

List AI activity 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.

Auth: Bearer token. Permission: `audit-log.view`.

Parameters:

| Name | 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. |

```bash
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

Export AI activity events as 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.

Auth: Bearer token. Permission: `audit-log.view`.

Parameters:

| Name | 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). |

```bash
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

List AI models in use

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.

Auth: Bearer token. Permission: `settings.view`.

```bash
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

Summarize AI activity

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`.

Auth: Bearer token. Permission: `audit-log.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | no | Window in days, 1–365 (default 30). |

```bash
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.
