# Apps

Base URL: `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none.

## GET /v1/apps/{key}/render

Render a catalog app

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.

Auth: none.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | path | string | yes | Identifier for key. |

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

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

| 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

List the apps this workspace can add

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

Auth: Bearer token. Permission: `app-instance.view`.

```bash
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}

Get a live counter value

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.

Auth: none.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | Identifier for token. |

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

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

| 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}

Update a live counter value

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.

Auth: none.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | Identifier for token. |

```bash
curl -X POST "https://api.brixsignage.com/v1/apps/counter/{token}"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

| 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

Get the counter control page

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.

Auth: none.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | Identifier for token. |

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

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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