Apps API

Apps endpoints in the Brix REST API for digital signage: 5 operations (GET, POST). 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/apps/{key}/render
GET /v1/apps/catalog
GET /v1/apps/counter/{token}
POST /v1/apps/counter/{token}
GET /v1/apps/counter/{token}/control

GET/v1/apps/{key}/render

No auth

Get the rendered HTML for one app from the app catalog. This is the same output used by the player and by the content management system preview. **Notes.** - HTML for an iframe, with a strict content security policy; who may frame it is limited to Brix players and the console.

Parameter	In	Type	Required	Description
`key`	path	string	yes	The app's catalog key.
`config`	query	string	no	The app's settings as a JSON string (at most 8 KB; invalid JSON renders the defaults).
`lang`	query	string	no	BCP 47 language tag for the app's text (default `en-US`).
`brand`	query	string	no	A brand kit as a JSON string, for apps that follow the brand.
`dt`	query	string	no	An app data token, for an app bound to a data source (`dataSourceId` in `config`).

curl "https://api.brixsignage.com/v1/apps/{key}/render"

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 404 Unknown app key. The body is still an HTML card saying so.

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 413 `config` is over 8 KB.

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/apps/catalog

Bearer token app-instance.view

List the apps available to your workspace, including which ones are currently visible for your account to add.

curl "https://api.brixsignage.com/v1/apps/catalog" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Field	Type	Description
`data`	object
`data.apps`	array of object
`data.apps[].key`	string	The `appKey` to create an instance with.
`data.apps[].status`	"alpha" \| "beta" \| "ga" \| "deprecated"
`data.apps[].visible`	boolean	True when this workspace can add it: enabled and GA, or alpha/beta with early access.

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.

GET/v1/apps/counter/{token}

No auth

Get the current value of a live counter app, such as Now Serving or Goal Tracker. Access is controlled by the token in the URL rather than by an API key; anyone with the token can read the value. **Notes.** - An unknown token answers 200 with value: null, not 404.

Parameter	In	Type	Required	Description
`token`	path	string	yes	The counter's control code (8–64 letters, digits, `_` or `-`), from the app's settings.

curl "https://api.brixsignage.com/v1/apps/counter/{token}"

Response 200 Success.

Field	Type	Description
`data`	object
`data.value`	integer \| null	Null until the counter is first set.
`data.label`	string \| null

Response 400 `bad_token`: the token is not 8–64 letters, digits, `_` or `-`.

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 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 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/apps/counter/{token}

No auth

Set or adjust the value of a live counter app. Provide either an absolute value or a relative change, and the resulting value is clamped between 0 and 999999. Access is controlled by the token in the URL rather than by an API key.

Parameter	In	Type	Required	Description
`token`	path	string	yes	The counter's control code (8–64 letters, digits, `_` or `-`), from the app's settings.

Request body application/json

Field	Type	Required	Description
`value`	number	no	Set to this value.
`delta`	number	no	Add this (may be negative). Used when `value` is absent.
`label`	string	no	A new label (first 80 characters kept).

curl -X POST "https://api.brixsignage.com/v1/apps/counter/{token}" \
  -H "Content-Type: application/json"

Response 200 Success.

Field	Type	Description
`data`	object
`data.value`	integer	The stored value, 0–999999.
`data.label`	string \| null	The label SENT in this request; null when none was sent, even if one is stored.

Response 400 `bad_token`, or `value_or_delta_required`: neither is a number.

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 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 404 `unknown_token`: no saved app uses this control code.

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 429 More than 120 updates a minute.

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/apps/counter/{token}/control

No auth

Get an HTML page with simple controls for adjusting a live counter from a phone. The page submits its changes back to the counter endpoint. Access is controlled by the token in the URL.

Parameter	In	Type	Required	Description
`token`	path	string	yes	The counter's control code (8–64 letters, digits, `_` or `-`), from the app's settings.
`start`	query	number	no	The value shown before the first read.
`label`	query	string	no	The page's heading (default `Now Serving`).

curl "https://api.brixsignage.com/v1/apps/counter/{token}/control"

Response 400 The token is not 8–64 letters, digits, `_` or `-` (plain text 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.

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 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/apps/{key}/render

GET/v1/apps/catalog

GET/v1/apps/counter/{token}

POST/v1/apps/counter/{token}

GET/v1/apps/counter/{token}/control

Connect With Us

Message Received!