Apps API
Apps endpoints in the Brix REST API for digital signage: 12 operations (GET, POST). 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/apps/{key}/renderGET /v1/apps/catalogGET /v1/apps/counter/{token}POST /v1/apps/counter/{token}GET /v1/apps/counter/{token}/cardGET /v1/apps/counter/{token}/controlGET /v1/apps/counter/{token}/logoGET /v1/apps/queue/{joinId}POST /v1/apps/queue/{joinId}/cancelGET /v1/apps/queue/{joinId}/logoGET /v1/apps/queue/{joinId}/statePOST /v1/apps/queue/{joinId}/take
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/apps/{key}/render
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.
Response 404: Unknown app key. The body is still an HTML card saying so.
Response 413: config is over 8 KB.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/catalog
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.
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/apps/counter/{token}
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. The queue position: what the next call adds 1 to. |
data.label | string | null | |
data.seq | integer | Goes up by 1 on every staff action. A screen chimes when it changes, unless quiet is true. |
data.n | integer | null | The number of the latest call (or call again, or correction); null before the first write and after a restart, until a call. |
data.counter | string | null | The counter that made the latest call, or null. |
data.history | array of object | The last 20 changes, oldest first. |
data.history[].n | integer | |
data.history[].c | string | null | The counter name, or null. |
data.history[].at | string | ISO 8601 time of the change. |
data.history[].kind | "call" | "recall" | "set" | "reset" | call: the next number; recall: a number called again; set: a correction (the number that counter serves now); reset: the numbers were started again. |
data.issued | integer | null | The last ticket number handed out (join the queue); null when no ticket was taken. |
data.waiting | integer | How many tickets are not called yet (0 without tickets; cancelled tickets do not count). |
data.next | integer | The number the next call is. |
data.epoch | integer | The run of numbers: goes up when staff restart the numbers and when a day's tickets expire. |
data.quiet | boolean | true: the latest action is not a call (a restart, an undo, a number given by hand). The screen does not chime for it. |
Response 400: bad_token: the token is not 8–64 letters, digits, _ or -.
Response 401: Missing, expired or revoked bearer token.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/apps/counter/{token}
Set or adjust the value of a live counter app. Provide an absolute value or a relative change (the resulting value is clamped between 0 and 999999), or one staff action of Now Serving: call again, move the number one up or down, start the numbers again, give a number, or undo the latest action. 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). |
counter | string | no | The counter (desk) that makes this call, 1–40 characters. Listed with the number in history. |
recall | boolean | no | true: call this counter's last number again. The value does not change; seq goes up so the screen chimes. |
take | boolean | no | true: give the next ticket to a customer with no phone (join the queue). The answer adds ticket. |
queue | boolean | no | true with delta: 1: call only a number a customer took. Answers 409 nobody_waiting when nobody waits. |
move | integer | no | 1 or -1: move this counter's number one up or one down (a correction, not a call). 409 at_minimum / at_maximum when it cannot move. |
restart | integer | no | Start the numbers again: the next call and the next ticket are this number (1–999999). Every ticket that waits is void. |
undo | integer | no | The seq an earlier action answered: put back what that action changed. Only the latest action, for 2 minutes. 409 cannot_undo otherwise. |
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. |
data.seq | integer | Goes up by 1 on every staff action. A screen chimes when it changes, unless quiet is true. |
data.n | integer | null | The number of the latest call (or call again, or correction); null before the first write and after a restart, until a call. |
data.counter | string | null | The counter that made the latest call, or null. |
data.history | array of object | The last 20 changes, oldest first. |
data.history[].n | integer | |
data.history[].c | string | null | The counter name, or null. |
data.history[].at | string | ISO 8601 time of the change. |
data.history[].kind | "call" | "recall" | "set" | "reset" | call: the next number; recall: a number called again; set: a correction (the number that counter serves now); reset: the numbers were started again. |
data.issued | integer | null | The last ticket number handed out (join the queue); null when no ticket was taken. |
data.waiting | integer | How many tickets are not called yet (0 without tickets; cancelled tickets do not count). |
data.next | integer | The number the next call is. |
data.epoch | integer | The run of numbers: goes up when staff restart the numbers and when a day's tickets expire. |
data.quiet | boolean | true: the latest action is not a call (a restart, an undo, a number given by hand). The screen does not chime for it. |
data.ticket | integer | With take: the number to give the customer. |
data.undone | boolean | With undo: true when the earlier action was put back. |
Response 400: bad_token; bad_counter: counter is not 1–40 plain characters; bad_move, bad_number, bad_undo: that field is not valid; or value_or_delta_required: no action was sent.
Response 401: Missing, expired or revoked bearer token.
Response 404: unknown_token: no saved app uses this control code.
Response 409: nothing_to_recall: this counter has not called a number yet; nobody_waiting: queue is set and nobody waits; queue_full: take and 300 customers already wait; at_minimum / at_maximum: move would leave 0–999999; cannot_undo: another action came after, or the time is over.
Response 429: More than 120 updates a minute.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/counter/{token}/card
Public printable staff card (HTML) for a counter app: Now Serving's A6 card or Goal Tracker's QR page. Its QR is the control page on the workspace's console host; 404 once no saved app owns the code. Notes. - Now Serving: the A6 staff card. Goal Tracker: a page with the QR code. The QR code opens the control page on the workspace's own console host, with the counters and the phone queue of the saved app.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
token | path | string | yes | The counter's control code (8–64 letters, digits, _ or -), from the app's settings. |
lang | query | string | no | BCP 47 language tag for the card's text (default en-US). |
curl "https://api.brixsignage.com/v1/apps/counter/{token}/card"Response 400: The token is not 8–64 letters, digits, _ or - (plain text body).
Response 401: Missing, expired or revoked bearer token.
Response 404: No saved app owns this control code (plain text body).
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/counter/{token}/control
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). |
c | query | string | no | A counter name; repeat it once per counter. With counters the page asks which counter the phone is and shows Next and Call again. |
lang | query | string | no | BCP 47 language tag for the page's text (default en-US). |
q | query | string | no | 1: customers take numbers on their phones. The page shows how many wait and Give a number, and Next calls only a number a customer took. |
curl "https://api.brixsignage.com/v1/apps/counter/{token}/control"Response 400: The token is not 8–64 letters, digits, _ or - (plain text body).
Response 401: Missing, expired or revoked bearer token.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/counter/{token}/logo
Public image: the Brand logo of the workspace whose saved app owns the control code (a file of that workspace only), for the phone pages and the staff card.
| 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}/logo"Response 401: Missing, expired or revoked bearer token.
Response 404: No saved app owns this control code, or its workspace has no Brand logo that is an image of that workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/queue/{joinId}
Get the HTML page a customer opens from the Now Serving screen's QR code to take a queue number on their phone. The join id in the URL is the control code sealed with a server key, so the page never holds the control code. Notes. - The screen's customer QR opens this page. The join id is the control code sealed with a server key; the page never holds the control code.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
joinId | path | string | yes | The join id from the screen's customer QR: the control code sealed with a server key (base64url). |
label | query | string | no | The page's heading (default Now Serving). |
lang | query | string | no | BCP 47 language tag for the page's text (default en-US). |
curl "https://api.brixsignage.com/v1/apps/queue/{joinId}"Response 401: Missing, expired or revoked bearer token.
Response 404: The join id does not open (HTML page that says so).
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/apps/queue/{joinId}/cancel
Give a queue number back. The place is free at once: the screen and the staff page count one fewer customer, and the next call passes over the number. Send the ticket number, its epoch and the key the take answer gave. Only the holder of the key can cancel the ticket.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
joinId | path | string | yes | The join id from the screen's customer QR: the control code sealed with a server key (base64url). |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
ticket | integer | yes | The ticket number. |
epoch | integer | yes | The epoch the ticket was taken in. |
key | string | yes | The key the take answer gave for this ticket. |
curl -X POST "https://api.brixsignage.com/v1/apps/queue/{joinId}/cancel" \
-H "Content-Type: application/json"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.cancelled | boolean | |
data.waiting | integer | How many tickets are not called yet, after the cancel. |
Response 400: bad_ticket: ticket or epoch is not a whole number.
Response 401: Missing, expired or revoked bearer token.
Response 403: bad_ticket: the key is not the key of this ticket.
Response 404: not_found: the join id does not open.
Response 409: not_waiting: the ticket was called, has passed or has expired. state says which.
Response 429: More than 10 cancels a minute from one address.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/queue/{joinId}/logo
Public image: the Brand logo of the shop behind a sealed join id, for the customer take-a-number page.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
joinId | path | string | yes | The join id from the screen's customer QR: the control code sealed with a server key (base64url). |
curl "https://api.brixsignage.com/v1/apps/queue/{joinId}/logo"Response 401: Missing, expired or revoked bearer token.
Response 404: The join id does not open, or the workspace has no Brand logo that is an image of that workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/apps/queue/{joinId}/state
Get the number now called, the counter that called it and how many customers wait. Access is controlled by the join id in the URL. The answer never contains the control code or the call history.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
joinId | path | string | yes | The join id from the screen's customer QR: the control code sealed with a server key (base64url). |
t | query | integer | no | A ticket number, to learn where it stands. |
e | query | integer | no | The epoch that ticket was taken in. |
curl "https://api.brixsignage.com/v1/apps/queue/{joinId}/state"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.value | integer | null | The last number called; null before the first write. |
data.n | integer | null | The number of the latest call (or recall, or set). |
data.counter | string | null | The counter that made the latest call, or null. |
data.seq | integer | Goes up by 1 on every call, recall and set. |
data.issued | integer | null | The last ticket number handed out; null when no ticket was taken. |
data.waiting | integer | How many tickets are not called yet (cancelled tickets do not count). |
data.epoch | integer | The run of numbers: goes up when staff restart the numbers and when a day's tickets expire. |
data.ticket | object | With t and e: where that ticket stands. |
data.ticket.state | "waiting" | "called" | "passed" | "cancelled" | "expired" | |
data.ticket.before | integer | waiting: how many customers are in front. |
data.ticket.counter | string | null | called: the counter to go to, or null. |
data.ticket.call | string | called: changes on every call of this number (a call again is a new call). |
Response 401: Missing, expired or revoked bearer token.
Response 404: not_found: the join id does not open.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/apps/queue/{joinId}/take
Give the customer the next queue number. Each call hands out one number, with the key that lets its holder cancel it. At most 300 customers can wait, and one address can take 10 numbers a minute. Access is controlled by the join id in the URL.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
joinId | path | string | yes | The join id from the screen's customer QR: the control code sealed with a server key (base64url). |
curl -X POST "https://api.brixsignage.com/v1/apps/queue/{joinId}/take"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.ticket | integer | The customer's number. |
data.value | integer | The last number called. |
data.n | integer | The number of the latest call. |
data.counter | string | null | |
data.waiting | integer | How many tickets are not called yet, this one included. |
data.before | integer | How many customers are in front of this ticket. |
data.epoch | integer | The run of numbers this ticket belongs to. |
data.key | string | The key of this ticket. Only its holder can cancel the ticket. |
Response 401: Missing, expired or revoked bearer token.
Response 404: not_found: the join id does not open, or no saved app uses its control code.
Response 409: queue_full: 300 customers already wait.
Response 429: More than 10 tickets a minute from one address.
Response 5XX: Server error. The body carries a requestId to quote to support.