# Interactions

> 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/interactions](#get-v1-interactions)
- [GET /v1/interactions/taps](#get-v1-interactions-taps)

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/interactions

List interaction events

List engagement events from your screens, such as on-screen taps, QR code scans, presenter joins, and form submissions.

**Notes.**
- Newest first, at most 1000, from screens at locations the caller can see.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | no | ISO-8601 start (default: 7 days ago). |
| `to` | query | string | no | ISO-8601 end (default: now). |
| `screenId` | query | string | no |  |

```bash
curl "https://api.brixsignage.com/v1/interactions" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].id` | string |  |
| `data[].screenId` | string |  |
| `data[].screenName` | string | The screen id when the screen no longer exists. |
| `data[].at` | string | ISO-8601 timestamp (UTC). |
| `data[].kind` | "touch" \| "qr-scan" \| "screenshare-join" \| "form-submit" |  |
| `data[].detail` | string | A short human-readable summary. |
| `data[].boxId` | string \| null | A counted button tap only: the box that was tapped. |
| `data[].creativeId` | string \| null | A counted button tap only: the design the box is on. |
| `data[].action` | string \| null | A counted button tap only: the tap action kind (for example `open-url`). |

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/interactions/taps

Count taps per button

Returns the number of taps on each button of a design in a date range, with the design and box names. Only tap actions saved with `count: true` are counted. The busiest buttons come first, and at most 20,000 taps are read, from screens at the locations you can see.

Counted taps per button (a box on a design) in the window. Only tap actions saved with `count: true` are counted.

**Notes.**
- Most taps first. Reads at most 20,000 taps, from screens at locations the caller can see.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | no | ISO-8601 start (default: 7 days ago). |
| `to` | query | string | no | ISO-8601 end (default: now). |
| `screenId` | query | string | no |  |

```bash
curl "https://api.brixsignage.com/v1/interactions/taps" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].creativeId` | string \| null |  |
| `data[].creativeName` | string \| null | Null when the design is gone. |
| `data[].boxId` | string |  |
| `data[].boxName` | string \| null | The layer name, else its text. Null when the box is gone. |
| `data[].action` | string \| null | The tap action kind of the newest tap. |
| `data[].count` | integer |  |
| `data[].lastAt` | string | ISO-8601 timestamp (UTC). |

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.
