Banners API

Banners endpoints in the Brix REST API: 6 operations (GET, POST, PATCH, DELETE). 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.

GET /v1/banners
POST /v1/banners
GET /v1/banners/{id}
PATCH /v1/banners/{id}
DELETE /v1/banners/{id}
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

Auth: Bearer token. Permission: integration.view.

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.

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

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

Auth: Bearer token. Permission: integration.create.

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.

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.

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}

Auth: Bearer token. Permission: integration.view.

Retrieve one announcement banner.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Banner id.

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}

Auth: Bearer token. Permission: integration.edit.

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

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

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}

Auth: Bearer token. Permission: integration.delete.

Delete an announcement banner.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Banner id.

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

Auth: Bearer token. Permission: integration.delete.

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

Parameter	In	Type	Required	Description
`id`	path	string	yes	Banner id.

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.

GET /v1/banners

POST /v1/banners

GET /v1/banners/{id}

PATCH /v1/banners/{id}

DELETE /v1/banners/{id}

POST /v1/banners/{id}/restore

Connect With Us

Message Received!