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

Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip 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

GET/v1/banners

Bearer token 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.

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.

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

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.

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

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.

POST/v1/banners

Bearer token 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.

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.

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

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.

Response 422 `title` is missing.

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.

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

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/{id}

Bearer token 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.

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.

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

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.

Response 404 No such banner in this workspace.

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.

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

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.

PATCH/v1/banners/{id}

Bearer token 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.

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.

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

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.

Response 404 No such banner in this workspace.

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.

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

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.

DELETE/v1/banners/{id}

Bearer token 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.

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.

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

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.

Response 404 No such banner in this workspace.

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.

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

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.

POST/v1/banners/{id}/restore

Bearer token 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.

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.

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

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.

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

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.

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

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.

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

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

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!