# Banners

> 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/banners](#get-v1-banners)
- [POST /v1/banners](#post-v1-banners)
- [GET /v1/banners/{id}](#get-v1-banners-id)
- [PATCH /v1/banners/{id}](#patch-v1-banners-id)
- [DELETE /v1/banners/{id}](#delete-v1-banners-id)
- [POST /v1/banners/{id}/restore](#post-v1-banners-id-restore)

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

List banners

List the announcement banners this workspace has created for display inside the content management system, including each banner's title, body, tone, audience, and active state.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Page size. Omit to get every row; pass it to page by `cursor`. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. |
| `count` | query | "1" | no | With `limit`: also return `total`, the number of matching rows. |
| `usableAt` | query | string | no | Location id: only rows usable at that location (homed there, at the workspace root, or shared to it). |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of Banner |  |
| `data[].id` | string |  |
| `data[].spaceId` | string |  |
| `data[].title` | string |  |
| `data[].body` | string \| null |  |
| `data[].tone` | "info" \| "success" \| "warning" \| "critical" |  |
| `data[].audience` | object | Free-form JSON the screens use to pick the banner (default `{}`). |
| `data[].active` | boolean |  |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].deletedAt` | string \| null |  |
| `nextCursor` | string \| null | Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page. |
| `total` | integer | Total matching rows, when the route computes it. |

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.

## POST /v1/banners

Create a banner

Create an announcement banner with a `title` and optional `body`, `tone`, `audience`, and `active` state. `tone` defaults to "info" when not specified.

**Notes.**
- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.

Auth: Bearer token. Permission: `integration.create`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | yes |  |
| `body` | string \| null | no |  |
| `tone` | "info" \| "success" \| "warning" \| "critical" | no | Default `info`. |
| `audience` | object | no |  |
| `active` | boolean | no | Default true. |

```bash
curl -X POST "https://api.brixsignage.com/v1/banners" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Staff meeting at 3","body":"Break room","tone":"warning"}'
```

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | Banner | A workspace message banner shown on screens. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.title` | string |  |
| `data.body` | string \| null |  |
| `data.tone` | "info" \| "success" \| "warning" \| "critical" |  |
| `data.audience` | object | Free-form JSON the screens use to pick the banner (default `{}`). |
| `data.active` | boolean |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 422: `title` is missing.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/banners/{id}

Get a banner

Retrieve one announcement banner.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Banner id. |

```bash
curl "https://api.brixsignage.com/v1/banners/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | Banner | A workspace message banner shown on screens. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.title` | string |  |
| `data.body` | string \| null |  |
| `data.tone` | "info" \| "success" \| "warning" \| "critical" |  |
| `data.audience` | object | Free-form JSON the screens use to pick the banner (default `{}`). |
| `data.active` | boolean |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such banner in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PATCH /v1/banners/{id}

Update a banner

Edit an announcement banner's title, body, tone, audience, or active state.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Banner id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no |  |
| `body` | string \| null | no |  |
| `tone` | "info" \| "success" \| "warning" \| "critical" | no | Default `info`. |
| `audience` | object | no |  |
| `active` | boolean | no | Default true. |

```bash
curl -X PATCH "https://api.brixsignage.com/v1/banners/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | Banner | A workspace message banner shown on screens. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.title` | string |  |
| `data.body` | string \| null |  |
| `data.tone` | "info" \| "success" \| "warning" \| "critical" |  |
| `data.audience` | object | Free-form JSON the screens use to pick the banner (default `{}`). |
| `data.active` | boolean |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such banner in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## DELETE /v1/banners/{id}

Delete a banner

Delete an announcement banner.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Banner id. |

```bash
curl -X DELETE "https://api.brixsignage.com/v1/banners/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.deleted` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such banner in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/banners/{id}/restore

Restore a banner

Restore a previously deleted announcement banner so it is active again.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Banner id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/banners/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.restored` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such banner in this workspace, or it was purged.

Response 409: `not_deleted`: the banner is not in the recycle bin.

Response 5XX: Server error. The body carries a `requestId` to quote to support.
