# Brix developer documentation (full text) > Brix is cloud digital signage software. This file is every page of the Brix developer docs as plain markdown, followed by the complete REST API reference. Use it to call the Brix API or connect an agent over MCP. Docs: https://brixsignage.com/developers/ · Index: https://brixsignage.com/llms.txt · OpenAPI: https://api.brixsignage.com/v1/openapi.json # Use cases for AI agents Brix can be run from an AI assistant. Connect Claude or ChatGPT to the Brix MCP server by signing in with a Brix account (no API key), from [Claude's connector directory](https://claude.ai/directory/connectors/brix), or use an API key from Settings > AI, API & MCP in the CMS. The endpoint is `https://api.brixsignage.com/v1/mcp`. Every tool acts with the signed-in person's or the key's own permissions and location scope, and every change it makes lands in the workspace audit log. Setup and the full tool catalog: [MCP server docs](https://brixsignage.com/developers/mcp.md). Everything else: [developer docs](https://brixsignage.com/developers.md) and the [REST API reference](https://brixsignage.com/developers/api.md). Jobs an agent can do with Brix, and the MCP tools that do them: - Find which screens are offline: `search_screens` with `status: offline` (optionally under one location), then `screen_health` with `view: diagnose` for the likely cause and a checklist, or `view: outages` for each outage in the last 30 days with its cause. `list_open_alerts` lists open alerts. - Weekly uptime report: `get_uptime_report` gives online % per screen and per location, downtime windows with their causes, worst screens first. - Change or schedule a menu: `search_media` to find the new menu, then `assign_content` to put a playlist, schedule, layout or media item on one screen or many; `update_playlist` to add, remove or reorder items or set a play window; `bulk_create` with `schedules` for dayparts (breakfast and lunch menus by day of week and time, in each screen's time zone). Before a price change goes live, `refresh_all_data_sources` or `sync_data_source` pulls fresh data from a Google Sheet, CSV or POS feed. - Show something for a set time: `cast_content` puts existing content on screens until a chosen time, then they return to their schedule; `end_cast` stops it early. - Pull proof of play: `get_proof_of_play` returns plays, watch time, skips and failures per piece of content for a date range, and which screens reported. Needs `playback-log.view`, and proof of play switched on in the workspace. - See what a screen is showing now: `capture_device_frame` takes a fresh screenshot from the screen; `screen_health` with `view: why` explains why it shows what it shows (emergency, cast, schedule or default). - Emergency takeover: `list_emergency_templates`, then `trigger_emergency_template` fires a pre-set template (lockdown, severe weather, fire drill) on every screen in its scope. - Fix a stuck screen: `reboot_screen`, `refresh_screen`, `clear_screen_cache`, or `set_tv_power` to turn the TV on or off over HDMI-CEC, on one screen or many. - Approve content: `list_pending_approvals`, then `decide_approval` approves or rejects (with a reason), when the connected person is an approver. - Undo a delete: `list_recycle_bin`, then `restore_recycle_bin_item` restores an item deleted in the last 30 days. - Set up a queue board (Now Serving): `get_items` with `kind: app_types` and `ids: ["now-serving"]` lists its settings (counters, queue, display, sound) with their values and defaults; `create_items` with `apps` creates it, and the result has `staffLinks`: the staff page that calls the next number, a staff card to print and, when customers take numbers on their phones, the customer page. `set_screen_content` puts it on a screen. If a customer gets the staff link, `update_items` with `newControlCode: true` makes a new one. The `set_up_now_serving` prompt walks the whole setup. - Move from another signage platform: `upload_media_from_url` pulls files from a public link, `bulk_create` creates up to 500 playlists, 200 schedules or 1,000 locations in one call, `create_web_link` adds a web page or dashboard. - Find anything: `list_items` lists playlists, schedules, layouts, apps, data sources, screen groups, locations, media folders and running casts. `search_audit_log` shows who changed what. Anything without a tool goes through the REST API (https://brixsignage.com/developers/api.md) with an API key. # Brix developer docs > Control Brix digital signage from code or an AI agent. REST API, MCP server, webhooks, API keys and a full reference generated from the OpenAPI spec. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/ Brix is cloud digital signage software. Everything the Brix CMS does goes through the same public API, so a script, an integration or an AI agent can do it too: list screens, upload media, build playlists, schedule content, take over screens for a set time, and read proof of play and uptime. ## Four ways in | Way in | Use it when | Start here | | --- | --- | --- | | REST API | You write code: a sync job, a POS or HR integration, a report. | [Quickstart](https://brixsignage.com/developers/quickstart/) | | MCP server | You want Claude, ChatGPT, Cursor or another agent to operate your screens. | [Connect an AI agent (MCP)](https://brixsignage.com/developers/mcp/) | | TypeScript SDK | You write TypeScript or JavaScript and want typed calls. Node, Deno, Bun, browsers and Workers. | [TypeScript SDK](https://brixsignage.com/developers/sdk/) | | CLI | You work in a terminal or a shell script: reboot a screen, upload media, cast content. | [Command-line tool (CLI)](https://brixsignage.com/developers/cli/) | Both the REST API and the MCP server use the same API keys, the same permissions and the same workspace boundary. The SDK and the CLI call the REST API, so they use them too. claude.ai and ChatGPT can also connect to the MCP server by signing in, with no key. Brix is in Claude's connector directory: [claude.ai/directory/connectors/brix](https://claude.ai/directory/connectors/brix). What it does and what to ask: [Brix connector for Claude](https://brixsignage.com/claude/). Setup details: [Connect an AI agent (MCP)](https://brixsignage.com/developers/mcp/#find-brix-in-claudes-connector-directory). ## The basics - Base URL: `https://api.brixsignage.com`. Every path starts with `/v1`. - Auth: `Authorization: Bearer `. Create keys in the CMS at **Settings > AI, API & MCP**. See [Authentication and scopes](https://brixsignage.com/developers/authentication/). - Success bodies are `{ "data": ... }`. Errors are `{ "error": "", "message": "" }`. See [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits/). - Default rate limit: 600 requests per minute per workspace, across all keys. - Every workspace can create API keys. There is no separate API plan and no per-call charge. - MCP endpoint: `https://api.brixsignage.com/v1/mcp`. ```bash curl https://api.brixsignage.com/v1/me \ -H "Authorization: Bearer $BRIX_API_KEY" ``` ## Pages - [Quickstart](https://brixsignage.com/developers/quickstart/): create a key, make a first call, list screens, cast content to a screen. - [Authentication and scopes](https://brixsignage.com/developers/authentication/): key format, permissions, location-pinned keys, OAuth client credentials. - [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits/): the error envelope, error codes, rate-limit headers, retries, idempotency. - [Pagination](https://brixsignage.com/developers/pagination/): cursor pagination on list endpoints. - [Connect an AI agent (MCP)](https://brixsignage.com/developers/mcp/): Claude Code, Claude Desktop, Cursor, ChatGPT and the Claude API, plus the full tool catalog. - [Webhooks](https://brixsignage.com/developers/webhooks/): subscribe to events, verify signatures, retries. - [API reference](https://brixsignage.com/developers/api/): every customer endpoint, grouped by resource. ## For agents and LLMs - [/llms.txt](https://brixsignage.com/llms.txt): a short index of Brix, with links to these pages. - [/llms-full.txt](https://brixsignage.com/llms-full.txt): every developer page and the full API reference as one markdown file. - Every page here has a markdown twin. Add `.md` to the path without the trailing slash, for example [/developers/quickstart.md](https://brixsignage.com/developers/quickstart.md). - OpenAPI 3.1 spec: [https://api.brixsignage.com/v1/openapi.json](https://api.brixsignage.com/v1/openapi.json). A copy is also served at [https://brixsignage.com/openapi.json](https://brixsignage.com/openapi.json). # Quickstart > Create a Brix API key, make your first request with curl, list your screens and cast a playlist to a screen for an hour. Copy-paste commands. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/quickstart/ This page takes you from nothing to content on a screen. You need a Brix workspace with at least one paired screen, and `curl`. Every command runs against the live API. ## 1. Create an API key 1. Sign in to the CMS at [cms.brixsignage.com](https://cms.brixsignage.com). 2. Open **Settings > AI, API & MCP**. 3. Select **New key**. 4. Type a name into **Name**, for example `Quickstart`. 5. Under **Permissions**, select **Screens** and **Playlists**. Leave **Limit to a location** empty. 6. Select **Create key**. 7. Copy the key from the panel. Brix shows the full key once. A key looks like `ak_us_live_` followed by 32 characters. The second part is your workspace's data region: `us`, `eu`, `oc` or `apac`. You need the `api-key.create` permission to make a key. Workspace Owners and Admins have it. A key never gets a permission that the person who creates it does not hold. Store the key in an environment variable: ```bash export BRIX_API_KEY="ak_us_live_..." ``` ## 2. Check who you are ```bash curl https://api.brixsignage.com/v1/me \ -H "Authorization: Bearer $BRIX_API_KEY" ``` ```json { "data": { "actor": { "kind": "key", "id": "ak_...", "name": "Quickstart", "nodeId": null }, "workspace": { "id": "...", "name": "Acme Coffee" }, "permissions": ["screen.view", "screen.cast", "playlist.view", "..."] } } ``` `permissions` is what this key may do. If a later call returns 403 or an empty list, check this first. A missing header returns `401 {"error":"missing_credentials",...}`. A wrong, revoked or expired key returns `401 {"error":"invalid_credentials",...}`. ## 3. List your screens ```bash curl "https://api.brixsignage.com/v1/screens?limit=50" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` ```json { "data": [ { "id": "scr_...", "name": "Lobby", "status": "online", "contentKind": "playlist", "contentId": "pl_...", "lastSeenAt": "..." } ], "nextCursor": null } ``` The response is trimmed here. Copy the `id` of the screen you want to use. When `nextCursor` is not null, there are more screens: see [Pagination](https://brixsignage.com/developers/pagination/). With [jq](https://jqlang.org), print id, name and status: ```bash curl -s "https://api.brixsignage.com/v1/screens?limit=500" \ -H "Authorization: Bearer $BRIX_API_KEY" | jq -r '.data[] | [.id, .name, .status] | @tsv' ``` ## 4. Find a playlist ```bash curl -s https://api.brixsignage.com/v1/playlists \ -H "Authorization: Bearer $BRIX_API_KEY" | jq -r '.data[] | [.id, .name] | @tsv' ``` Copy the `id` of a playlist. ## 5. Cast the playlist to the screen for one hour A cast is a timed takeover. The screens play your content until `expiresAt`, then go back to their normal schedule by themselves. ```bash SCREEN_ID="scr_..." PLAYLIST_ID="pl_..." EXPIRES_AT=$(( $(date +%s) * 1000 + 3600000 )) # one hour from now, epoch milliseconds curl -X POST https://api.brixsignage.com/v1/casts \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"contentKind\": \"playlist\", \"contentId\": \"$PLAYLIST_ID\", \"scopeKind\": \"screens\", \"screenIds\": [\"$SCREEN_ID\"], \"expiresAt\": $EXPIRES_AT }" ``` The API answers `201` with the cast: ```json { "data": { "id": "cast_...", "kind": "cast", "status": "active", "contentKind": "playlist", "contentId": "pl_...", "scopeKind": "screens", "screenCount": 1, "triggeredAt": "...", "expiresAt": "..." } } ``` Keep the cast id for the next step. With jq, run the same request with `curl -s ... | jq -r .data.id` and store it: ```bash CAST_ID="cast_..." # data.id from the response above ``` Always send `scopeKind`. If you leave it out, the cast goes to **every screen** the key can reach. | Field | Values | | --- | --- | | `contentKind` | `media`, `playlist`, `app`, `creative`, `schedule` | | `contentId` | The id of that content. | | `scopeKind` | `screens` (with `screenIds`), `node` (with `scopeNodeId`, a location and everything under it), or `all`. Default `all`. | | `expiresAt` | ISO 8601 date-time or epoch milliseconds. Omit it and the cast stays until you clear it. | | `contentName` | Optional label shown in the CMS. | The key needs `screen.cast`. A newer cast on the same screens replaces an older one. An emergency takeover pre-empts a cast, and the cast resumes after it. ## 6. End the cast early ```bash curl -X POST https://api.brixsignage.com/v1/casts/$CAST_ID/clear \ -H "Authorization: Bearer $BRIX_API_KEY" ``` The screens go back to their scheduled content at once. Clearing a cast that already ended returns `409 already_inactive`. To see what is on air now: ```bash curl "https://api.brixsignage.com/v1/casts?status=active" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` ## Change what a screen plays by default A cast is temporary. To change the content a screen plays every day, assign it: ```bash curl -X POST https://api.brixsignage.com/v1/screens/$SCREEN_ID/assign \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"contentKind\": \"playlist\", \"contentId\": \"$PLAYLIST_ID\"}" ``` `contentKind` is one of `playlist`, `schedule`, `layout`, `creative`, `signage`, `app`, `media`. Send `"contentKind": null` to clear the assignment. For many screens at once, use `POST /v1/screens/bulk-assign` with `screenIds`. ## Upload a file ```bash curl -X POST https://api.brixsignage.com/v1/media/upload \ -H "Authorization: Bearer $BRIX_API_KEY" \ -F "file=@menu.jpg" \ -F "name=Winter menu" ``` The key needs `media.create`. The response is `201` with the new media item in `data`. Use its `id` as `contentId` with `"contentKind": "media"`. For files over about 100 MB, use the multipart upload routes under `/v1/media/upload/multipart/`. To import from a public URL, use `POST /v1/media/import-url`. SVG files are refused. ## Use the TypeScript SDK The same calls with the [TypeScript SDK](https://brixsignage.com/developers/sdk/): ```bash npm install https://brixsignage.com/sdk/latest.tgz ``` ```ts import { BrixClient } from "@brixsignage/sdk"; const brix = new BrixClient({ token: process.env.BRIX_API_KEY! }); const { data: screens } = await brix.screens.listScreens({ limit: 50 }); await brix.screens.assignContent({ id: screens[0].id, contentKind: "playlist", contentId: "pl_..." }); ``` ## Next - [Authentication and scopes](https://brixsignage.com/developers/authentication/) for least-privilege keys. - [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits/) before you ship an integration. - [TypeScript SDK](https://brixsignage.com/developers/sdk/) for typed calls from Node, Deno, Bun, browsers and Workers. - [API reference](https://brixsignage.com/developers/api/) for every endpoint. - [Connect an AI agent (MCP)](https://brixsignage.com/developers/mcp/) to do all of this from Claude or ChatGPT. # TypeScript SDK > Install the Brix TypeScript SDK from brixsignage.com and call the API with typed methods. Runs in Node, Deno, Bun, browsers and Cloudflare Workers. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/sdk/ The Brix TypeScript SDK is a typed client for the [REST API](https://brixsignage.com/developers/api/). It has one method for each operation in the [OpenAPI spec](https://api.brixsignage.com/v1/openapi.json), with request and response types. It has no runtime dependencies and uses the platform `fetch`, so it runs in Node 18 or later, Deno, Bun, browsers and Cloudflare Workers. The package name is `@brixsignage/sdk`. Brix hosts it on brixsignage.com. It is not on the npm registry. ## Install ```bash npm install https://brixsignage.com/sdk/latest.tgz ``` pnpm and yarn take the same URL: ```bash pnpm add https://brixsignage.com/sdk/latest.tgz yarn add @brixsignage/sdk@https://brixsignage.com/sdk/latest.tgz ``` `latest.tgz` is always the newest version. To pin a version, install its own file, for example `https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz`. The list of versions, with a SHA-256 checksum and the npm integrity hash for each file, is at [brixsignage.com/sdk/manifest.json](https://brixsignage.com/sdk/manifest.json). ### Without a package manager Deno, a browser page or a Worker can import the ES module directly: ```ts import { BrixClient } from "https://brixsignage.com/sdk/v1/index.js"; ``` `/sdk/v1/index.js` is the newest version. `/sdk//index.js` is a fixed version. The type declarations are next to the module (`index.d.ts`), and Deno finds them without extra setup. Do not put an API key in code that runs in a browser. Anyone who opens the page can read it. Call the API from a server or a Worker. ## Create a client You need an API key. See [Quickstart](https://brixsignage.com/developers/quickstart/#1-create-an-api-key) to make one. ```ts import { BrixClient } from "@brixsignage/sdk"; const brix = new BrixClient({ token: process.env.BRIX_API_KEY! }); ``` | Option | Default | What it does | | --- | --- | --- | | `token` | none | Your API key (`ak_...`). Sent as `Authorization: Bearer `. | | `baseUrl` | `https://api.brixsignage.com` | The API origin. | | `timeoutInSeconds` | 60 | Time limit for each request. | | `maxRetries` | 2 | Retries for a 408, 429, 502, 503 or 504 response, with backoff. | | `fetch` | global `fetch` | A different `fetch` implementation. | | `headers` | none | Extra headers on every request. | ## Example: list screens and assign a playlist This script prints your screens, then makes the first screen play the first playlist by default. Save it as `brix.ts` and run it with `BRIX_API_KEY=ak_... npx tsx brix.ts`. ```ts import { BrixClient, BrixError } from "@brixsignage/sdk"; const brix = new BrixClient({ token: process.env.BRIX_API_KEY! }); async function main() { // 1. Who am I? The key's workspace and permissions. const { data: me } = await brix.me.getMe(); console.log("workspace:", me.workspace.name); // 2. List screens (up to 50; pass nextCursor as cursor for the next page). const { data: screens, nextCursor } = await brix.screens.listScreens({ limit: 50 }); for (const screen of screens) console.log(screen.id, screen.name, screen.status); if (nextCursor) console.log("more screens after", nextCursor); // 3. Pick a playlist. const { data: playlists } = await brix.playlists.listPlaylists(); const screen = screens[0]; const playlist = playlists[0]; if (!screen || !playlist) return; // 4. Assign it: the screen plays this playlist by default from now on. await brix.screens.assignContent({ id: screen.id, contentKind: "playlist", contentId: playlist.id }); console.log(`assigned ${playlist.name} to ${screen.name}`); } main().catch((err) => { if (err instanceof BrixError) { console.error(`Brix API error ${err.statusCode}:`, err.body); process.exit(1); } throw err; }); ``` The key needs `screen.view`, `screen.edit` and `playlist.view`. `contentKind` is one of `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. Send `contentKind: null` to clear the assignment. For many screens at once, use `brix.screens.bulkAssignContent({ screenIds, contentKind, contentId })`. ## Example: cast content for one hour A cast is a timed takeover. The screens go back to their normal content when it ends. ```ts const { data: cast } = await brix.casts.castContent({ contentKind: "playlist", contentId: "pl_...", scopeKind: "screens", screenIds: ["scr_..."], expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(), }); // End it early: await brix.casts.endCast({ id: cast.id }); ``` Always send `scopeKind`. If you leave it out, the cast goes to every screen the key can reach. The key needs `screen.cast`. ## Errors A response with a 4xx or 5xx status throws `BrixError`. It has `statusCode` and `body` (the API's `{ "error", "message" }` object). A request that runs past `timeoutInSeconds` throws `BrixTimeoutError`. See [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits/) for each error code. ## Types Every request and response type is in the `Brix` namespace: ```ts import { Brix } from "@brixsignage/sdk"; const request: Brix.CastContentRequest = { contentKind: "media", contentId: "med_...", scopeKind: "all" }; ``` The type declarations do not need `@types/node`. They type-check under `strict` in a browser, Deno, Bun or Workers project with only the DOM and ES2022 libraries. File uploads take a `Blob`, `File`, `ReadableStream`, `Uint8Array` or `ArrayBuffer`. In Node they also take a `Buffer` or a stream from `fs.createReadStream`. ## Find a method Methods are grouped by resource, the same groups as the [API reference](https://brixsignage.com/developers/api/): `brix.screens`, `brix.playlists`, `brix.media`, `brix.schedules`, `brix.casts` and so on. The method name is the operation's `operationId` in the OpenAPI spec. For example, `GET /v1/screens` is `listScreens` and `POST /v1/screens/{id}/assign` is `assignContent`. For an endpoint without a method, `brix.fetch(path, init)` sends a request with the same key, retries and timeout. ## Versions and checksums The SDK is generated from the public OpenAPI spec, so it follows the API. Version numbers use semver. A published version never changes. [manifest.json](https://brixsignage.com/sdk/manifest.json) lists each version with: - `tarball.url`, `tarball.sha256` and `tarball.integrity` (the npm `sha512-` hash) - `esm.url` and `types.url`, with their SHA-256 - `gitCommit`: the source commit it was built from - `specSha256`: the OpenAPI document it was generated from To check a download: ```bash curl -sO https://brixsignage.com/sdk/brix-sdk-0.1.0.tgz shasum -a 256 brix-sdk-0.1.0.tgz ``` # Command-line tool (CLI) > Install the brix CLI from npm. List screens, reboot or screenshot a display, upload media, cast content and send emergency alerts from your terminal. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/cli/ The `brix` command-line tool controls your Brix screens from a terminal or a script. It calls the [REST API](https://brixsignage.com/developers/api/) with your API key. It has commands for the common tasks and one generic command that calls any operation in the [OpenAPI spec](https://api.brixsignage.com/v1/openapi.json). - The npm package name is `brixsignage`. The command is `brix`. - It has no dependencies. It needs Node.js 18.17 or later. - It runs on macOS, Linux and Windows. ## Install ```bash npm install -g brixsignage brix --help ``` To run one command without an install: ```bash npx brixsignage screens ``` ## Log in 1. In the Brix console, go to **Settings > AI, API & MCP** and create an API key. Give it only the permissions the CLI needs. See [Authentication and scopes](https://brixsignage.com/developers/authentication/). 2. Run `brix login` and paste the key. The CLI does not show the key while you paste it. 3. Run `brix whoami` to see the workspace, the key and its permissions. The CLI checks the key with `GET /v1/me`, then saves it in `~/.config/brix/config.json`. Only your user can read that file. `brix logout` removes it. In CI or a script, set `BRIX_API_KEY` instead of `brix login`. The environment variable has priority over the saved key. ## Screens ```bash brix screens # all screens, as a table brix screens --search lobby brix screens get scr_0123456789abcdef brix screens diagnose scr_0123456789abcdef # what the screen does now and why brix screens reboot scr_0123456789abcdef brix screens refresh scr_0123456789abcdef brix screens screenshot scr_0123456789abcdef brix screens command scr_0123456789abcdef set-volume --payload '{"level":40}' brix screens assign scr_0123456789abcdef playlist pl_0123456789abcdef brix screens assign scr_0123456789abcdef --clear ``` A device runs a command the next time it checks in. The CLI prints the command ID. To read the result, run `brix call getScreenCommand --param id= --param commandId=`. ## Content ```bash brix media # the media library brix media --search menu --kind video brix media upload ./spring-menu.mp4 --name "Spring menu" brix media import https://example.com/promo.jpg brix playlists brix playlists get pl_0123456789abcdef brix schedules brix layouts ``` ## Casts and emergency alerts A cast puts content on screens for a set time. Then the screens go back to their usual content. ```bash brix cast playlist pl_0123456789abcdef --screens scr_a,scr_b --for 30m brix cast media med_0123456789abcdef --node loc_0123456789abcdef --until 2026-12-24T18:00:00Z brix casts brix casts end cast_0123456789abcdef ``` An emergency alert shows above all other content until you clear it or it expires. ```bash brix emergency "Please leave the building by the nearest exit" --all --severity critical brix emergencies brix emergencies clear emg_0123456789abcdef ``` `cast` and `emergency` need one target: `--all`, `--node ` or `--screens `. Without a target, the CLI stops and sends nothing. The API sends an unscoped cast to every screen, so the CLI makes you choose. ## Any API operation ```bash brix ops # every operation, from the OpenAPI spec brix ops webhook # search by name, path or summary brix call getScreen --param id=scr_0123456789abcdef brix call createPlaylist --data '{"name":"Lobby loop"}' brix call updateSchedule --param id=sch_0123456789abcdef --data @schedule.json brix api GET /v1/me ``` `--param` (or `-p`) fills path parameters such as `{id}`. Other parameters go in the query string. `--data` takes JSON, or `@file.json` to read a file. ## Output for scripts Add `--json` to any command to get the raw API response: ```bash brix screens --json | jq -r '.data[] | select(.status != "online") | .name' ``` Exit codes: `0` success, `1` the API refused the request, `2` a usage error, `3` no API key. ## Options | Option | Environment variable | Default | | --- | --- | --- | | `--api-key ` | `BRIX_API_KEY` | The key from `brix login` | | `--api-url ` | `BRIX_API_URL` | `https://api.brixsignage.com` | | | `BRIX_CONFIG_DIR` | `~/.config/brix` | ## Related - [Quickstart](https://brixsignage.com/developers/quickstart/): the same tasks with curl. - [TypeScript SDK](https://brixsignage.com/developers/sdk/): typed calls from your own code. - [Connect an AI agent (MCP)](https://brixsignage.com/developers/mcp/): let Claude or ChatGPT operate your screens. - Source: [github.com/BenLoveitt/brix-stack/tree/main/packages/cli](https://github.com/BenLoveitt/brix-stack/tree/main/packages/cli). Package: [npmjs.com/package/brixsignage](https://www.npmjs.com/package/brixsignage). # Authentication and scopes > How Brix API keys work: key format, the Bearer header, resource.verb permissions, location-pinned keys, rotation, revocation and OAuth client credentials. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/authentication/ Every request carries one API key as a Bearer token: ```bash curl https://api.brixsignage.com/v1/me \ -H "Authorization: Bearer $BRIX_API_KEY" ``` The key decides everything: which workspace the request acts on, what it may do, and which locations it can reach. There is no workspace header and no workspace id in the path. ## Key format `ak__live_<32 characters>`, for example `ak_eu_live_...`. - `region` is the workspace's data region: `us`, `eu`, `oc` or `apac`. The API routes the request to that region. All regions use the same host, `https://api.brixsignage.com`. - Keys made before regions were tagged look like `ak_live_...` and belong to `us`. - The CMS shows only a preview (the first 15 characters). Brix stores a SHA-256 hash, never the key itself. Brix cannot show you a lost key. Rotate it instead. - Keys are for server-side use. Browser calls from other origins are refused by CORS. Do not put a key in front-end code. ## Create a key In the CMS: **Settings > AI, API & MCP > New key**. | Field | What it does | | --- | --- | | **Name** | A label, for example `Roster sync - PowerSchool`. | | **Limit to a location (optional)** | Pins the key to one location and every location under it. Leave it empty for the whole workspace. | | **Full access** | Every permission. Shown only to people who hold every permission. | | **Permissions** | Areas such as Screens, Playlists, Files. Each area grants every action in that area that you hold. | Select **Create key**, then copy the key from the panel. It is shown once. Rules: - You need `api-key.create` to make a key, `api-key.view` to list keys and `api-key.delete` to revoke one. - A key never gets a permission its creator does not hold: `403 "A key can't be granted permissions you don't hold."` - A key for the whole workspace needs its permissions at the workspace level. Otherwise pin it to a location you control. - Every workspace can create keys. There is no plan gate. You can also manage keys over the API: ```bash # Create (returns the secret once, in data.secret) curl -X POST https://api.brixsignage.com/v1/api-keys \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Nightly report", "permissions": ["screen.view", "playback-log.view"], "expiresInDays": 90}' ``` | Field | Notes | | --- | --- | | `name` | Required. | | `permissions` | An array of `resource.verb` strings, or `"all"`. | | `nodeId` | Optional. Pins the key to that location and everything under it. | | `expiresInDays` | Optional, 1 to 3650. Omit it for a key that does not expire. The CMS does not set an expiry. | A key's record has `id`, `name`, `preview`, `permissions`, `nodeId`, `lastUsedAt`, `expiresAt`, `expired`, `revokedAt` and `createdAt`. The secret is never returned again after create or rotate. ## Rotate and revoke - **Rotate**: `POST /v1/api-keys/{id}/rotate`, or **Rotate** in the CMS. Returns a new secret once. The old secret stops working at once. Name, permissions, location and expiry stay the same. You cannot rotate a revoked key (`409 revoked`). - **Revoke**: `DELETE /v1/api-keys/{id}`, or **Revoke** in the CMS. Every integration that uses the key stops at once. This cannot be undone. An expired or revoked key gets `401 invalid_credentials`, the same as an unknown key. ## Permissions (scopes) A permission is `resource.verb`. Every endpoint requires exactly one, shown in the [API reference](https://brixsignage.com/developers/api/) and in the spec as `x-brix-permission`. A missing permission returns: ```json { "error": "forbidden", "message": "Missing permission: screen.cast" } ``` | Resource | Verbs | | --- | --- | | `screen` | view, create, edit, delete, cast, manage-permissions | | `playlist`, `schedule` | view, create, edit, delete, approve, publish, share, manage-permissions | | `layout`, `creative` | view, create, edit, delete, approve, publish, share | | `media` (Files) | view, create, edit, delete, share, export | | `font` | view, create, delete | | `app-instance` | view, create, edit, delete, share | | `brand-kit` | view, edit | | `billing` | view, edit, export | | `recycle-bin` | view, edit, delete | | `audit-log`, `playback-log` (Proof of Play) | view, export | | `org-unit`, `user`, `permission-group` (Roles), `tag`, `alert-rule` | view, create, edit, delete | | `api-key` | view, create, delete | | `integration` | view, create, edit, delete | | `data-source` | delete | | `settings` | view, edit | | `emergency-override` | view, create, edit, approve, publish | | `import` | create | Verb meanings: `cast` puts content on a screen. `publish` means publish without approval. `share` means share to other locations. Common sets: | Integration | Permissions | | --- | --- | | Read-only dashboard or AI assistant | `screen.view`, `playlist.view`, `schedule.view`, `media.view`, `playback-log.view` | | Menu or price sync | `media.view`, `media.create`, `media.edit`, `playlist.view`, `playlist.edit` | | Timed takeovers | `screen.view`, `screen.cast`, plus `.view` on the content you cast | | Webhook management | `integration.view`, `integration.edit` | ## Keys pinned to a location A key with a location (`nodeId`) sees and changes only that location and the locations under it. Anything outside returns 404, not 403. `GET /v1/me` shows the pin in `actor.nodeId`. An empty list or an unexpected 404 from a pinned key usually means the resource is outside its branch. ## Tenancy Every request resolves to one workspace. A resource that belongs to another workspace returns 404, never 403, so a response never confirms that something exists elsewhere. ## OAuth client credentials For tools that expect OAuth, exchange a key for a short-lived access token. The client id is the key's id (`ak_...`, from the key list), and the client secret is the key itself. ```bash curl -X POST https://api.brixsignage.com/v1/oauth/token \ -u "$BRIX_KEY_ID:$BRIX_API_KEY" \ -d grant_type=client_credentials ``` ```json { "access_token": "bat_...", "token_type": "Bearer", "expires_in": 3600, "scope": "..." } ``` - Send `access_token` as `Authorization: Bearer bat_...`. It lasts 3600 seconds. - The token carries the key's permissions. Revoking or rotating the key ends the token. - Credentials can go in HTTP Basic (`client_secret_basic`) or in the form body (`client_secret_post`). - Only the `client_credentials` grant exists. There is no authorization-code flow and no consent screen. - The token endpoint allows 30 requests per 5 minutes per IP address. - Discovery: `GET https://api.brixsignage.com/.well-known/oauth-authorization-server`. # Errors and rate limits > The Brix API response envelope, error codes, the 600 requests per minute workspace limit, RateLimit headers, retries and idempotency keys. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/errors-and-rate-limits/ ## Response envelope Success: ```json { "data": { "id": "scr_...", "name": "Lobby" } } ``` List endpoints return an array in `data`. Paginated lists add `nextCursor` (see [Pagination](https://brixsignage.com/developers/pagination/)). Endpoints that serve bytes, such as a media file or an invoice PDF, return the bytes. Error: ```json { "error": "validation_error", "message": "name is required" } ``` - `error` is a stable, machine-readable code. Branch on it. - `message` is for people. It can change. It is sometimes absent, for example `{"error":"not_found"}`. - 5xx errors add `requestId`. Quote it to support. ## Status codes and error codes | HTTP | `error` | Meaning | | --- | --- | --- | | 401 | `missing_credentials` | No `Authorization: Bearer` header. | | 401 | `invalid_credentials` | Key unknown, revoked or expired. | | 403 | `forbidden` | The key lacks the permission: `Missing permission: `. | | 403 | `not_shared` | The content is not shared to that screen's location. Share it there first. | | 404 | `not_found` | Does not exist, is outside the key's location, or belongs to another workspace. | | 409 | `revoked` | The key is revoked. Create a new key. | | 409 | `already_inactive` | The cast or takeover already ended. | | 409 | `idempotency_in_progress` | A request with the same `Idempotency-Key` is still running. | | 413 | `too_large` | The body or file is over the limit. | | 415 / 422 | `unsupported_type` | The file type is not accepted. | | 422 | `validation_error` | A field is missing or invalid. `message` names it. | | 422 | `invalid_node` | `nodeId is not a node in this account.` | | 422 | `invalid_folder` | The folder does not exist in this workspace. | | 422 | `content_unplayable` | The content cannot play, for example a file still processing. | | 422 | `no_screens` | The target matched no screens the key can reach. | | 429 | `rate_limited` | Over the rate limit. Wait `Retry-After` seconds. | | 500 | `internal_error` | `Something went wrong on our side.` Retry with backoff. Quote `requestId`. | | 503 | `database_busy` | Retry after `Retry-After` (2 seconds). | An unknown path returns `404 {"error":"not_found","message":"No route here."}`. ## Rate limits - **600 requests per minute per workspace**, shared by all its API keys, in fixed 60-second windows. - The limit applies to API-key traffic. People using the CMS do not count against it. - Brix support can raise the limit for a workspace. `GET /v1/account/limits` returns the workspace's limits. - Some routes also have their own limit. `POST /v1/media/upload` allows 300 per minute per key. The MCP endpoint allows 30 per minute per caller. The OAuth token endpoint allows 30 per 5 minutes per IP address. Every API-key response carries the IETF `RateLimit` headers: ``` RateLimit-Limit: 600 RateLimit-Remaining: 587 RateLimit-Reset: 41 RateLimit-Policy: 600;w=60 ``` `RateLimit-Reset` is seconds until the window resets. Over the limit, the API returns `429` with `Retry-After`: ```json { "error": "rate_limited", "message": "This workspace has used its 600 requests per minute. Wait 12 seconds and try again.", "limit": 600, "windowSeconds": 60, "retryAfterSeconds": 12 } ``` ## Retries - Retry `429`, `500`, `503` and network errors. Wait `Retry-After` when it is present, otherwise back off exponentially. - Do not retry other `4xx` responses. Fix the request. - Send an `Idempotency-Key` header on creates you might retry (screens, playlists, schedules, media upload). A repeat with the same key returns the first success instead of creating a second item. ```bash curl -X POST https://api.brixsignage.com/v1/playlists \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c1d0f5e-nightly-2026" \ -d '{"name": "Nightly specials"}' ``` ## Request ids Send `x-brix-request-id` (letters, digits, `.`, `_`, `-`, up to 120 characters) to tag a request with your own trace id. Quote it to support with the time of the call. ## Versioning and deprecation The version is in the path: `/v1`. Brix announces a retiring route at least 90 days ahead. Calls to it carry `Deprecation` and `Sunset` headers, and `GET /v1/status/deprecations` (no auth) lists every retiring route, its end date and its replacement. # Pagination > Brix list endpoints use opt-in cursor pagination: send limit, follow nextCursor until it is null. Which endpoints page, their limits, and a full loop. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/pagination/ Brix uses cursor pagination. There are no page numbers. ## How it works 1. Send `?limit=N` on a list endpoint. This turns pagination on. 2. The response has `data` and `nextCursor`. 3. Send `?cursor=` with the same `limit` to get the next page. 4. Stop when `nextCursor` is `null`. ```json { "data": [ { "id": "scr_..." } ], "nextCursor": "scr_..." } ``` - Treat the cursor as opaque. Pass it back as it came. - A page can hold fewer than `limit` items even when more follow, for example with a key pinned to one location. Always follow `nextCursor`, do not stop on a short page. - Without `limit`, these endpoints return the full list in one response. Use `limit` for large workspaces. ## Endpoints | Endpoint | `limit` | Order | Notes | | --- | --- | --- | --- | | `GET /v1/screens` | 1 to 500 | by id | | | `GET /v1/media` | default 100, max 500 | newest first | `?search=`, `?kind=`, `?state=`, `?folderId=` filters. `?count=1` adds `total`. | | `GET /v1/media-folders`, `/v1/app-instances`, `/v1/creatives`, `/v1/signage-templates`, `/v1/layouts`, `/v1/banners`, `/v1/alert-rules`, `/v1/celebration-entries` | default 100, max 500 | newest first | `?search=` and `?count=1` as above. | | `GET /v1/webhooks/deliveries` | default 50, max 200 | newest first | `?endpointId=`, `?status=` | | `GET /v1/casts` | default 200, max 500 | newest first | `?status=active`. No cursor. | | `GET /v1/playlists`, `GET /v1/schedules` | none | | Return the full list. | ## Loop over every screen ```bash cursor="" while :; do page=$(curl -s "https://api.brixsignage.com/v1/screens?limit=500${cursor:+&cursor=$cursor}" \ -H "Authorization: Bearer $BRIX_API_KEY") echo "$page" | jq -r '.data[] | [.id, .name, .status] | @tsv' cursor=$(echo "$page" | jq -r '.nextCursor // empty') [ -z "$cursor" ] && break done ``` The same loop in JavaScript: ```js async function* allScreens(key) { let cursor = null; do { const url = new URL('https://api.brixsignage.com/v1/screens'); url.searchParams.set('limit', '500'); if (cursor) url.searchParams.set('cursor', cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }); if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error}`); const page = await res.json(); yield* page.data; cursor = page.nextCursor; } while (cursor); } ``` # Connect an AI agent (MCP) > Control Brix digital signage from Claude, ChatGPT or Grok over MCP. Sign in, no key. Endpoint, setup, compatible clients and all 15 tools. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/mcp/ Yes: you can control Brix digital signage from Claude or ChatGPT. Brix runs a hosted Model Context Protocol (MCP) server at `https://api.brixsignage.com/v1/mcp`. You connect by signing in, with no key to copy, and the MCP server is on every plan ($6 per screen per month billed annually, or $8 billed monthly). - **Works in:** claude.ai, Claude Desktop and the Claude mobile apps (Brix is in [Claude's connector directory](https://claude.ai/directory/connectors/brix)), ChatGPT (Developer mode), Grok (custom connector), Claude Code, Cursor, the Claude API and the OpenAI Responses API. Any client that takes a remote MCP URL works. - **Sign-in:** OAuth 2.1 with PKCE. You pick the workspace, an optional location, and **View only** or **View and change** for each area. Or use an API key in developer tools. - **15 tools,** the same for every client (an API key adds 2 for uploading large files): - Every kind of item (screens, media, playlists, schedules, layouts, creatives, apps, data sources, screen groups, locations, folders, emergency templates): `list_items`, `get_items`, `create_items`, `update_items`, `delete_items`, `restore_items` - People: see who is in the workspace and their roles (`list_items`, `get_items`), and invite a person (`create_items`) - Put content on screens: `set_screen_content` (lasting), `start_takeover` and `end_takeover` (existing content for a while, or an emergency) - Find and fix problems: `get_screen_status`, `capture_screenshot`, `control_screens` (refresh, reboot, clear cache, TV on or off) - Approvals, data and reports: `review_approval` (approve, reject or withdraw), `refresh_data`, `get_fleet_report` (uptime, proof of play, audit log) - **Deletes go to the recycle bin** for 30 days and come back with `restore_items`. A permanent delete takes two calls: the first only shows what would be erased and gives a code, and the second must carry that code after you say yes. No access to billing or API keys, and no changes to a person's access. No Brix account yet? [Start a 7-day free trial](https://brixsignage.com/start). No card needed. The full list with arguments and permissions is in the [tool catalog](#tool-catalog). Which other signage platforms have MCP, and how they compare: [Control digital signage from Claude or ChatGPT](https://brixsignage.com/blog/control-digital-signage-from-claude-chatgpt/). ## Connection details | Setting | Value | | --- | --- | | Endpoint | `https://api.brixsignage.com/v1/mcp` | | Transport | Streamable HTTP. `POST` one JSON-RPC 2.0 message; the reply is a JSON response. No SSE stream. | | Auth | Sign in with OAuth 2.1 (claude.ai, ChatGPT, Grok and other connector apps), or `Authorization: Bearer ` with the same keys as the REST API. | | Protocol versions | `2024-11-05`, `2025-03-26`, `2025-06-18` | | Rate limit | 30 requests per minute per caller, inside the workspace's 600 per minute. Over it: HTTP 429 with `Retry-After`. | | Methods | `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get` | There are two ways to connect: - **Sign in (Claude, ChatGPT, Grok).** In Claude, find Brix in the connector directory. In ChatGPT, add the endpoint as a plugin. In Grok, add it as a custom connector. In Claude you can also add it as a custom connector. The app opens a Brix page where you sign in and choose what it may do. No key to copy. - **API key (Claude Code, Cursor, Claude Desktop config file, the Claude and OpenAI APIs).** Create a key and put it in the client's config. Either way, the permissions you pick decide what the agent can do. See [Authentication and scopes](https://brixsignage.com/developers/authentication/). ## Find Brix in Claude's connector directory Brix is listed in Claude's connector directory: [claude.ai/directory/connectors/brix](https://claude.ai/directory/connectors/brix). Example requests and what Claude can do: [Brix connector for Claude](https://brixsignage.com/claude/). 1. In Claude, go to **Customize > Connectors**, click **+** and search for Brix. Or open the listing link above. 2. Click **Connect**. 3. Claude opens a Brix page. Sign in, then pick the workspace, a location if you want to limit Claude to one, and the permission areas. Click **Allow**. This works in claude.ai, Claude Desktop and the Claude mobile apps, which share the same connectors. On a Team or Enterprise plan, an owner first adds Brix under **Organization settings > Connectors**, then each member connects it from **Customize > Connectors**. ## Add Brix by URL (ChatGPT plugin, Grok or Claude custom connector) Use these steps for ChatGPT and Grok, or in Claude if you prefer to add the endpoint yourself. 1. Copy the endpoint: `https://api.brixsignage.com/v1/mcp`. 2. Add it to the app. - **Claude:** **Customize > Connectors**, click **+**, then **Add custom connector**. Enter a name and the endpoint, then click **Add**. - **ChatGPT:** first turn on Developer mode under **Settings > Security and login** (your workspace policy can hide it). Then go to [chatgpt.com/plugins](https://chatgpt.com/plugins) and select **+**. Enter a name and description, paste the endpoint under **Connection**, and create it. - **Grok:** go to [grok.com/connectors](https://grok.com/connectors) and select **New Connector > Custom**. Enter a name and the endpoint, and add it. On Grok Business or Enterprise, a team admin must add the connector in the xAI console first. After that, each member connects it. 3. The app opens a Brix page. Sign in, then pick the workspace, a location if you want to limit the app to one, and the permission areas. Click **Allow**. 4. To check the connection, ask the app: "Which of my Brix screens are online?" It lists your screens. The app acts as you, with only the areas you picked. Viewing screens is always included, so if you pick no areas, the app can only view screens. You cannot give the app a permission you do not hold. Whatever areas you pick, an app connected by signing in cannot use billing, payment, invoice, API key or single sign-on routes. It can see people and roles, and it can invite a person, but only with a role that does not manage people, roles, API keys, settings or billing. It cannot change, remove or re-role a person, or edit a role. A person does these in the CMS. API keys are not affected. Every connection is listed in the CMS under **Settings > AI, API & MCP > Connected apps**, with who connected it and when it was last used. **Revoke** ends it at once: the app's next call is refused and it has to be connected again. For client developers: the server follows the MCP authorization spec. A call without a token gets `401` with a `WWW-Authenticate` header that points to the protected-resource metadata at `/.well-known/oauth-protected-resource/v1/mcp`. The authorization server is `https://api.brixsignage.com` (metadata at `/.well-known/oauth-authorization-server`). It supports authorization code with PKCE (S256), dynamic client registration and client ID metadata documents. Access tokens last an hour. Refresh tokens rotate on every use. An access token from this flow works only at `/v1/mcp`. ## API key clients ### 1. Create a key for the agent In the CMS: **Settings > AI, API & MCP > API keys > New key**. Give it only the areas the agent needs. For a first try, a view-only key (Screens, Playlists, Schedules, Files, Proof of Play) is safe: the agent can answer questions but cannot change what plays. The same page has a **Model Context Protocol (MCP)** section with the endpoint and **Copy config** and **Copy command** buttons. ### Claude Code ```bash claude mcp add --transport http brix https://api.brixsignage.com/v1/mcp \ --header "Authorization: Bearer $BRIX_API_KEY" ``` Then run `claude` and ask: "Which of my Brix screens are offline, and why?" Check the connection with `/mcp`. ### Claude Desktop To connect by signing in, connect Brix from Claude's connector directory (see above). To use a key instead: Claude Desktop's config file starts local (stdio) servers, so connect through the `mcp-remote` bridge. It needs Node.js. Open **Settings > Developer > Edit Config** and add: ```json { "mcpServers": { "brix": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.brixsignage.com/v1/mcp", "--header", "Authorization:${BRIX_AUTH}" ], "env": { "BRIX_AUTH": "Bearer ak_us_live_..." } } } } ``` Restart Claude Desktop. The header value goes through `env` because some platforms split arguments that contain spaces. ### Cursor Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "brix": { "url": "https://api.brixsignage.com/v1/mcp", "headers": { "Authorization": "Bearer ${env:BRIX_API_KEY}" } } } } ``` `${env:BRIX_API_KEY}` reads the key from your environment, so it stays out of the file. You can also paste the key in place of it. Open **Cursor Settings > MCP** to check that `brix` is connected. Other clients that accept a remote URL with custom headers use the same shape. This is the config that **Copy config** in the CMS gives you: ```json { "mcpServers": { "brix": { "url": "https://api.brixsignage.com/v1/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### OpenAI API The OpenAI Responses API sends your key in a header to a remote MCP server: ```bash curl https://api.openai.com/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5", "tools": [{ "type": "mcp", "server_label": "brix", "server_url": "https://api.brixsignage.com/v1/mcp", "headers": { "Authorization": "Bearer '"$BRIX_API_KEY"'" }, "require_approval": "never" }], "input": "Which of my screens are offline?" }' ``` `"require_approval": "never"` lets the model call tools without a pause. Use it with a view-only key, or set it to `"always"` and approve each call. ### Claude API The Messages API connects to remote MCP servers with the MCP connector: ```bash curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mcp-client-2025-11-20" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5", "max_tokens": 4096, "mcp_servers": [{ "type": "url", "name": "brix", "url": "https://api.brixsignage.com/v1/mcp", "authorization_token": "'"$BRIX_API_KEY"'" }], "tools": [{ "type": "mcp_toolset", "mcp_server_name": "brix" }], "messages": [{ "role": "user", "content": "Which of my screens are offline?" }] }' ``` ## Test the endpoint with curl ```bash curl https://api.brixsignage.com/v1/mcp \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_items","arguments":{"kind":"account"}}}' ``` A tool result comes back as a text block plus `structuredContent`. A failed tool call returns `isError: true` with the error text, so the agent can correct itself. ## How the tools behave - Start with `get_items` kind `account` in an unfamiliar workspace. It returns the key, the workspace and its permissions. - Every tool uses the same kind names. `list_items` finds ids by name; `get_items` reads items in full. Never guess an id. - `start_takeover` shows existing content for a limited time (default one hour) or fires a prepared emergency. To show a new announcement, make it first with `create_items` `creatives`, then pass its id to `start_takeover`. `set_screen_content` changes what a screen plays by default. - `create_items` adds items of one kind. It also uploads files you hold (up to 5 files, 6 MB each), copies files from public links (500 MB each) and pairs a device by its 6-digit code. - `update_items` changes one item or many with the same changes: playlist items, schedule blocks, screen group members, screen settings, a web link's crop or refresh. It also moves a screen to a new device (the new device's pairing code) and closes an alert by hand. `delete_items` moves items to the recycle bin; `restore_items` brings them back. - Tools never take sign-in values. A data feed that needs a sign-in or key (a POS, Stripe, Shopify, HubSpot, a private sheet) is connected by a person in the CMS under **Content > Data sources**, and tools then use it by its id. `create_items` makes the feeds that need no sign-in: a CSV URL, a Google Sheet published to anyone with the link, an iCal feed, a public transit stop or a public JSON URL. It refuses the rest and stores nothing. A stored sign-in value reads as `••••••••`; sending that back, or leaving it out, keeps what is stored. - **Repeat for each row** (beta, off until we turn it on for your workspace): one design and one data source play as a slideshow, one slide per row. `create_items` `creatives` and `update_items` take `dataSourceId` and `repeat: { over: "rows", secondsPerRow }` (3 to 3600 seconds, default 12); `repeat: null` turns it off. Without the feature, the call is refused with `403 feature_disabled` and nothing is saved. - Bind to the current row with `{{row.column}}` in a text box's `text`, `row.column` in a field box's `field`, and `{{row.photo}}` as an image box's `url`. A picture cell must be a plain https address. `{{rows.0.column}}` stays on the first row; `update_items` `useEachRow: true` moves those bindings to the current row, like **Use each row** in the CMS. - The column name is the sheet's header in lower case, with accents removed, every other character changed to `_`, repeats collapsed and none at the ends: `Date de début` is `row.date_de_debut`, `Région (€)` is `row.region`. - At most 200 rows and 3 MB of slides play, and each slide is a whole copy of the design, so a large design fits fewer rows. `get_items` returns `repeatStatus` on such a design: `rowCount`, `rowsThatFit`, `limitedBy`, `columns`, `missingColumns` and `warnings`. - `refresh_data` syncs the sheet. A sheet published to the web changes on Google's side up to about 5 minutes after an edit, so a sync straight after an edit can still read the old rows. - A Google Sheet published to anyone with the link works by tool. A sheet that needs a sign-in is connected by a person in the CMS, and tools then use it by its id. - Every client gets the same tools. An API key also gets `mint_upload_url` and `confirm_media_upload` for files over 6 MB. For anything without a tool, use the [REST API](https://brixsignage.com/developers/api/) with the same key. - Every tool declares MCP annotations: read-only, destructive, idempotent, and whether it reaches outside Brix. Clients use them to decide when to ask you first. - Content created over MCP lands as a draft where the location requires approval. - Changes made over MCP are recorded in the workspace audit log. Reads are not. ## Things to ask - "Which of my screens are offline, and why?" - "Why is the lobby screen blank? Show me what it's displaying right now." - "Put the Summer Menu playlist on every screen at the Downtown location for the next two hours." - "How many times did the Burger Promo play last week, and on which screens?" - "Give me this month's uptime report, worst screens first." Your AI app asks before it runs a tool that changes what a screen shows. ## Privacy, disconnecting and support - The app sees only what the tools return for the workspace, location and permission areas you approved. Brix does not receive your conversation with the app, only the tool calls it makes. - Disconnect any time in Brix under Settings > AI, API & MCP > Connected apps. Revoke ends the connection at once: the app's next call is refused. Removing the connector or plugin in the app stops the app using it. - A connection record is deleted 30 days after the connection ends (revoked, refresh token expired, or sign-in never completed). The audit log entries stay for the audit log's normal retention period. - Brix does not use data accessed through connected apps to train AI models. The app's provider handles what the app receives under its own terms. - How Brix handles data is in the [Privacy Policy](https://brixsignage.com/privacy#connected-ai-apps). For help, email [hello@brixsignage.com](mailto:hello@brixsignage.com). - To report a security problem, see [Reporting a vulnerability](https://brixsignage.com/security/#report). ## Tool catalog 17 tools. Each needs the permission shown on the API key. Read-only tools never change anything; the others say what they change. ### list_items List items of one kind with their ids, so other tools can act on them. When to use: - A request names a screen, file, playlist or location and you need its id. - Seeing what runs now (casts, emergencies), what is wrong now (alerts), approval requests, deleted items (recycle_bin), or who is in the workspace and what they may do (people, roles). When NOT to use: - Reading one item's contents: use get_items. - History over time: use get_fleet_report. What to know: - Rows are short (id, name, nodeId, counts), never configs or members; only locations this connection can see. people rows add each person's role at each location (never sign-in details); roles rows add their permissions. - A kind this connection cannot read is an error, not an empty list. people and roles are read-only here (invite with create_items); changing a person's access, roles, API keys and billing stays with a person in the Brix console. To see what this connection itself may do, use get_items kind account. - media, alerts and recycle_bin come newest first. Every call counts toward the connection's 30 tool calls a minute, so page with offset instead of re-listing. Parameters: - kind: the list to read; app_types and connectors are what create_items can make. A connectors row's setup is here (create_items makes it) or console (a person connects it in the Brix console, and it is then used by its id). - Filters (all optional, combined with AND, ignored on kinds they do not name): q (name contains, any kind but people and roles); status (screens online/offline/pairing; approvals pending by default, approved, rejected, withdrawn); nodeId (screens at that location and below; alerts at that location only); tag (screens, media); mediaKind and folderId (media); severity and screenId (alerts); binKind (recycle_bin). - limit: page size for media and approvals (default 50); other kinds give 100 a page. offset: pass nextOffset while hasMore. - Example: {kind:"screens", status:"offline", nodeId:"on_west"}. Permission: `the kind's view permission`. Behavior: read-only. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `kind` | screens \| media \| playlists \| schedules \| layouts \| creatives \| apps \| data_sources \| screen_groups \| locations \| media_folders \| emergency_templates \| casts \| emergencies \| alerts \| approvals \| recycle_bin \| app_types \| connectors \| people \| roles | yes | The collection to read. The tool description says what the less obvious kinds hold. | | `q` | string | no | Text that the item's name must contain. | | `status` | online \| offline \| pairing \| pending \| approved \| rejected \| withdrawn | no | Only screens in this connection state, or only approval requests in this review state. Left out, screens in every state are listed, and approval requests that still wait for a decision. | | `nodeId` | string | no | Only screens or alerts at this location. A location id comes from list_items kind locations. | | `tag` | string | no | Only screens or files that carry this tag, a label people put on them in the console. | | `mediaKind` | string | no | Only files of this type, for example image or video. | | `folderId` | string | no | Only files in this media folder. A folder id comes from list_items kind media_folders. | | `severity` | info \| warning \| critical | no | Only alerts of this urgency. | | `screenId` | string | no | Only alerts about this screen. A screen id comes from list_items kind screens. | | `binKind` | string | no | Only deleted items of this kind from the recycle bin. | | `limit` | integer | no | The page size for files and approval requests. Left out, a page holds 50 of them. Other kinds have a fixed page size. | | `offset` | integer | no | Where the page starts: the nextOffset value the previous page returned. | ### get_items Read items of one kind in full. When to use: - Before update_items, to see current values and part ids (playlist items pli_…, schedule blocks sb_…). - Checking how many rows of a sheet a repeating creative plays, and how many fit. - Checking an approval request, a fired emergency, a device test run, a person's locations and roles, a role's permissions, or who this connection is (kind account). When NOT to use: - Searching by name: use list_items first. - Why a screen is blank, its outages or its TV state: use get_screen_status (get_items returns a screen's settings and assigned content). What to know: - Returns a playlist's items in order, a schedule's blocks, a layout's zones, an app's config, a screen's status and content. - kind app_types, with app type keys from list_items as ids: each app's settings (key, kind, label, help, options with their values, default, required). create_items and update_items check an app's config against them. - A Now Serving or Goal Tracker app also returns staffLinks (controlUrl, staffCardUrl, takeNumberUrl), only when this connection may edit it. - A creative that repeats for each row also returns repeatStatus: rowCount and rowsThatFit (what the last sync holds and how many play), limitedBy (rows, bytes or null), loopSeconds, columns (each header and its row tag), missingColumns, firstRowBindings, lastSyncedAt and warnings to pass on. rowCount is null when this connection cannot read that data source. - Sign-in details of feeds and web links stay in the Brix console: a stored one reads as ••••••••. Items outside this connection's locations read as not found. Parameters: - kind: the kind of every id. account takes no ids and returns this connection's actor, workspace and permissions. - ids: prefix-typed ids from list_items (pl_… playlist, scr_… screen, sch_… schedule). Each id returns its item or not found; the rest still return. - device_test_runs: call again until status is finished. - Example: {kind:"playlists", ids:["pl_8f2c"]}. Permission: `the kind's view permission`. Behavior: read-only. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `kind` | screens \| media \| playlists \| schedules \| layouts \| creatives \| apps \| data_sources \| screen_groups \| locations \| media_folders \| emergency_templates \| approvals \| emergencies \| device_test_runs \| people \| roles \| account \| app_types | yes | The kind of item that every id names. | | `ids` | array | no | The items to read, by id. Ids come from list_items. | ### create_items Create new items of one kind. When to use: - Adding anything new, uploading files (media_files for bytes you hold, media_from_urls for public links), pairing a device by its code or inviting a person. When NOT to use: - Changing an existing item: use update_items. - Showing it on screens: create it, then use set_screen_content or start_takeover. What to know: - playlists, schedules, locations and creatives are all-or-nothing: one bad row rejects the call and names it (a location whose externalId exists is skipped, so imports re-run safely). Other kinds are created one by one; each reports ok or its error and the rest continue. - Returns each new item's id and name, to pass to the other tools, and each item that was not created with the reason. - New content at a location under review starts as a draft. Needs the kind's create permission there. - Tools never take sign-in values: a data_sources or apps item holding one, or a feed that cannot work without one, is refused and nothing is created. A person connects those in the Brix console; the feed is then used by its id. - Now Serving and Goal Tracker apps: leave out the control code (the server makes it). The result has staffLinks: controlUrl (the staff page that calls numbers), staffCardUrl (a card to print) and, when customers take numbers on their phones, takeNumberUrl. Give them to the staff only: anyone with controlUrl can change the number. The prompt set_up_now_serving walks the whole setup. - Repeat for each row (one slide per row of a sheet): the rules are in the repeat field's description. A workspace without the feature refuses it with 403 feature_disabled. Parameters: - Pass exactly one array; its name is the kind and two arrays is an error. - Ids inside items (refId, contentId, nodeId, screenId, appKey, connector) must already exist; get them from list_items. - Example: {playlists:[{name:"Lobby loop", items:[{refKind:"media", refId:"med_logo", durationSec:10}]}]}. Permission: `the kind's create permission`. Behavior: creates, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `playlists` | array | no | New playlists. A playlist plays its items in order and loops, on every screen it is assigned to. If one row is bad, nothing is created and the error names the row. | | `schedules` | array | no | New schedules. A schedule plays different content at different times of the day and week, on every screen it is assigned to. | | `locations` | array | no | New locations in the location tree (regions, stores, floors). List a parent before its children in the same call. A location whose externalId already exists is skipped, so an import can run again safely. | | `celebrations` | array | no | People for the celebrations app to celebrate on screens: birthdays, work anniversaries, retirements. | | `creatives` | array | no | New designs: layers of text, data fields, lists, images, shapes and slots on one canvas. If one row is bad, nothing is created and the error names the row. | | `screens` | array | no | Devices to pair into this workspace. Each device shows a pairing code on its screen until it is paired; the code is all it needs. | | `screen_groups` | array | no | New screen groups. A group gathers screens from any location under one label, so they can be targeted together. It grants no permissions. | | `web_links` | array | no | Live web pages or dashboards to add to the media library, to play like any file. Set crop, scroll and refresh later with update_items kind media. | | `media_from_urls` | array | no | Files (image, video, PDF, audio) to copy into the media library from public web addresses, up to 500 MB each. Copies land at the workspace root, so a connection limited to one location is refused. | | `media_files` | array | no | Files whose bytes you hold (an image you made, a file the person pasted), uploaded straight into the media library, up to 6 MB each. For a bigger file at a public address, use media_from_urls. | | `layouts` | array | no | New layouts that split the screen into zones. A new layout has one full-screen zone; set zones later with update_items (read a layout with get_items to copy its zone shape). | | `apps` | array | no | New app instances (weather, clock, menu board and others): an app type with its own settings, ready to play on screens. | | `data_sources` | array | no | Data feeds that need no sign-in: a CSV address, a Google Sheet published to anyone with the link, an iCal feed, a public transit stop, or a public JSON address. A feed that needs a sign-in or key (POS, Stripe, Shopify, HubSpot, a private sheet) is connected by a person in the Brix console and refused here; use it by its id from list_items kind data_sources. list_items kind connectors shows each type's setup. | | `media_folders` | array | no | New folders to sort the media library. | | `emergency_templates` | array | no | Saved emergency messages (Lockdown, Fire drill and others), ready to fire at once with start_takeover emergencyTemplateId. | | `people` | array | no | People to invite. Each one gets an email invitation; inviting someone who is already here adds the missing locations. Roles that manage people, roles, API keys, settings or billing are refused: a person gives those in the Brix console. | | `device_test_runs` | array | no | Device Lab test runs to start on screens. Each one queues at once; read its result with get_items kind device_test_runs. The suites content, soak, chaos and full change what the screen plays while they run, and chaos and full run only on internal or test-tagged screens. | ### update_items Change existing items of one kind, the same changes on every id. When to use: - Renaming, moving or retagging items; editing what is inside a playlist, schedule, layout or screen group; screen, web link and data feed settings; swapping a screen's device; closing an alert. - Turning Repeat for each row on, changing its seconds or turning it off on a creative (repeat, useEachRow). - Franchise menus: share a creative live with child workspaces (shareWithWorkspaces), and set one location's own prices on a creative shared to it (localText). When NOT to use: - Showing content on screens: use set_screen_content. - New items: use create_items. Removing: use delete_items. What to know: - Per id, changes run as steps in a fixed order and stop at that id's first failure; earlier steps stay and are named; other ids go on. Each id returns the item as it is now. - Content that airs where review is required goes back to draft. Needs the kind's edit permission (screen moves: at both locations). - Changes go live at once: every screen playing an edited playlist, schedule or layout shows the new version at its next sync. There is no undo; overwritten values and removed playlist items are gone, so note the old values with get_items first. - Repeat for each row (one slide per row of a sheet): the rules are in the repeat field's description. A workspace without the feature refuses it with 403 feature_disabled. Parameters: - kind and ids: every id must be of that kind; get them from list_items. Every id gets identical changes; for different values per item, call once per value. - changes: only the fields to change. Each field's description names the kinds that take it; a field the kind does not take is refused before anything changes. - zones, boxes, config and tags replace the whole value: read it with get_items first. - Example: {kind:"screens", ids:["scr_lobby7", "scr_lobby8"], changes:{nodeId:"on_store12", tags:["lobby"]}}. Permission: `the kind's edit permission`. Behavior: changes existing data, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `kind` | screens \| media \| playlists \| schedules \| layouts \| creatives \| apps \| data_sources \| screen_groups \| locations \| media_folders \| emergency_templates \| alerts | yes | The kind of item that every id names. | | `ids` | array | yes | The items to change, by id. Ids come from list_items. | | `changes` | object | yes | The fields to change and their new values. A field left out keeps its value. | ### delete_items Delete items of one kind into the 30-day recycle bin. When to use: - The person has confirmed what should go (show it with list_items or get_items first). When NOT to use: - Taking a screen out of a group: use update_items removeScreenIds. - Stopping a takeover: use end_takeover. What to know: - restore_items undoes a delete within 30 days. A deleted playlist or schedule stops on every screen playing it; a deleted screen's device returns to pairing; a deleted location hands its content to its parent. - Refused: the root, a location with child locations, items shared to another workspace. Each id reports ok or its error. Needs the kind's delete permission. Parameters: - kind and ids: every id must be of that kind. - permanent: true erases for good instead (recycle-bin kinds only). The first call deletes nothing and returns wouldErase and a confirmCode. - confirmCode: only with permanent:true; send the code from the first call, after the person says yes, with the same kind and ids. It lasts 10 minutes and fits only those ids; without permanent it is an error. - Example: {kind:"playlists", ids:["pl_8f2c"]}. Permission: `the kind's delete permission`. Behavior: changes existing data, idempotent, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `kind` | screens \| media \| playlists \| schedules \| layouts \| creatives \| apps \| data_sources \| screen_groups \| locations \| media_folders \| emergency_templates | yes | The kind of item that every id names. | | `ids` | array | yes | The items to delete, by id. Ids come from list_items. | | `permanent` | boolean | no | Erase the items for good and skip the recycle bin. This needs a second call with confirmCode. | | `confirmCode` | string | no | The code the first permanent call returned, sent back after the person agrees. | ### restore_items Bring back deleted items of one kind from the 30-day recycle bin. When to use: - Undoing delete_items. When NOT to use: - Items deleted more than 30 days ago: they are gone and report not found. What to know: - Whatever used a restored item (playlists, screens) uses it again; a restored screen re-pairs by itself if its device still holds its pairing. Each id reports ok or not found. Needs the kind's delete permission. Parameters: - kind: the list_items kind name, so a recycle_bin row of kind playlist is restored with kind playlists. - ids: up to 50, from list_items kind recycle_bin. An id that is not in the bin reports "not in the recycle bin"; one deleted over 30 days ago reports not found. - Example: {kind:"playlists", ids:["pl_8f2c"]}. Permission: `the kind's delete permission`. Behavior: creates, idempotent, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `kind` | screens \| media \| playlists \| schedules \| layouts \| creatives \| apps \| data_sources \| media_folders \| screen_groups | yes | The kind of item that every id names. | | `ids` | array | yes | The deleted items to bring back, by id. Ids come from list_items kind recycle_bin. | ### set_screen_content Set what screens play by default until it is changed again. When to use: - Putting a playlist, schedule, app, media file or creative on one screen, a list, or every screen under a location. When NOT to use: - A takeover that ends by itself: use start_takeover. - Changing what a playlist contains: use update_items (every screen playing it follows). What to know: - Screens update within seconds. In a bulk call, screens the content is not shared to or whose location needs approval for it are skipped and counted (notShared, needsApproval); the rest change. Needs screen.cast. Parameters: - screenId, screenIds and nodeId (every screen at and under it, up to 1000): give at least one; they combine into one set. - contentKind: playlist, schedule, app, media or creative. null clears what plays and needs exactly one screen and no nodeId. - contentId: the playlist, schedule, app, media or creative id from list_items; omit only with contentKind null. - Example: {nodeId:"on_ca", contentKind:"playlist", contentId:"pl_spring"}. Permission: `none`. Behavior: changes existing data, idempotent, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `screenId` | string | no | The one screen that gets the content. A screen id comes from list_items kind screens. | | `screenIds` | array | no | The screens that get the content, when there are several. Screen ids come from list_items kind screens. | | `nodeId` | string | no | A location: every screen at it and under it gets the content. A location id comes from list_items kind locations. | | `contentKind` | playlist \| schedule \| app \| media \| creative | yes | The kind of content that contentId names. A null value clears what one screen plays. | | `contentId` | string | no | The content to play, by id, from list_items of that kind. It must be of contentKind. Leave it out only to clear a screen, with contentKind null. | ### start_takeover Show something on screens over their normal content, now. When to use: - Existing content for a while (the lunch menu until 2 pm), or a pre-armed emergency. When NOT to use: - A lasting change: use set_screen_content. What to know: - Content ends by itself; an emergency stays above everything until end_takeover, so confirm its scope with the person first. Returns castId for end_takeover. Needs screen.cast. Parameters: - Pass exactly one of: contentId with contentKind (from list_items), or emergencyTemplateId (from list_items kind emergency_templates). - scopeKind: all (default, every screen this connection reaches), node with scopeNodeId, or screens with screenIds. An emergency ignores scope and uses its template's. - expiresAt: ISO 8601 with offset, default one hour from now. - Example: {contentKind:"playlist", contentId:"pl_lunch", scopeKind:"node", scopeNodeId:"on_store12", expiresAt:"2026-10-20T14:00:00-07:00"}. Permission: `screen.cast`. Behavior: changes existing data, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `contentKind` | media \| playlist \| app \| creative \| schedule | no | The kind of content that contentId names. | | `contentId` | string | no | The content to show during the takeover, by id, from list_items of that kind. | | `emergencyTemplateId` | string | no | A saved emergency message to fire, in place of contentKind and contentId. Ids come from list_items kind emergency_templates. | | `scopeKind` | all \| node \| screens | no | Which screens the takeover reaches: all of them, one location, or a list of screens. | | `scopeNodeId` | string | no | The location whose screens are taken over, with every location under it. A location id comes from list_items kind locations. | | `screenIds` | array | no | The screens that are taken over, when the scope is a list of screens. Screen ids come from list_items kind screens. | | `expiresAt` | string | no | The time the takeover ends and screens return to their normal content, as an ISO 8601 date and time with offset. Left out, it ends one hour after it starts. | | `headline` | string | no | A name for this takeover in lists of what runs now. Use it with contentId only. | ### end_takeover End a running takeover or emergency on every screen it covers, in one call. When to use: - Taking down what start_takeover started, early. When NOT to use: - Changing default content: use set_screen_content. - Calling once per screen: one call ends it everywhere. What to know: - Screens return to their normal content at once. Ending one that already ended succeeds with alreadyEnded:true; an unknown id fails and lists what is running. Needs screen.cast (emergency-override.create for an emergency). Parameters: - castId: the castId start_takeover returned, an emergency id (emg_…), the id of the content on screen, or the takeover's exact headline. The last two end every running takeover of it. Find running ones with list_items kind casts or emergencies. Permission: `screen.cast`. Behavior: changes existing data, idempotent, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `castId` | string | yes | The takeover to stop: the castId that start_takeover returned, or an id from list_items kind casts or emergencies. | ### get_screen_status Explain the state of one screen. When to use: - Why a screen shows what it shows, why it is blank or wrong, when it was down, or what its TV did. When NOT to use: - A screen's settings, tags or assigned content: use get_items kind screens. - Many screens: use get_fleet_report. A picture: use capture_screenshot. A fix: use control_screens. What to know: - Reads what the screen already reported and never contacts it, so it answers for offline screens. Needs screen.view. Parameters: - screenId: one scr_… id from list_items kind screens. - view: why (the source on screen: deactivated, emergency, takeover, schedule or default); diagnose (likely cause plus a checklist; guided:true marks a TV/input/cable guess, not a reading); outages (each outage with length and cause); tv (TV off, other input, cable lost; Signage Sticks only). - days: outages default 30; tv default and max 14. limit: default 50; max 200 for outages, 500 for tv. Both are ignored for why and diagnose. - Example: {screenId:"scr_lobby7", view:"outages", days:7}. Permission: `screen.view`. Behavior: read-only. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `screenId` | string | yes | The screen to explain. A screen id comes from list_items kind screens. | | `view` | why \| diagnose \| outages \| tv | yes | The question to answer about the screen. The tool description says what each view returns. | | `days` | number | no | How many days back the outage or TV history goes. Left out, outages go back 30 days and TV history 14. | | `limit` | number | no | A cap on the outage or TV history rows, newest first. Left out, 50 rows return. | ### capture_screenshot Take a new screenshot of one screen and return it as an image; nothing on the screen changes. When to use: - Checking what a screen shows, e.g. after set_screen_content or control_screens. When NOT to use: - Learning why: use get_screen_status. Polling in a loop. What to know: - Waits up to about 5 seconds; a slow or offline screen returns its last frame with fresh:false. A frame over 2 MB returns latestFrameUrl only. Needs screen.edit (it sends a device command). Parameters: - screenId: one scr_… id from list_items kind screens; for several screens, call once each. An id outside this connection's reach reads as not found and nothing is sent. Permission: `screen.edit`. Behavior: creates, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `screenId` | string | yes | The screen to take a picture of. A screen id comes from list_items kind screens. | ### control_screens Send a device action to one or many screens. When to use: - A change has not appeared, a screen is frozen, an old or broken file keeps playing, or the TV must go on or off. When NOT to use: - Changing content: use set_screen_content. New data from a feed or web page: use refresh_data. What to know: - Devices act within seconds; offline ones act when they come back. Check the result with capture_screenshot. Needs screen.edit. Parameters: - action: refresh (reload content, no restart; try first), reboot (restart; about a minute blank), clear_cache (delete stored files so they download again; media shows late meanwhile), tv_on or tv_off (HDMI-CEC TVs only; the player keeps running). - screenId and screenIds: give either or both; they combine into one set, each screen gets the action once, and screens out of reach are skipped. - Example: {action:"refresh", screenIds:["scr_7", "scr_8"]}. Permission: `screen.edit`. Behavior: changes existing data, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `action` | refresh \| reboot \| clear_cache \| tv_on \| tv_off | yes | What each device does. The tool description says what each action costs; start with the lightest one. | | `screenId` | string | no | The one screen that gets the action. A screen id comes from list_items kind screens. | | `screenIds` | array | no | The screens that get the action, when there are several. Screen ids come from list_items kind screens. | ### review_approval Approve, reject or withdraw one pending approval request. When to use: - This connection's person is an approver and a request is waiting (list_items kind approvals; read it with get_items kind approvals). - Cancelling a request that is no longer wanted, or one left behind by a person who has gone: withdraw. When NOT to use: - Editing the content: use update_items (an edit opens a new request). What to know: - approve airs the content where it is assigned, at once; reject keeps it off screens; withdraw closes the request with no decision and puts the content back to draft. Each is final. - approve and reject need this connection's person to be an approver in the request's chain; withdraw needs the requester or such an approver. Otherwise the call is refused. Parameters: - approvalId: an ar_… id from list_items kind approvals. - reason: required with reject and shown to the requester word for word; with approve, an optional note; ignored with withdraw. - Example: {approvalId:"ar_12", decision:"reject", reason:"Price on slide 2 is wrong."}. Permission: `an approver for the request`. Behavior: changes existing data, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `approvalId` | string | yes | The approval request to act on. Ids come from list_items kind approvals. | | `decision` | approve \| reject \| withdraw | yes | The outcome for the request. Each outcome is final. | | `reason` | string | no | A note for the person who asked. They see it with the decision. A rejection needs it; left out of an approval, the decision carries no note. | ### refresh_data Pull fresh content now instead of at the next scheduled refresh. When to use: - Before an announcement, so menus and prices are current; after someone edits a sheet that a creative repeats over; after changing a web link's crop with update_items, to see the result. When NOT to use: - Changing a feed's or link's settings: use update_items. A screen that has not picked up a change, or is frozen: use control_screens. What to know: - Settings never change. A failing feed is reported in the result, not thrown. Screens showing the data update when a sync succeeds. Needs integration.edit for feeds, media.edit for a web link. - A sheet published to the web changes on Google's side up to about 5 minutes after an edit, so a sync straight after an edit can still read the old rows: synced true says the sync ran, not that the edit arrived. Check rowCount with get_items and sync again after a few minutes if it is old. Parameters: - Pass exactly one; none or two is an error. - dataSourceId: one ds_… feed from list_items kind data_sources. - allDataSources: true syncs every feed you can edit, one after another; one failure does not stop the rest; limited to 5 calls a minute. - webLinkId: one med_… web link (list_items kind media, mediaKind web); renders a new snapshot. Permission: `integration.edit (media.edit for a web link)`. Behavior: creates, idempotent, reaches outside Brix. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `dataSourceId` | string | no | The data source to sync now. Ids come from list_items kind data_sources. | | `allDataSources` | boolean | no | Sync every data source in the workspace, in place of one id. | | `webLinkId` | string | no | The web link whose picture is taken again. Ids come from list_items kind media. | ### get_fleet_report Read a report across screens for a time window. When to use: - Uptime and outage causes, what actually played, or who changed what. When NOT to use: - One screen's detail: use get_screen_status. What is wrong now: use list_items kind alerts. What to know: - Reads stored history only; only screens this connection can see count. Needs screen.view (uptime), playback-log.view (proof_of_play) or audit-log.view (audit_log). Parameters: - report: uptime (online % per screen, outages with causes, worst first, one-line insights), proof_of_play (plays, watch time, skips and failures per content, and where) or audit_log (who changed what, newest first, by name). - from and to: uptime and proof_of_play only; ISO 8601; default the whole stored window (30 days for uptime) up to now; a non-ISO value is refused. screenId: uptime and proof_of_play only, one screen. screenIds, contentIds and detail: proof_of_play only. - since, limit (default 50) and cursor (nextCursor of the previous page): audit_log only. - Parameters for another report are ignored. Example: {report:"uptime", from:"2026-10-13T00:00:00Z"}. Permission: `per report`. Behavior: read-only. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `report` | uptime \| proof_of_play \| audit_log | yes | The report to read. The tool description says what each report holds. | | `from` | string | no | The start of the time window the report covers, as an ISO 8601 date and time. Left out, the window starts at the oldest stored history. | | `to` | string | no | The end of the time window the report covers, as an ISO 8601 date and time. Left out, the window ends now. | | `screenId` | string | no | Only this screen counts in the report. A screen id comes from list_items kind screens. | | `screenIds` | array | no | For proof of play: only plays on these screens count. Screen ids come from list_items kind screens. | | `contentIds` | array | no | For proof of play: only plays of these items count, for example one advertiser's ads. An id is the id of a file, playlist, app or creative from list_items of that kind. | | `detail` | screens | no | For proof of play: adds a breakdown with one row per content item and screen. Left out, the report has one row per content item. | | `since` | string | no | For the audit log: only events at or after this time, as an ISO 8601 date and time. Left out, the newest events come first with no start time. | | `limit` | integer | no | For the audit log: the page size. Left out, a page holds 50 events. | | `cursor` | string | no | Where the next page starts: the cursor value the previous page returned. | ### mint_upload_url Get a one-shot upload URL for a large file. The model's host PUTs bytes to it then calls confirm_media_upload with the same `uploadId`. Permission: `media.create`. Behavior: creates. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `contentType` | string | yes | MIME type of the file, e.g. video/mp4 or image/png. | | `name` | string | yes | Display name for the asset. | ### confirm_media_upload Finalize an upload after PUTting bytes to a mint_upload_url. Creates the media_assets row. Permission: `media.create`. Behavior: creates. | Argument | Type | Required | Description | | --- | --- | --- | --- | | `uploadId` | string | yes | The upl_… id that mint_upload_url returned. | | `folderId` | string | no | Library folder to file it in; omit for the library root. | | `tags` | array | no | Tags to set on the new asset. | ## Resources Read with `resources/read`. Each one checks its own view permission. - `brix://screens`: Every screen in the workspace, with status + location + assigned content. - `brix://playlists`: Playlists with their items (refKind/refId/duration), approval state and org node. - `brix://schedules`: Time-of-day schedules and which screens they target. - `brix://alerts/open`: Currently open alert events — anything offline / storage-critical / playback-failing. - `brix://org-tree`: The hierarchical org-node structure (Spaces / districts / schools / rooms). - `brix://media`: Images, videos, PDFs, web links and fonts — id, name, kind, folder, tags, state. - `brix://creatives`: Canvas creatives (data-bound designs) with stage + box count. - `brix://apps`: Installed app instances (weather, RSS, menus…) with their app key + node. - `brix://layouts`: Multi-zone layouts a screen can be pointed at, each with its `theme` (the Brand Kit look — { source: "brand", mode?, radius? } — or null for a bare canvas). Zone geometry, bindings and per-zone `frame` / `radius` / `role` come from GET /v1/layouts/:id. - `brix://data-sources`: Connected data feeds (CSV, Sheets, POS…) with connection + last-sync status. - `brix://screen-groups`: Named saved cohorts of screens — the unit for bulk commands and casts. - `brix://emergency-templates`: Pre-armed emergency takeover recipes; pass one's id to start_takeover as emergencyTemplateId. - `brix://approvals/pending`: Content awaiting an approve/reject decision before it can air. - `brix://screens/{screenId}/why`: The resolution chain (deactivated / emergency / cast / scheduled / default) for one screen. - `brix://playlists/{playlistId}`: One playlist WITH its ordered items. - `brix://media/{mediaId}/usage`: Where a media asset is used (playlists/creatives/layouts) and when it last played. ## Prompts - `fleet_health_report`: A daily ops digest: fleet status, open alerts, worst uptime offenders and what to do about each. - `diagnose_offline_screen`: Walk the likely-cause diagnosis for one screen and hand back a guided next-step checklist. Arguments: `screen_id` (optional). - `onboard_new_location`: Set up a new org location end-to-end: create the node, home its screens there and assign starter content. Arguments: `location_name`. - `weekly_content_review`: Proof-of-play rollup for the last 7 days: top content, skipped/failed plays, unused media worth pruning. - `set_up_now_serving`: Set up a Now Serving queue board end to end: the app with its counters, on a screen, and the staff link and card for the people who call numbers. Arguments: `business_name`, `counters` (optional). # Webhooks > Get a signed HTTPS POST when Brix content is recalled or restored. Create endpoints, verify the brix-signature HMAC, handle retries, and replay deliveries. For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path). Source: https://brixsignage.com/developers/webhooks/ A webhook endpoint receives a signed `POST` from Brix when an event happens in your workspace. Manage endpoints in the CMS at **Settings > Integrations > Webhooks**, or over the API. Managing webhooks needs `integration.view` and `integration.edit` at the workspace level. ## Events | Event | Sent when | `data` | | --- | --- | --- | | `content.recalled` | Someone pulls a file, design, playlist or schedule off every screen. | `kind` (`media`, `creative`, `playlist`, `schedule`), `id`, `name` (the kind's label, such as `Playlist`), `reason` (or null), `recalledBy` | | `content.restored` | Recalled content is put back. | `kind`, `id`, `name` | `GET /v1/webhooks/events` returns the full event catalog with a label and description for each. The catalog also names screen, approval and emergency events (`screen.offline`, `screen.online`, `approval.requested`, `approval.decided`, `emergency.started`, `emergency.cleared`). You can subscribe to them, but Brix does not send them. Only the two events above are delivered. ## Create an endpoint ```bash curl -X POST https://api.brixsignage.com/v1/webhooks \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/brix-hook", "events": ["content.recalled", "content.restored"], "description": "Ops channel"}' ``` The response is `201` with the endpoint (`id` starts with `whe_`) and its signing `secret`. The secret is shown once. Store it. An unknown event name returns `400`. | Call | What it does | | --- | --- | | `GET /v1/webhooks` | List endpoints. The secret is never included. | | `PATCH /v1/webhooks/{id}` | Change `url`, `events`, `description` or `enabled`. Re-enabling clears an auto-disable. | | `DELETE /v1/webhooks/{id}` | Delete an endpoint. Its pending deliveries stop. | | `POST /v1/webhooks/{id}/test` | Send a real signed delivery now. | | `GET /v1/webhooks/deliveries` | The delivery log, with payload, response and attempts. Paginated. Kept 30 days. | | `POST /v1/webhooks/deliveries/{id}/replay` | Send a delivery again as a new delivery. | The test delivery is a `screen.offline` event with `data.test: true` and a note that nothing is wrong. It returns `{ deliveryId, ok, status, error }`. If it returns `409 not_subscribed`, add `screen.offline` to the endpoint's events. ## The request Brix sends ``` POST /brix-hook HTTP/1.1 content-type: application/json user-agent: Brix-Webhooks/1 x-brix-event: content.recalled brix-signature: t=1790000000,v1=5f2b...c9 ``` ```json { "deliveryId": "whd_...", "event": "content.recalled", "occurredAt": "2026-01-15T14:03:22.000Z", "workspaceId": "...", "attempt": 1, "data": { "kind": "playlist", "id": "pl_...", "name": "Playlist", "reason": "Wrong prices", "recalledBy": "..." } } ``` - `deliveryId` stays the same across retries. Use it to ignore duplicates. - `occurredAt` is when the event happened, not when it was sent. - `attempt` counts delivery attempts, starting at 1. - A replay has a new `deliveryId` and a `replayOf` field with the original id. ## Verify the signature `brix-signature` is `t=,v1=`. The hex is HMAC-SHA256 of `.` with your endpoint secret. Check it against the raw body bytes, before you parse the JSON, and reject old timestamps. ```js import crypto from 'node:crypto'; export function verifyBrix(rawBody, header, secret, toleranceSec = 300) { const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.trim().split('=', 2))); const t = Number(parts.t); if (!Number.isFinite(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false; if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v1, 'hex')); } ``` ```python import hmac, hashlib, time def verify_brix(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool: parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p) try: t = int(parts["t"]) except (KeyError, ValueError): return False if abs(time.time() - t) > tolerance: return False expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, parts.get("v1", "")) ``` ## Delivery and retries - Delivery is at least once. Deduplicate on `deliveryId`. - Any `2xx` response is success. Redirects are not followed. Brix waits 10 seconds for a response. - A failed delivery is retried with backoff: 30 seconds, 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, then 4 hours between attempts. After the ninth attempt the delivery is abandoned. - After 9 failures in a row, Brix disables the endpoint and emails the workspace Owners. Fix the receiver, then set `enabled: true` again. - Reply fast and do the work after. A slow receiver risks the 10-second timeout and a duplicate. # API reference 480 operations. Base URL `https://api.brixsignage.com`. ## Account (part 1 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/account Get account overview Returns the workspace plan, subscription status, screen pool size, trial or paid status, and onboarding progress. **Notes.** - `email`, `emailVerifiedAt` and `verificationEmailLastSentAt` describe the CALLING user; they are null for an API key. - On a workspace created before the onboarding step existed, a null `prefs.onboardingCompletedAt` is filled with the workspace's creation time (and saved). Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Account | | | `data.scheduledScreenPool` | object \| null | A screen plan reduction queued for the renewal. | | `data.trialPlan` | object \| null | During a free trial billed by us: the plan that starts when the trial ends, charged to the saved card then. Null when none is set. | | `data.contract` | BillingTerm \| null | | | `data.id` | string | Workspace id (the account id support asks for). | | `data.partnerManaged` | boolean | A partner (white-label or reseller) manages this workspace. Its screens never show a corner mark, so the console hides the "Logo on screens" switch. | | `data.whiteLabel` | boolean | A partner bills this workspace; Brix billing does not apply. | | `data.freeAccess` | boolean | This workspace has free access (an external tester). There is no plan to choose and nothing is billed. | | `data.status` | "active" \| "cancel_scheduled" \| "paused" \| "past_due" \| "suspended" \| "cancelled" | | | `data.pauseUntil` | string \| null | | | `data.cancelEffectiveAt` | string \| null | | | `data.cancelReason` | "provider" \| "trial_expired" \| "voluntary" \| "nonpayment" \| null | | | `data.everPaid` | boolean | | | `data.deletionRequestedAt` | string \| null | | | `data.billingBanner` | BillingBanner \| null | | | `data.survey` | any | The last cancellation survey (`{ reason, competitor, returnLikelihood, comment }`), or null. | | `data.prefs` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.prefs.timeFormat` | "12h" \| "24h" | | | `data.prefs.weekStart` | "mon" \| "sun" | | | `data.prefs.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.prefs.tempUnits` | "f" \| "c" | | | `data.prefs.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.prefs.language` | string | BCP 47 language tag. | | `data.prefs.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.prefs.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.prefs.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.prefs.appBranding` | object | The look of the on-screen apps. | | `data.prefs.appBranding.accent` | string | | | `data.prefs.appBranding.accent2` | string | | | `data.prefs.appBranding.theme` | "dark" \| "light" | | | `data.prefs.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.appBranding.intensity` | number | | | `data.prefs.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.prefs.brandKits[].id` | string | | | `data.prefs.brandKits[].name` | string | | | `data.prefs.brandKits[].accent` | string | | | `data.prefs.brandKits[].accent2` | string | | | `data.prefs.brandKits[].theme` | "dark" \| "light" | | | `data.prefs.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.brandKits[].intensity` | number | | | `data.prefs.audio` | object | Default screen volume and a master mute. | | `data.prefs.audio.volume` | number | 0–100. | | `data.prefs.audio.muted` | boolean | | | `data.prefs.brand` | object | | | `data.prefs.brand.companyName` | string | | | `data.prefs.brand.logoUrl` | string | | | `data.prefs.requireAltText` | boolean | | | `data.prefs.showScreenLogo` | boolean | | | `data.prefs.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.prefs.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.prefs.standbyContentId` | string \| null | | | `data.prefs.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.prefs.industry` | string \| null | | | `data.prefs.onboardingCompletedAt` | string \| null | | | `data.prefs.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.prefs.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.prefs.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.prefs.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.prefs.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.prefs.orgNameSet` | boolean | | | `data.prefs.tiers` | array of integer | Location tree levels in use. | | `data.prefs.tierLabels` | object | Custom names for the location tree levels. | | `data.prefs.requireTwoFactor` | boolean | | | `data.prefs.requireSso` | boolean | | | `data.prefs.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.prefs.requireSsoPendingSince` | string \| null | | | `data.prefs.ai` | object | | | `data.prefs.ai.enabled` | boolean | | | `data.prefs.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.prefs.ai.dailyCallLimit` | integer \| null | | | `data.prefs.ai.redactPersonalData` | boolean | | | `data.prefs.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.prefs.retention.offline` | number | | | `data.prefs.retention.screenshots` | number | | | `data.prefs.retention.playback` | number | | | `data.prefs.retention.deviceLogs` | number | | | `data.prefs.retention.vitals` | number | | | `data.prefs.retention.replays` | number | | | `data.prefs.retention.aiEvents` | number | | | `data.prefs.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.prefs.warehouse.enabled` | boolean | | | `data.prefs.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.prefs.warehouse.tables` | array of string | | | `data.prefs.warehouse.lookbackDays` | integer | | | `data.prefs.supportAccess` | SupportAccessPolicy | | | `data.prefs.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.prefs.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.prefs.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.prefs.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | | `data.region` | "us" \| "eu" \| "oc" \| "apac" | Where the workspace's data is stored. | | `data.dbRegion` | "us" \| "eu" \| "oc" \| "apac" | Where the workspace's records are stored. Can differ from `region` for workspaces created before regional sign-up: media in the region, records on the primary. | | `data.billingProvider` | "chargebee" \| "brix" | `brix`: Brix invoices the account (see `payment`). `chargebee`: a card subscription. | | `data.payment` | AccountPayment \| null | Only when `billingProvider` is `brix`. | | `data.subscriptionStatus` | string \| null | | | `data.cadence` | "monthly" \| "annual" \| null | | | `data.billableScreens` | integer | Screens that count toward the bill now. | | `data.licensedScreens` | integer \| null | Screens bought (the plan quantity or the term's screens). | | `data.trialEndsAt` | string \| null | | | `data.nextBillingAt` | string \| null | | | `data.currentTermEndsAt` | string \| null | | | `data.emailVerifiedAt` | string \| null | The calling user's; null for an API key. | | `data.verificationEmailLastSentAt` | string \| null | | | `data.email` | string \| null | The calling user's email; null for an API key. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/about-you Answer the first-sign-in questions Records the answers a new workspace gives at its first sign-in: `screenCount`, the number of screens you expect (a whole number from 1 to 1,000,000, required), `heardFrom`, how you heard about Brix (required, except for a customer of a partner), and `phone`. A phone number is required only for a Google or Microsoft sign-up in the United States or Canada. Returns 422 with the field that is missing or not valid. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenCount` | integer | yes | How many screens the workspace expects. Sets `prefs.expectedScreens` and the tier. | | `heardFrom` | string | no | How they heard about Brix. Required unless the workspace belongs to a partner. | | `aiPrompt` | string | no | The question they asked an AI assistant, when `heardFrom` names one. | | `phone` | string | no | Required for a workspace in the US or Canada when the person has no phone on file (`phoneRequired` on GET /v1/account/onboarding); optional elsewhere and in a partner's customer workspace. US and Canada numbers get the North-American checks. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/about-you" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.prefs` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.prefs.timeFormat` | "12h" \| "24h" | | | `data.prefs.weekStart` | "mon" \| "sun" | | | `data.prefs.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.prefs.tempUnits` | "f" \| "c" | | | `data.prefs.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.prefs.language` | string | BCP 47 language tag. | | `data.prefs.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.prefs.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.prefs.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.prefs.appBranding` | object | The look of the on-screen apps. | | `data.prefs.appBranding.accent` | string | | | `data.prefs.appBranding.accent2` | string | | | `data.prefs.appBranding.theme` | "dark" \| "light" | | | `data.prefs.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.appBranding.intensity` | number | | | `data.prefs.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.prefs.brandKits[].id` | string | | | `data.prefs.brandKits[].name` | string | | | `data.prefs.brandKits[].accent` | string | | | `data.prefs.brandKits[].accent2` | string | | | `data.prefs.brandKits[].theme` | "dark" \| "light" | | | `data.prefs.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.brandKits[].intensity` | number | | | `data.prefs.audio` | object | Default screen volume and a master mute. | | `data.prefs.audio.volume` | number | 0–100. | | `data.prefs.audio.muted` | boolean | | | `data.prefs.brand` | object | | | `data.prefs.brand.companyName` | string | | | `data.prefs.brand.logoUrl` | string | | | `data.prefs.requireAltText` | boolean | | | `data.prefs.showScreenLogo` | boolean | | | `data.prefs.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.prefs.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.prefs.standbyContentId` | string \| null | | | `data.prefs.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.prefs.industry` | string \| null | | | `data.prefs.onboardingCompletedAt` | string \| null | | | `data.prefs.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.prefs.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.prefs.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.prefs.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.prefs.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.prefs.orgNameSet` | boolean | | | `data.prefs.tiers` | array of integer | Location tree levels in use. | | `data.prefs.tierLabels` | object | Custom names for the location tree levels. | | `data.prefs.requireTwoFactor` | boolean | | | `data.prefs.requireSso` | boolean | | | `data.prefs.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.prefs.requireSsoPendingSince` | string \| null | | | `data.prefs.ai` | object | | | `data.prefs.ai.enabled` | boolean | | | `data.prefs.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.prefs.ai.dailyCallLimit` | integer \| null | | | `data.prefs.ai.redactPersonalData` | boolean | | | `data.prefs.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.prefs.retention.offline` | number | | | `data.prefs.retention.screenshots` | number | | | `data.prefs.retention.playback` | number | | | `data.prefs.retention.deviceLogs` | number | | | `data.prefs.retention.vitals` | number | | | `data.prefs.retention.replays` | number | | | `data.prefs.retention.aiEvents` | number | | | `data.prefs.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.prefs.warehouse.enabled` | boolean | | | `data.prefs.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.prefs.warehouse.tables` | array of string | | | `data.prefs.warehouse.lookbackDays` | integer | | | `data.prefs.supportAccess` | SupportAccessPolicy | | | `data.prefs.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.prefs.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.prefs.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.prefs.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 422: `screen_count_required`, `heard_from_required`, `phone_required` or `phone_invalid`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/billing-address Get billing address Returns the billing address on file with the billing provider: the country used to determine invoice tax, and, for the United States and Canada, the state and postal code. The response includes `configured: false` when no billing address has been set yet. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account/billing-address" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/billing-address Set billing address Sets the workspace billing address. `country` is required and validated against the ISO 3166-1 country list. For the United States and Canada, `stateCode` and `zip` are also required. This replaces the entire address on file; you cannot update a single field. **Notes.** - Answers 400 (not 422) for an invalid address, unlike most validation errors. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `country` | string | yes | Country code or name. | | `stateCode` | string | no | Required for US and Canada. Stored in upper case. | | `zip` | string | no | Required for US and Canada. | | `city` | string | no | | | `line1` | string | no | | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/billing-address" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.configured` | true | | | `data.address` | object | | | `data.address.country` | string \| null | ISO 3166-1 alpha-2. | | `data.address.stateCode` | string \| null | State or province, without the country prefix (`CA`, `ON`). | | `data.address.zip` | string \| null | | | `data.address.city` | string \| null | | | `data.address.line1` | string \| null | | | `data.needsState` | boolean | | Response 400: `invalid_country` or `state_required` (400, not 422). Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_customer`: billing is not set up yet. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/billing-mode Switch billing mode Switches the workspace between automatic card charging (`auto`) and invoice billing (`invoice`). Switching to invoice billing requires a signed-in user with a verified work email address, so an API key can only switch to automatic charging. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `mode` | "auto" \| "invoice" | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/billing-mode" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.mode` | "auto" \| "invoice" | | Response 401: Missing, expired or revoked bearer token. Response 403: `user_required`: switching to `invoice` needs a signed-in user with a verified work email, so an API key can switch only to `auto`. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `email_unverified`, `work_email_required`, `billing_not_configured`, or `under_contract`. Response 422: `mode` is not `auto` or `invoice`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/brix-plan Choose a plan Starts a monthly or yearly plan for a workspace billed directly by Brix. Needs a saved card. The first period is charged to the card now; if the payment fails, nothing is created and the response is 402. The plan renews on its end date until it is cancelled. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `cadence` | "monthly" \| "annual" | yes | | | `screens` | integer | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/brix-plan" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). | | `data.contract.id` | string | | | `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" | | | `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). | | `data.contract.activateOn` | "now" \| "paid" | | | `data.contract.poNumber` | string \| null | | | `data.contract.invoiceNumber` | string \| null | | | `data.contract.invoicePaid` | boolean \| null | | | `data.contract.activatedAt` | string \| null | | | `data.contract.screens` | integer | | | `data.contract.rateCentsPerScreenMonth` | integer | | | `data.contract.termMonths` | integer | | | `data.contract.schedule` | "upfront" \| "monthly" \| "annual" | | | `data.contract.collect` | "card" \| "invoice" | | | `data.contract.currency` | string | | | `data.contract.startsAt` | string | Date (YYYY-MM-DD). | | `data.contract.endsAt` | string | Date (YYYY-MM-DD). | | `data.contract.totalCents` | integer | | | `data.contract.monthlyCents` | integer | | | `data.contract.termLabel` | string | | | `data.contract.scheduleLabel` | string | | | `data.contract.invoiceId` | string \| null | | | `data.contract.notes` | string \| null | | | `data.contract.createdBy` | string \| null | | | `data.contract.prior` | object \| null | The plan before the term started. | | `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.contract.endedAt` | string \| null | | | `data.contract.renewal` | "renew" \| "non_renewing" | | | `data.contract.renewalInvoiceId` | string \| null | | | `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. | | `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. | | `data.invoiceNumber` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 402: `card_declined` — the first payment failed. Nothing was created. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, `card_required`, `already_on_plan`, or `payment_required`. Response 422: Bad `cadence` or `screens`. Response 503: `price_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/brix-plan/cadence Switch plan cadence Switches the plan between monthly and yearly. The switch takes effect when the current period ends, at the list price of the new cadence. **Notes.** - The switch takes effect when the current period ends. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `cadence` | "monthly" \| "annual" | yes | | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/cadence" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). | | `data.contract.id` | string | | | `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" | | | `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). | | `data.contract.activateOn` | "now" \| "paid" | | | `data.contract.poNumber` | string \| null | | | `data.contract.invoiceNumber` | string \| null | | | `data.contract.invoicePaid` | boolean \| null | | | `data.contract.activatedAt` | string \| null | | | `data.contract.screens` | integer | | | `data.contract.rateCentsPerScreenMonth` | integer | | | `data.contract.termMonths` | integer | | | `data.contract.schedule` | "upfront" \| "monthly" \| "annual" | | | `data.contract.collect` | "card" \| "invoice" | | | `data.contract.currency` | string | | | `data.contract.startsAt` | string | Date (YYYY-MM-DD). | | `data.contract.endsAt` | string | Date (YYYY-MM-DD). | | `data.contract.totalCents` | integer | | | `data.contract.monthlyCents` | integer | | | `data.contract.termLabel` | string | | | `data.contract.scheduleLabel` | string | | | `data.contract.invoiceId` | string \| null | | | `data.contract.notes` | string \| null | | | `data.contract.createdBy` | string \| null | | | `data.contract.prior` | object \| null | The plan before the term started. | | `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.contract.endedAt` | string \| null | | | `data.contract.renewal` | "renew" \| "non_renewing" | | | `data.contract.renewalInvoiceId` | string \| null | | | `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. | | `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. | | `data.changed` | boolean | | | `data.effectiveAt` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed` or `no_plan`. Response 422: Bad `cadence`. Response 503: `price_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/brix-plan/playing List screens on the plan Lists every screen on the plan in the order it was paired. Each screen shows if it plays or waits for payment. Also returns the number of screens the plan pays for. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/account/brix-plan/playing" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.capacity` | integer \| null | | | `data.screens` | array of object | | | `data.screens[].id` | string | | | `data.screens[].name` | string | | | `data.screens[].status` | string | | | `data.screens[].lastSeenAt` | string \| null | | | `data.screens[].waiting` | boolean | | | `data.canChoose` | boolean | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: A workspace billed by a partner. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/brix-plan/playing Choose which screens play When you have more screens than your plan pays for, choose which screens play. Send exactly as many screens as the plan has. The other screens wait for payment. Nothing is charged. **Notes.** - The other screens wait for payment. Nothing is charged. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | yes | | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/playing" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.playing` | array of string | | | `data.waiting` | array of string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: `screen_not_found`, or a workspace billed by a partner. Response 409: `not_brix_billed` or `no_plan`. Response 422: `wrong_count` — choose exactly as many as the plan has. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/brix-plan/pool Get plan screen counts For a workspace billed directly by Brix, returns how many screens the plan pays for, how many play, how many wait for payment, the price of one more screen today, and an open request for more screens. The saved card is shown only to a caller who can edit billing. Returns `pool: null` for a workspace that is not billed directly by Brix. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/account/brix-plan/pool" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/brix-plan/quote Quote a plan Returns the list price of a monthly or yearly plan for a screen count, for a workspace billed directly by Brix. Nothing is charged. Returns 409 for a workspace that is not billed directly by Brix. Auth: Bearer token. Permission: `billing.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `cadence` | query | "monthly" \| "annual" | yes | | | `screens` | query | integer | yes | | ```bash curl "https://api.brixsignage.com/v1/account/brix-plan/quote" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | BrixPlanQuote | The price of a plan on Brix's own billing, before anything is charged. | | `data.cadence` | "monthly" \| "annual" | | | `data.screens` | integer | | | `data.rateCentsPerScreenMonth` | integer | | | `data.termMonths` | integer | | | `data.schedule` | "monthly" \| "annual" | | | `data.startsAt` | string | | | `data.endsAt` | string | | | `data.monthlyCents` | integer | | | `data.totalCents` | integer | What the first payment is for. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`. Response 422: Bad `cadence` or `screens`. Response 503: `price_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/brix-plan/screens Change plan screens Sets the screen count of the plan. More screens are invoiced now, prorated to the days left in the period, and charged to the saved card. Fewer screens start at the next period and nothing is refunded. The count cannot go below the screens that are running. **Notes.** - More screens are charged now, prorated to the days left in the period. Fewer screens start at the next period; nothing is refunded. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screens` | integer | yes | | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/screens" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.effect` | "now" \| "renewal" \| "unchanged" | | | `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). | | `data.contract.id` | string | | | `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" | | | `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). | | `data.contract.activateOn` | "now" \| "paid" | | | `data.contract.poNumber` | string \| null | | | `data.contract.invoiceNumber` | string \| null | | | `data.contract.invoicePaid` | boolean \| null | | | `data.contract.activatedAt` | string \| null | | | `data.contract.screens` | integer | | | `data.contract.rateCentsPerScreenMonth` | integer | | | `data.contract.termMonths` | integer | | | `data.contract.schedule` | "upfront" \| "monthly" \| "annual" | | | `data.contract.collect` | "card" \| "invoice" | | | `data.contract.currency` | string | | | `data.contract.startsAt` | string | Date (YYYY-MM-DD). | | `data.contract.endsAt` | string | Date (YYYY-MM-DD). | | `data.contract.totalCents` | integer | | | `data.contract.monthlyCents` | integer | | | `data.contract.termLabel` | string | | | `data.contract.scheduleLabel` | string | | | `data.contract.invoiceId` | string \| null | | | `data.contract.notes` | string \| null | | | `data.contract.createdBy` | string \| null | | | `data.contract.prior` | object \| null | The plan before the term started. | | `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.contract.endedAt` | string \| null | | | `data.contract.renewal` | "renew" \| "non_renewing" | | | `data.contract.renewalInvoiceId` | string \| null | | | `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. | | `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. | | `data.chargedCents` | integer | | | `data.carriedCents` | integer | | | `data.invoiceNumber` | string \| null | | | `data.collect` | "card" \| "next_invoice" \| "invoice" | How the added screens were collected. `invoice`: an invoice went out by email and no card was charged. | | `data.dueAt` | string \| null | When the invoice, or the amount added to the next invoice, is due. | | `data.audit` | string | | Response 401: Missing, expired or revoked bearer token. Response 402: `card_declined` — the extra screens were not added. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, `no_plan`, `below_running`, `card_required`, `payment_pending`, or `payment_required`. Response 422: Bad `screens`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/brix-plan/screens/estimate Price a screen change Returns what a new screen count costs today. More screens are charged now, prorated to the days left in the period. Fewer screens start at the next period. Nothing is changed. Auth: Bearer token. Permission: `billing.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screens` | integer | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/brix-plan/screens/estimate" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.currentScreens` | integer | | | `data.screens` | integer | | | `data.effect` | "now" \| "renewal" \| "unchanged" | | | `data.chargeCents` | integer | | | `data.periodEnds` | string | | | `data.collect` | "card" \| "next_invoice" \| "invoice" \| null | How `chargeCents` is collected. `card`: charged to the saved card now. `next_invoice`: added to the next invoice. `invoice`: the account pays by invoice, so an invoice goes out by email and no card is charged. Null when nothing is due now. | | `data.needsCard` | boolean | True when the account pays by card and no card is saved. The change is refused until a card is saved. | | `data.dueAt` | string \| null | When the invoice, or the amount added to the next invoice, is due. Null for a card charge. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed` or `no_plan`. Response 422: Bad `screens`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Account (part 2 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/account/brix-plan/screens/request Request more screens Asks for more screens on the plan without billing access. Send `add`, the number of screens, and optionally `sendTo`, an email address that gets the invoice (for example, accounts payable). Without `sendTo`, the invoice goes to the billing contacts of the account. Returns the request with its payment link. Nothing is charged until the invoice is paid. Connected apps cannot make this request. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/account/brix-plan/screens/request" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/brix-plan/trial-plan Set the plan for the trial's end During a free trial, sets the plan that starts when the trial ends. The plan uses the list price. We charge the saved card when the trial ends. Nothing is charged now. **Notes.** - Nothing is charged now. The plan starts when the trial ends, charged to the saved card. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `cadence` | "monthly" \| "annual" | yes | | | `screens` | integer | yes | | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/brix-plan/trial-plan" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.trialPlan` | object | | | `data.trialPlan.cadence` | "monthly" \| "annual" | | | `data.trialPlan.screens` | integer | | | `data.trialPlan.rateCentsPerScreenMonth` | integer | | | `data.trialPlan.totalCents` | integer | What the trial's end charges: the whole first period. | | `data.trialPlan.from` | "chargebee" \| "customer" | | | `data.trialPlan.startsAt` | string \| null | When it is charged: the trial's end. On `GET /v1/account` only. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, `not_in_trial`, `already_on_plan` or `card_required`. Response 422: Bad `cadence` or `screens`. Response 503: `price_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/account/brix-plan/trial-plan Remove the plan for the trial's end Removes the plan that was set for the end of the free trial. Nothing is charged when the trial ends, and the screens stop when the trial ends. **Notes.** - Nothing is charged when the trial ends. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X DELETE "https://api.brixsignage.com/v1/account/brix-plan/trial-plan" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.trialPlan` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/cancel Cancel subscription Submits a cancellation request with a reason. Choosing the reason "Seasonal Business" together with a `restartDate` pauses the account instead of cancelling it. Any other reason schedules cancellation for a fixed number of days after the request. Cancellation can be reversed at any time before it takes effect by calling the reactivate operation. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `reason` | string | yes | Survey answer. `Seasonal Business` pauses the account instead of cancelling it. | | `restartDate` | string | no | Required for `Seasonal Business`: when the account comes back (future, at most 12 months). | | `competitor` | string | no | | | `returnLikelihood` | number | no | | | `comment` | string | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/cancel" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such workspace. Response 409: `payment_required` (unpaid invoice), `already_cancelled`, `under_contract` (an agreed term; contact Brix), or `location_plans_active` (a seasonal pause while a location has its own plan; contact Brix). A cancel schedules each location's own plan to end on the same date. Response 422: `reason` missing, or a bad `restartDate`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/cancel-deletion Cancel pending account deletion Stops a scheduled permanent deletion of the workspace before it happens. Call this any time before the deletion date to keep the account and its data. **Notes.** - The account stays `cancelled`; reactivate it separately. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/cancel-deletion" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.status` | "active" \| "cancel_scheduled" \| "paused" \| "past_due" \| "suspended" \| "cancelled" | | | `data.deletionRequestedAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `not_pending_deletion`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/content-scope Get the default content scope Read what people in this workspace can see when neither they nor their role has a setting of their own: `all` for all content, or `shared` for only content shared with them. Auth: Bearer token. Permission: `user.view`. ```bash curl "https://api.brixsignage.com/v1/account/content-scope" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/content-scope Set the default content scope Set the default for people with no setting of their own to `all` or `shared`. People already in the workspace keep what they see today: anyone who would change has their current value saved on their own account first. A connected app cannot call this. Auth: Bearer token. ```bash curl -X PUT "https://api.brixsignage.com/v1/account/content-scope" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/contract/renewal Set contract auto-renewal Sets whether the workspace's current contract term renews automatically or ends at term expiry. Choosing not to renew voids any unpaid renewal invoice; choosing to renew allows Brix to invoice the next term automatically. Returns 409 if the workspace has no fixed term, and 404 for white-label workspaces, where this setting does not apply. **Notes.** - Turning auto-renew off voids an unpaid renewal invoice. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `renewal` | "renew" \| "non_renewing" | yes | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/contract/renewal" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.contract` | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). | | `data.contract.id` | string | | | `data.contract.status` | "active" \| "cancelled" \| "awaiting_payment" \| "ended" | | | `data.contract.rail` | "chargebee" \| "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). | | `data.contract.activateOn` | "now" \| "paid" | | | `data.contract.poNumber` | string \| null | | | `data.contract.invoiceNumber` | string \| null | | | `data.contract.invoicePaid` | boolean \| null | | | `data.contract.activatedAt` | string \| null | | | `data.contract.screens` | integer | | | `data.contract.rateCentsPerScreenMonth` | integer | | | `data.contract.termMonths` | integer | | | `data.contract.schedule` | "upfront" \| "monthly" \| "annual" | | | `data.contract.collect` | "card" \| "invoice" | | | `data.contract.currency` | string | | | `data.contract.startsAt` | string | Date (YYYY-MM-DD). | | `data.contract.endsAt` | string | Date (YYYY-MM-DD). | | `data.contract.totalCents` | integer | | | `data.contract.monthlyCents` | integer | | | `data.contract.termLabel` | string | | | `data.contract.scheduleLabel` | string | | | `data.contract.invoiceId` | string \| null | | | `data.contract.notes` | string \| null | | | `data.contract.createdBy` | string \| null | | | `data.contract.prior` | object \| null | The plan before the term started. | | `data.contract.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.contract.endedAt` | string \| null | | | `data.contract.renewal` | "renew" \| "non_renewing" | | | `data.contract.renewalInvoiceId` | string \| null | | | `data.contract.origin` | "staff" \| "self_serve" | `self_serve` — the customer chose this plan on the Billing page; `staff` — an agreed term set by Brix. | | `data.contract.next` | object \| null | What the next period starts with, when the customer asked for a change at renewal. | | `data.changed` | boolean | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `no_term` (no agreed term), or a term that cannot change here. Response 422: `renewal` is not `renew` or `non_renewing`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/data-inventory Get data inventory Returns, for every category of data Brix holds about the workspace, what it is, whether it identifies a person, how long it is kept, whether it is included in a data export, and whether it is deleted when the account is closed. Pass `?counts=1` to include a row count for each category. Auth: Bearer token. Permission: `settings.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `counts` | query | "1" | no | `1` adds a row count per table (slower). | ```bash curl "https://api.brixsignage.com/v1/account/data-inventory" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.generatedAt` | string | ISO-8601 timestamp (UTC). | | `data.counted` | boolean | | | `data.categories` | array of object | | | `data.categories[].id` | string | | | `data.categories[].label` | string | | | `data.categories[].what` | string | | | `data.categories[].personal` | string | | | `data.categories[].retention` | string | | | `data.categories[].rows` | integer \| null | | | `data.categories[].tables` | array of object | | | `data.categories[].tables[].table` | string | | | `data.categories[].tables[].rows` | integer \| null | | | `data.categories[].tables[].inExport` | boolean | | | `data.categories[].tables[].exportNote` | string \| null | | | `data.categories[].tables[].erasedOnClose` | boolean | | | `data.categories[].tables[].retainedNote` | string \| null | | | `data.categories[].tables[].strippedFields` | array of string | | | `data.residency` | object \| null | Where the workspace's data is stored. `database`, `media` and `backups` are internal store names. | | `data.notes` | array of string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/downgrade-monthly Switch to monthly billing Switches the workspace from annual to monthly billing at the end of the current annual term. Nothing is charged or refunded now. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/downgrade-monthly" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.cadence` | "annual" | Unchanged until the annual term ends. | | `data.scheduledCadence` | "monthly" | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_subscription`, `already_monthly`, or `under_contract`. Response 502: The switch could not be scheduled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/encryption-key Get encryption key status Returns whether the workspace can use its own encryption key in Azure Key Vault, what that key covers, its identifier, its status, and the progress of re-encrypting existing data under it. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/account/encryption-key" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.available` | boolean | Customer-managed keys can be used on this platform. | | `data.consentUrl` | string \| null | Microsoft admin-consent link for the Key Vault application. A tenant administrator opens it once; null when customer-managed keys are not available. | | `data.covers` | string | | | `data.doesNotCover` | string | | | `data.key` | object \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/account/encryption-key Enable customer-managed key Enables encryption with the workspace's own key in Azure Key Vault. Brix verifies the key, generates and wraps a data key, and starts re-encrypting existing secrets under it. Every new secret created after this call is protected with the customer's key. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `tenantId` | string | yes | Your Microsoft Entra tenant id (a UUID). | | `keyId` | string | yes | `https://.vault.azure.net/keys//`. | ```bash curl -X PUT "https://api.brixsignage.com/v1/account/encryption-key" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.available` | boolean | Customer-managed keys can be used on this platform. | | `data.consentUrl` | string \| null | Microsoft admin-consent link for the Key Vault application. A tenant administrator opens it once; null when customer-managed keys are not available. | | `data.covers` | string | | | `data.doesNotCover` | string | | | `data.key` | object \| null | | | `data.firstPass` | object | The first re-encryption pass, run inside the request; the rest runs hourly. | | `data.firstPass.status` | string | | | `data.firstPass.remaining` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `conflict` (a key is already set; turn it off first) or `key_check_failed`. Response 422: Bad `tenantId` or `keyId`. Response 503: `not_available` on this platform. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/account/encryption-key Disable customer-managed key Disables the workspace's customer-managed encryption key. Every secret currently protected by that key is first moved back under the Brix-managed key, so nothing becomes unreadable, and only then is the key record removed. Returns 409 if the customer-managed key can no longer be reached. **Notes.** - `key` is null when the first pass moved every secret back; otherwise it shows `disabling` until the hourly pass finishes. Auth: Bearer token. Permission: `settings.edit`. ```bash curl -X DELETE "https://api.brixsignage.com/v1/account/encryption-key" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.available` | boolean | Customer-managed keys can be used on this platform. | | `data.consentUrl` | string \| null | Microsoft admin-consent link for the Key Vault application. A tenant administrator opens it once; null when customer-managed keys are not available. | | `data.covers` | string | | | `data.doesNotCover` | string | | | `data.key` | object \| null | | | `data.firstPass` | object | The first re-encryption pass, run inside the request; the rest runs hourly. | | `data.firstPass.status` | string | | | `data.firstPass.remaining` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No key is set. Response 409: `key_unavailable`: the vault did not answer, so secrets cannot be moved back. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/encryption-key/verify Verify encryption key Performs a dry run against the workspace's own encryption key: it wraps and unwraps a random test value to confirm the key still works. Nothing is stored or changed. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `tenantId` | string | yes | Your Microsoft Entra tenant id (a UUID). | | `keyId` | string | yes | `https://.vault.azure.net/keys//`. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/encryption-key/verify" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `key_check_failed`: the vault refused (`kind` says why). Response 422: Bad `tenantId` or `keyId`. Response 503: `not_available` on this platform. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/export Download full data export Returns a data export of the workspace as one downloadable file: the workspace record, its members, nine content tables and the last 365 days of activity-log events. Credentials are never included. Because the file holds every member's personal data, it requires permission to export billing data (`billing.export`) for the whole workspace. Permission to edit billing is not enough. Brix does not email or store the export. For every table and the complete activity log, use the export manifest and its parts. **Notes.** - No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`). - Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker. - `generatedBy.kind` is `user` even when an API key made the export (and then `userId` is absent). - The complete export (every table, the whole audit log) is `GET /v1/account/export/manifest` and its parts. Auth: Bearer token. Permission: `billing.export`. ```bash curl "https://api.brixsignage.com/v1/account/export" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `schemaVersion` | 1 | | | `generatedAt` | string | ISO-8601 timestamp (UTC). | | `generatedBy` | object | Always `user`; `userId` is absent for an API key. | | `generatedBy.kind` | "user" | | | `generatedBy.userId` | string | | | `workspace` | object | The workspace record (every column; the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`). | | `people` | array of object | | | `people[].id` | string | | | `people[].name` | string | | | `people[].email` | string | | | `people[].status` | string | | | `people[].lastLoginAt` | string \| null | | | `people[].createdAt` | string | ISO-8601 timestamp (UTC). | | `content` | object | Nine content tables, one object per row (all columns). | | `content.screens` | array of object | | | `content.mediaAssets` | array of object | | | `content.playlists` | array of object | | | `content.schedules` | array of object | | | `content.layouts` | array of object | | | `content.creatives` | array of object | | | `content.appInstances` | array of object | | | `content.dataSources` | array of object | | | `content.banners` | array of object | | | `auditEvents` | array of object | The last 365 days only. | | `limits` | object | | | `limits.auditEvents` | string | | | `limits.completeness` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/export/manifest Get export manifest Describes the contents of a full data export without downloading it: every table of workspace data with its row count, which tables are excluded from the export and why, and which fields are redacted and why. Use this to confirm what an export will and will not contain before downloading it. Auth: Bearer token. Permission: `billing.export`. ```bash curl "https://api.brixsignage.com/v1/account/export/manifest" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.schemaVersion` | integer | | | `data.generatedAt` | string | ISO-8601 timestamp (UTC). | | `data.parts` | array of object | | | `data.parts[].part` | string | Pass to `/export/part/:part`. | | `data.parts[].table` | string | | | `data.parts[].rows` | integer | | | `data.excluded` | array of object | | | `data.excluded[].table` | string | | | `data.excluded[].reason` | string | | | `data.redactedColumns` | array of string | `table.column` values withheld from every part. | | `data.notes` | array of string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/export/part/{part} Download one export part Downloads one part of a full data export. Results are paged with a cursor rather than an offset, so rows are not skipped or duplicated if data changes while the export is running. Secret values are replaced with a marker rather than removed, so a withheld value can be told apart from one that was never set. Pass `?format=csv` to receive the same data as CSV, encoded with a UTF-8 byte-order mark for compatibility with Excel and guarded against spreadsheet formula injection. Use the `x-brix-next-cursor` response header to fetch the next page. **Notes.** - Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker (the manifest lists them in `redactedColumns`). - `?format=csv` answers `text/csv` instead, with the cursor in the `X-Brix-Next-Cursor` header. Auth: Bearer token. Permission: `billing.export`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `part` | path | string | yes | A `part` from the manifest (a table name). | | `cursor` | query | string | no | `nextCursor` of the previous page. | ```bash curl "https://api.brixsignage.com/v1/account/export/part/{part}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | Rows of the table, all columns (withheld ones marked). | | `nextCursor` | string \| null | Null on the last page. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such part. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/invoice-email Set invoice email Sets one more email address that receives every invoice Brix issues to a workspace billed directly by Brix. The workspace owners always receive invoices too. Send `null` or an empty string to remove it. Returns 422 if the value is not one email address, and 409 if the workspace is billed through the billing provider. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string \| null | yes | One more address for every invoice. `null` or empty removes it. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/invoice-email" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.payment` | AccountPayment | Payment settings of an account that Brix invoices directly. | | `data.payment.option` | "card" \| "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. | | `data.payment.card` | object \| null | | | `data.payment.backupCard` | object \| null | Charged once when the card is declined. | | `data.payment.lastPaid` | object \| null | The card the last invoice was paid with. | | `data.payment.cardAvailable` | boolean | Card payment can be set up for this workspace. | | `data.payment.invoiceEmail` | string \| null | One more address that gets every invoice. The owners always get them. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`. Response 422: Not one email address. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/invoices List invoices Returns the workspace's invoice history, newest first: invoices Brix issued for an agreed term and invoices of the card subscription. The response includes `configured: false` when billing has not been set up yet. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account/invoices" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.configured` | boolean | | | `data.invoices` | array of object \| object | Newest first. Amounts are in currency units, not cents. | | `data.reason` | string | Present when the card subscription's invoices could not be read. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/invoices/{id}/file Download invoice file Downloads the PDF file for one invoice belonging to the calling workspace. **Notes.** - For an invoice Brix issued, when the PDF cannot be drawn the route answers 302 to the invoice's web page instead. Auth: Bearer token. Permission: `billing.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Invoice id from the list. | | `inline` | query | string | no | Any value: `Content-Disposition: inline`. | ```bash curl "https://api.brixsignage.com/v1/account/invoices/{id}/file" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: Not an invoice of this workspace. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/invoices/{id}/pay-link Create invoice pay link Creates a shareable payment link for one invoice, which can be paid by card or ACH bank transfer. The link can optionally be emailed directly, for example to forward to a finance team. **Notes.** - For an invoice Brix issued, `email` is ignored and `emailed` is always false. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Invoice id from the list. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `ttlDays` | number | no | Link lifetime in days, 1–180 (clamped). Default 30. | | `email` | string | no | Also email the link to this address (card subscription invoices only). | ```bash curl -X POST "https://api.brixsignage.com/v1/account/invoices/{id}/pay-link" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | A web page where anyone with the link can see and pay the invoice. | | `data.emailed` | boolean | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: Not an invoice of this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/invoices/{id}/pdf Get invoice PDF link Returns a short-lived download URL for one invoice's PDF. Brix confirms the invoice belongs to the calling workspace before returning the link. Auth: Bearer token. Permission: `billing.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Invoice id (a card subscription invoice). | | `inline` | query | string | no | Any value: the link opens in the browser instead of downloading. | ```bash curl "https://api.brixsignage.com/v1/account/invoices/{id}/pdf" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | A short-lived download link. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: Not an invoice of this workspace (invoices Brix issued have no link here; use `/file`). Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/invoices/pay-all-link Create pay-all link Creates one shareable link that lets whoever receives it pay all of the workspace's outstanding invoices at once. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `ttlDays` | number | no | Link lifetime in days, 1–180 (clamped). Default 30. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/invoices/pay-all-link" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | One web page that lists and pays every open invoice. | | `data.ttlDays` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `billing_not_configured`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/invoices/pay-links-outstanding Create links for outstanding invoices Creates a separate hosted payment link for every invoice currently outstanding on the workspace. **Notes.** - Covers the card subscription's invoices only, not invoices Brix issued. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `ttlDays` | number | no | Link lifetime in days, 1–180 (clamped). Default 30. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/invoices/pay-links-outstanding" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.links` | array of object | | | `data.links[].invoiceId` | string | | | `data.links[].number` | string | | | `data.links[].amountDue` | number | | | `data.links[].currencyCode` | string | | | `data.links[].url` | string | | | `data.ttlDays` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `billing_not_configured`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/limits Get API limits Returns the workspace's API usage limits: the number of requests allowed per minute, the time window, and confirmation that the limit is counted per workspace across all API keys rather than per key. Also returns the `RateLimit-*` response headers to expect, and the delivery, retry, and retention behavior for webhooks. Use this before building an integration to size your request rate correctly. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/account/limits" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.api` | object | | | `data.api.perMinute` | integer | | | `data.api.windowSeconds` | integer | | | `data.api.scope` | string | `workspace`: all keys of the workspace share one budget. | | `data.api.appliesTo` | string | | | `data.api.headers` | array of string | | | `data.api.onBreach` | string | | | `data.webhooks` | object | | | `data.webhooks.maxConsecutiveFailures` | integer | | | `data.webhooks.deliveryLogRetentionDays` | integer | | | `data.webhooks.delivery` | string | | | `data.webhooks.retry` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/location-payment Get who pays for new locations Read the account setting that makes new locations pay for their own screens before they go live, whether the account can use it, and each location that pays for itself, marked `awaiting` (no card yet) or `live`. Requires `billing.view` on the whole account. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/account/location-payment" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Account (part 3 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### PUT /v1/account/location-payment Set whether new locations pay for themselves Turn on or off the account setting that makes new locations pay for their own screens before they go live. Send `{ newLocationsPayFirst: true | false }`. Requires `billing.edit` on the whole account; an API key also needs the `location-payment.edit` scope, and a connected app cannot change it. Returns 409 when the account cannot use location payment. The change is recorded in the activity log. Auth: Bearer token. ```bash curl -X PUT "https://api.brixsignage.com/v1/account/location-payment" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/look-prefs Update brand, tier and AI preferences Updates the brand kit, the organization tiers and the AI settings. Needs permission to edit settings. Any other preference is refused: use the workspace preferences route, which needs permission to edit billing. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/look-prefs" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"showScreenLogo":true}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.timeFormat` | "12h" \| "24h" | | | `data.weekStart` | "mon" \| "sun" | | | `data.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.tempUnits` | "f" \| "c" | | | `data.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.language` | string | BCP 47 language tag. | | `data.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.appBranding` | object | The look of the on-screen apps. | | `data.appBranding.accent` | string | | | `data.appBranding.accent2` | string | | | `data.appBranding.theme` | "dark" \| "light" | | | `data.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.appBranding.intensity` | number | | | `data.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.brandKits[].id` | string | | | `data.brandKits[].name` | string | | | `data.brandKits[].accent` | string | | | `data.brandKits[].accent2` | string | | | `data.brandKits[].theme` | "dark" \| "light" | | | `data.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.brandKits[].intensity` | number | | | `data.audio` | object | Default screen volume and a master mute. | | `data.audio.volume` | number | 0–100. | | `data.audio.muted` | boolean | | | `data.brand` | object | | | `data.brand.companyName` | string | | | `data.brand.logoUrl` | string | | | `data.requireAltText` | boolean | | | `data.showScreenLogo` | boolean | | | `data.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.standbyContentId` | string \| null | | | `data.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.industry` | string \| null | | | `data.onboardingCompletedAt` | string \| null | | | `data.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.orgNameSet` | boolean | | | `data.tiers` | array of integer | Location tree levels in use. | | `data.tierLabels` | object | Custom names for the location tree levels. | | `data.requireTwoFactor` | boolean | | | `data.requireSso` | boolean | | | `data.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.requireSsoPendingSince` | string \| null | | | `data.ai` | object | | | `data.ai.enabled` | boolean | | | `data.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.ai.dailyCallLimit` | integer \| null | | | `data.ai.redactPersonalData` | boolean | | | `data.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.retention.offline` | number | | | `data.retention.screenshots` | number | | | `data.retention.playback` | number | | | `data.retention.deviceLogs` | number | | | `data.retention.vitals` | number | | | `data.retention.replays` | number | | | `data.retention.aiEvents` | number | | | `data.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.warehouse.enabled` | boolean | | | `data.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.warehouse.tables` | array of string | | | `data.warehouse.lookbackDays` | integer | | | `data.supportAccess` | SupportAccessPolicy | | | `data.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 422: A key that this route does not change. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/me-prefs Get my preferences Returns preferences in three layers: `workspace` (the shared defaults), `user` (only the values the calling user has changed; empty for an API key), and `effective` (the merged result to use for display). **Notes.** - `user` is returned as saved: the per-user write does not check its keys or values. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account/me-prefs" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.workspace` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.workspace.timeFormat` | "12h" \| "24h" | | | `data.workspace.weekStart` | "mon" \| "sun" | | | `data.workspace.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.workspace.tempUnits` | "f" \| "c" | | | `data.workspace.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.workspace.language` | string | BCP 47 language tag. | | `data.workspace.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.workspace.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.workspace.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.workspace.appBranding` | object | The look of the on-screen apps. | | `data.workspace.appBranding.accent` | string | | | `data.workspace.appBranding.accent2` | string | | | `data.workspace.appBranding.theme` | "dark" \| "light" | | | `data.workspace.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.workspace.appBranding.intensity` | number | | | `data.workspace.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.workspace.brandKits[].id` | string | | | `data.workspace.brandKits[].name` | string | | | `data.workspace.brandKits[].accent` | string | | | `data.workspace.brandKits[].accent2` | string | | | `data.workspace.brandKits[].theme` | "dark" \| "light" | | | `data.workspace.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.workspace.brandKits[].intensity` | number | | | `data.workspace.audio` | object | Default screen volume and a master mute. | | `data.workspace.audio.volume` | number | 0–100. | | `data.workspace.audio.muted` | boolean | | | `data.workspace.brand` | object | | | `data.workspace.brand.companyName` | string | | | `data.workspace.brand.logoUrl` | string | | | `data.workspace.requireAltText` | boolean | | | `data.workspace.showScreenLogo` | boolean | | | `data.workspace.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.workspace.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.workspace.standbyContentId` | string \| null | | | `data.workspace.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.workspace.industry` | string \| null | | | `data.workspace.onboardingCompletedAt` | string \| null | | | `data.workspace.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.workspace.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.workspace.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.workspace.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.workspace.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.workspace.orgNameSet` | boolean | | | `data.workspace.tiers` | array of integer | Location tree levels in use. | | `data.workspace.tierLabels` | object | Custom names for the location tree levels. | | `data.workspace.requireTwoFactor` | boolean | | | `data.workspace.requireSso` | boolean | | | `data.workspace.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.workspace.requireSsoPendingSince` | string \| null | | | `data.workspace.ai` | object | | | `data.workspace.ai.enabled` | boolean | | | `data.workspace.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.workspace.ai.dailyCallLimit` | integer \| null | | | `data.workspace.ai.redactPersonalData` | boolean | | | `data.workspace.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.workspace.retention.offline` | number | | | `data.workspace.retention.screenshots` | number | | | `data.workspace.retention.playback` | number | | | `data.workspace.retention.deviceLogs` | number | | | `data.workspace.retention.vitals` | number | | | `data.workspace.retention.replays` | number | | | `data.workspace.retention.aiEvents` | number | | | `data.workspace.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.workspace.warehouse.enabled` | boolean | | | `data.workspace.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.workspace.warehouse.tables` | array of string | | | `data.workspace.warehouse.lookbackDays` | integer | | | `data.workspace.supportAccess` | SupportAccessPolicy | | | `data.workspace.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.workspace.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.workspace.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.workspace.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | | `data.user` | object | The calling user's own overrides, as saved. Empty for an API key. | | `data.effective` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.effective.timeFormat` | "12h" \| "24h" | | | `data.effective.weekStart` | "mon" \| "sun" | | | `data.effective.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.effective.tempUnits` | "f" \| "c" | | | `data.effective.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.effective.language` | string | BCP 47 language tag. | | `data.effective.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.effective.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.effective.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.effective.appBranding` | object | The look of the on-screen apps. | | `data.effective.appBranding.accent` | string | | | `data.effective.appBranding.accent2` | string | | | `data.effective.appBranding.theme` | "dark" \| "light" | | | `data.effective.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.effective.appBranding.intensity` | number | | | `data.effective.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.effective.brandKits[].id` | string | | | `data.effective.brandKits[].name` | string | | | `data.effective.brandKits[].accent` | string | | | `data.effective.brandKits[].accent2` | string | | | `data.effective.brandKits[].theme` | "dark" \| "light" | | | `data.effective.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.effective.brandKits[].intensity` | number | | | `data.effective.audio` | object | Default screen volume and a master mute. | | `data.effective.audio.volume` | number | 0–100. | | `data.effective.audio.muted` | boolean | | | `data.effective.brand` | object | | | `data.effective.brand.companyName` | string | | | `data.effective.brand.logoUrl` | string | | | `data.effective.requireAltText` | boolean | | | `data.effective.showScreenLogo` | boolean | | | `data.effective.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.effective.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.effective.standbyContentId` | string \| null | | | `data.effective.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.effective.industry` | string \| null | | | `data.effective.onboardingCompletedAt` | string \| null | | | `data.effective.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.effective.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.effective.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.effective.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.effective.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.effective.orgNameSet` | boolean | | | `data.effective.tiers` | array of integer | Location tree levels in use. | | `data.effective.tierLabels` | object | Custom names for the location tree levels. | | `data.effective.requireTwoFactor` | boolean | | | `data.effective.requireSso` | boolean | | | `data.effective.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.effective.requireSsoPendingSince` | string \| null | | | `data.effective.ai` | object | | | `data.effective.ai.enabled` | boolean | | | `data.effective.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.effective.ai.dailyCallLimit` | integer \| null | | | `data.effective.ai.redactPersonalData` | boolean | | | `data.effective.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.effective.retention.offline` | number | | | `data.effective.retention.screenshots` | number | | | `data.effective.retention.playback` | number | | | `data.effective.retention.deviceLogs` | number | | | `data.effective.retention.vitals` | number | | | `data.effective.retention.replays` | number | | | `data.effective.retention.aiEvents` | number | | | `data.effective.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.effective.warehouse.enabled` | boolean | | | `data.effective.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.effective.warehouse.tables` | array of string | | | `data.effective.warehouse.lookbackDays` | integer | | | `data.effective.supportAccess` | SupportAccessPolicy | | | `data.effective.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.effective.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.effective.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.effective.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | 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/account/onboarding Get welcome details Returns what the welcome panel needs: how the owner signed up (email, Google or Microsoft), the workspace country, whether a phone number is on file, and the region where the workspace data is stored, with a plain place name. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/account/onboarding" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/onboarding Complete onboarding Finishes workspace onboarding in a single call: renames the workspace to the given name, records the industry and complexity tier, marks onboarding as complete, and seeds a starter set of ready-to-play content tailored to the chosen industry. Combining these into one call ensures the completion flag and the seeded content are never out of sync. **Notes.** - Every call adds the starter content again; it is not idempotent. - `tier` is stored as sent without a check. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `workspaceName` | string | no | Renames the workspace and sets the brand company name (cut at 120). | | `industry` | string \| null | no | Industry id (`cafe`, `qsr`, `gym`, …); picks the starter designs. | | `tier` | "simple" \| "team" \| "enterprise" | no | | | `setupStep` | string | no | Walkthrough position to save with the answers. | | `orientation` | "landscape" \| "portrait" | no | "portrait" seeds the starter designs on a portrait stage (the first screen hangs in portrait). Default landscape. | | `welcomeDeclined` | boolean | no | The owner declined the setup questions: adds the generic starter set and records `prefs.welcomeDeclinedAt`. Any other call clears it. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/onboarding" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.prefs` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.prefs.timeFormat` | "12h" \| "24h" | | | `data.prefs.weekStart` | "mon" \| "sun" | | | `data.prefs.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.prefs.tempUnits` | "f" \| "c" | | | `data.prefs.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.prefs.language` | string | BCP 47 language tag. | | `data.prefs.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.prefs.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.prefs.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.prefs.appBranding` | object | The look of the on-screen apps. | | `data.prefs.appBranding.accent` | string | | | `data.prefs.appBranding.accent2` | string | | | `data.prefs.appBranding.theme` | "dark" \| "light" | | | `data.prefs.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.appBranding.intensity` | number | | | `data.prefs.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.prefs.brandKits[].id` | string | | | `data.prefs.brandKits[].name` | string | | | `data.prefs.brandKits[].accent` | string | | | `data.prefs.brandKits[].accent2` | string | | | `data.prefs.brandKits[].theme` | "dark" \| "light" | | | `data.prefs.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.prefs.brandKits[].intensity` | number | | | `data.prefs.audio` | object | Default screen volume and a master mute. | | `data.prefs.audio.volume` | number | 0–100. | | `data.prefs.audio.muted` | boolean | | | `data.prefs.brand` | object | | | `data.prefs.brand.companyName` | string | | | `data.prefs.brand.logoUrl` | string | | | `data.prefs.requireAltText` | boolean | | | `data.prefs.showScreenLogo` | boolean | | | `data.prefs.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.prefs.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.prefs.standbyContentId` | string \| null | | | `data.prefs.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.prefs.industry` | string \| null | | | `data.prefs.onboardingCompletedAt` | string \| null | | | `data.prefs.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.prefs.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.prefs.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.prefs.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.prefs.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.prefs.orgNameSet` | boolean | | | `data.prefs.tiers` | array of integer | Location tree levels in use. | | `data.prefs.tierLabels` | object | Custom names for the location tree levels. | | `data.prefs.requireTwoFactor` | boolean | | | `data.prefs.requireSso` | boolean | | | `data.prefs.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.prefs.requireSsoPendingSince` | string \| null | | | `data.prefs.ai` | object | | | `data.prefs.ai.enabled` | boolean | | | `data.prefs.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.prefs.ai.dailyCallLimit` | integer \| null | | | `data.prefs.ai.redactPersonalData` | boolean | | | `data.prefs.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.prefs.retention.offline` | number | | | `data.prefs.retention.screenshots` | number | | | `data.prefs.retention.playback` | number | | | `data.prefs.retention.deviceLogs` | number | | | `data.prefs.retention.vitals` | number | | | `data.prefs.retention.replays` | number | | | `data.prefs.retention.aiEvents` | number | | | `data.prefs.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.prefs.warehouse.enabled` | boolean | | | `data.prefs.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.prefs.warehouse.tables` | array of string | | | `data.prefs.warehouse.lookbackDays` | integer | | | `data.prefs.supportAccess` | SupportAccessPolicy | | | `data.prefs.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.prefs.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.prefs.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.prefs.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | | `data.seeded` | array of object | Starter designs added. | | `data.seeded[].id` | string | | | `data.seeded[].name` | string | | | `data.library` | integer | Starter library items added (photos, a playlist, a schedule, …). 0 when that step failed. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 422: Unknown `industry`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/payers List payers Lists who pays for the screens. The main account comes first, with the screens it pays for, its price and how often it is billed. Then each payer follows with its status, card, targets (locations, screen groups and screens), screen count and price. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/account/payers" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payers Add a payer Adds a payer, such as a franchise or a site that pays for its own screens. Send its name, finance email and targets. The payer starts to pay for its screens when its first invoice is paid. The change is recorded in the activity log. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/account/payers" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/payers/{id} Edit a payer Changes a payer's name, finance email, address or targets. New targets change which payer pays for each screen. Screens added during a term are invoiced to the payer now, for the remaining part of the term. The change is recorded in the activity log. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/payers/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/account/payers/{id} Remove a payer Removes a payer. Its screens go back to the main account from the next billing period, and its unpaid invoices stay open. Returns 409 `not_brix_billed` when the account is not billed by Brix. The change is recorded in the activity log. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/account/payers/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payers/{id}/card-link Get a payer's card link Returns a signed link, valid for 90 days, to a page where the payer's finance team adds a card without signing in. Send `send: true` to email the link to the payer's finance email. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/payers/{id}/card-link" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payers/resolve Preview a payer change Shows the result of a payer edit before you save it: the payer's screen count and price, the screens it would take from other payers, and the screens that two screen groups give to different payers. Nothing is saved. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/account/payers/resolve" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/payers/search Search payer targets Finds locations, screen groups and screens that match `q`, for use as payer targets. Each screen shows the payer that pays for it now. Locations are included only when the workspace has more than one. At most 50 results of each kind are returned. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/account/payers/search" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/account/payment-card Remove saved card Removes the workspace's saved card. If the payment option was set to card, it reverts to invoice billing. **Notes.** - Removing the card when a backup card is saved makes the backup the card. With no backup and the payment option `card`, the option goes back to `invoice`. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `role` | query | "primary" \| "backup" | no | `backup` removes the backup card only. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/account/payment-card" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.removed` | boolean | | | `data.payment` | AccountPayment | Payment settings of an account that Brix invoices directly. | | `data.payment.option` | "card" \| "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. | | `data.payment.card` | object \| null | | | `data.payment.backupCard` | object \| null | Charged once when the card is declined. | | `data.payment.lastPaid` | object \| null | The card the last invoice was paid with. | | `data.payment.cardAvailable` | boolean | Card payment can be set up for this workspace. | | `data.payment.invoiceEmail` | string \| null | One more address that gets every invoice. The owners always get them. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payment-card/complete Complete card setup Saves the card from a finished hosted card-setup session, given its `sessionId`. Brix re-reads the session from the payment provider and confirms it belongs to the calling workspace, returning 404 otherwise. The same result also happens automatically when the payment provider notifies Brix that the session completed. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `sessionId` | string | yes | The `card_session` value from the return URL (`cs_…`). | ```bash curl -X POST "https://api.brixsignage.com/v1/account/payment-card/complete" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.outcome` | "saved" \| "already_saved" \| "incomplete" | | | `data.payment` | AccountPayment | Payment settings of an account that Brix invoices directly. | | `data.payment.option` | "card" \| "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. | | `data.payment.card` | object \| null | | | `data.payment.backupCard` | object \| null | Charged once when the card is declined. | | `data.payment.lastPaid` | object \| null | The card the last invoice was paid with. | | `data.payment.cardAvailable` | boolean | Card payment can be set up for this workspace. | | `data.payment.invoiceEmail` | string \| null | One more address that gets every invoice. The owners always get them. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: Not a card session of this workspace. Response 409: `not_brix_billed`. Response 422: `sessionId` missing or malformed. Response 502: The session could not be read. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Account (part 4 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/account/payment-card/setup Start card setup Starts adding or replacing the saved card for a workspace billed directly by Brix. Returns a hosted checkout URL where the card is entered, unless `useLastPaid: true` is passed and the payment provider already holds a card that was last used to pay this workspace, in which case that card is saved directly. Returns 409 if the workspace is not billed directly by Brix, and 404 for white-label workspaces. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `useLastPaid` | boolean | no | Save the card the last invoice was paid with, when that is possible, instead of opening a page. | | `role` | "primary" \| "backup" | no | `backup` saves a backup card, charged once when the card is declined. Default `primary`. | ```bash curl -X POST "https://api.brixsignage.com/v1/account/payment-card/setup" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, or `card_unavailable`. Response 502: The card page could not be opened. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payment-card/swap Swap card and backup card Makes the saved backup card the card that invoices are charged to, and the previous card the backup. Returns 409 `backup_required` when no backup card is saved. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/payment-card/swap" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.swapped` | true | | | `data.payment` | AccountPayment | Payment settings of an account that Brix invoices directly. | | `data.payment.option` | "card" \| "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. | | `data.payment.card` | object \| null | | | `data.payment.backupCard` | object \| null | Charged once when the card is declined. | | `data.payment.lastPaid` | object \| null | The card the last invoice was paid with. | | `data.payment.cardAvailable` | boolean | Card payment can be set up for this workspace. | | `data.payment.invoiceEmail` | string \| null | One more address that gets every invoice. The owners always get them. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, or `backup_required` (no backup card saved). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/payment-methods List payment methods Returns the workspace's saved payment methods, including cards and ACH bank accounts. When there are two or more methods and none is the backup, one method that is not the primary is made the backup. **Notes.** - A read that can write: with two or more methods and no backup, the handler makes one non-primary method the backup and records it in the audit log. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account/payment-methods" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.configured` | boolean | False when billing is not set up (or could not be read, see `reason`). | | `data.sources` | array of object | | | `data.sources[].id` | string | | | `data.sources[].type` | string | `card`, `bank_account`, or a wallet type (`apple_pay`, `paypal_express_checkout`, …). | | `data.sources[].brand` | string \| null | | | `data.sources[].last4` | string \| null | | | `data.sources[].walletType` | string \| null | | | `data.sources[].gateway` | string \| null | | | `data.sources[].expiryMonth` | integer \| null | | | `data.sources[].expiryYear` | integer \| null | | | `data.sources[].status` | string | | | `data.sources[].primary` | boolean | | | `data.sources[].backup` | boolean | Charged when the primary fails. | | `data.reason` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payment-methods/{id}/role Set payment method role Sets a saved payment method as the primary or backup method for the workspace. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Payment method id from the list. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `role` | "primary" \| "backup" | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/payment-methods/{id}/role" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.id` | string | | | `data.role` | "primary" \| "backup" | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: Not one of this workspace's payment methods. Response 409: `billing_not_configured`. Response 422: Bad `role`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/payment-methods/manage-url Get payment methods management link Returns a hosted page URL where the workspace can add, replace, or remove a saved card or bank account. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/payment-methods/manage-url" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | A hosted page to add, replace or remove a card or bank account. Open it in a browser. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `billing_not_configured`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/payment-option Set payment option Sets how a workspace billed directly by Brix pays: `card` or `invoice`. Choosing `card` requires a saved card and returns 409 if none exists; every invoice Brix issues is then charged to that card automatically. Returns 409 if the workspace is billed through the billing provider instead, and 404 for white-label workspaces. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `option` | "card" \| "invoice" | yes | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/payment-option" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.changed` | boolean | | | `data.payment` | AccountPayment | Payment settings of an account that Brix invoices directly. | | `data.payment.option` | "card" \| "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. | | `data.payment.card` | object \| null | | | `data.payment.backupCard` | object \| null | Charged once when the card is declined. | | `data.payment.lastPaid` | object \| null | The card the last invoice was paid with. | | `data.payment.cardAvailable` | boolean | Card payment can be set up for this workspace. | | `data.payment.invoiceEmail` | string \| null | One more address that gets every invoice. The owners always get them. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: A workspace billed by a partner. Response 409: `not_brix_billed`, or `card_required` (save a card first). Response 422: Bad `option`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/prefs Update workspace preferences Updates workspace-level preferences such as locale, time zone, date and number formats, brand kit, and plan tier. Any field you include is overwritten; fields you omit keep their current value. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `kioskPin` | string \| null | no | Set (4–8 digits) or clear (null) the workspace Screen Lock PIN. Stored as a hash. | | `requireSso` | boolean | no | Needs a working single sign-on connection with verified domains; until someone signs in through it, the request is held (`requireSsoPending`). | | `requireTwoFactor` | boolean | no | Turning it on needs the calling user to have two-factor sign-in set up, so an API key cannot turn it on. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/prefs" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"timeFormat":"24h","timeZone":"America/Chicago"}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). | | `data.timeFormat` | "12h" \| "24h" | | | `data.weekStart` | "mon" \| "sun" | | | `data.dateFormat` | "mdy" \| "dmy" \| "ymd" | | | `data.tempUnits` | "f" \| "c" | | | `data.timeZone` | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. | | `data.language` | string | BCP 47 language tag. | | `data.multinational` | boolean | Shows the per-location and per-screen language settings. | | `data.newLocationsPayFirst` | boolean | New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise). | | `data.navExtras` | array of string | Console pages switched on that the workspace size hides by default. | | `data.appBranding` | object | The look of the on-screen apps. | | `data.appBranding.accent` | string | | | `data.appBranding.accent2` | string | | | `data.appBranding.theme` | "dark" \| "light" | | | `data.appBranding.backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.appBranding.intensity` | number | | | `data.brandKits` | array of object | Saved looks. An app follows one with `config.brandKitId`. A write replaces the whole list (at most 50). | | `data.brandKits[].id` | string | | | `data.brandKits[].name` | string | | | `data.brandKits[].accent` | string | | | `data.brandKits[].accent2` | string | | | `data.brandKits[].theme` | "dark" \| "light" | | | `data.brandKits[].backdrop` | "brand" \| "wash" \| "plain" \| "aurora" \| "dots" \| "grid" \| "solid" | | | `data.brandKits[].intensity` | number | | | `data.audio` | object | Default screen volume and a master mute. | | `data.audio.volume` | number | 0–100. | | `data.audio.muted` | boolean | | | `data.brand` | object | | | `data.brand.companyName` | string | | | `data.brand.logoUrl` | string | | | `data.requireAltText` | boolean | | | `data.showScreenLogo` | boolean | | | `data.keepTvOnInput` | boolean | Default for "Keep the TV on this input" on screens that have not set their own. | | `data.standbyContentKind` | string \| null | What a screen with nothing to play shows; null = the default card. | | `data.standbyContentId` | string \| null | | | `data.tier` | "simple" \| "team" \| "enterprise" | Workspace size. It sets console defaults, not access. | | `data.industry` | string \| null | | | `data.onboardingCompletedAt` | string \| null | | | `data.setupStep` | string \| null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). | | `data.welcomeDeclinedAt` | string \| null | When the owner declined the setup questions. Null if never declined, or answered later. | | `data.aboutYouDue` | boolean | The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14). | | `data.aboutYouAt` | string \| null | When the first-sign-in questions were answered. | | `data.expectedScreens` | integer \| null | How many screens the owner said they expect. | | `data.orgNameSet` | boolean | | | `data.tiers` | array of integer | Location tree levels in use. | | `data.tierLabels` | object | Custom names for the location tree levels. | | `data.requireTwoFactor` | boolean | | | `data.requireSso` | boolean | | | `data.requireSsoPending` | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. | | `data.requireSsoPendingSince` | string \| null | | | `data.ai` | object | | | `data.ai.enabled` | boolean | | | `data.ai.features` | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. | | `data.ai.dailyCallLimit` | integer \| null | | | `data.ai.redactPersonalData` | boolean | | | `data.retention` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.retention.offline` | number | | | `data.retention.screenshots` | number | | | `data.retention.playback` | number | | | `data.retention.deviceLogs` | number | | | `data.retention.vitals` | number | | | `data.retention.replays` | number | | | `data.retention.aiEvents` | number | | | `data.warehouse` | object | Data warehouse feed. Set by Brix; not writable here. | | `data.warehouse.enabled` | boolean | | | `data.warehouse.bucketBinding` | string | Set by Brix when the data warehouse feed is provisioned. | | `data.warehouse.tables` | array of string | | | `data.warehouse.lookbackDays` | integer | | | `data.supportAccess` | SupportAccessPolicy | | | `data.supportAccess.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.supportAccess.grantMinutes` | integer | How long an approval lasts. | | `data.supportAccess.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.kioskHasGlobalPin` | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 422: `sso_not_configured`, `two_factor_not_enrolled`, or a PIN that is not 4–8 digits. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/provider Get the workspace provider Returns the partner that provides this workspace, with its product name and the email addresses of its team, or `null` when no partner provides it. The partner always has access to the workspace, and this access cannot be turned off. Auth: Bearer token. Permission: `user.view`. ```bash curl "https://api.brixsignage.com/v1/account/provider" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/reactivate Reactivate account Reverses a scheduled cancellation, or resumes an account that was paused for seasonal closure. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/reactivate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.status` | "active" | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `already_active`, `pending_deletion`, `payment_required`, `payment_method_required`, `not_reactivatable`, or `under_contract`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/retention Get retention settings Returns the workspace's data retention schedule: every data stream that can be governed, the retention window currently in effect for it, and the allowed range for that window. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/account/retention" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | RetentionSchedule | | | `data.policy` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.policy.offline` | number | | | `data.policy.screenshots` | number | | | `data.policy.playback` | number | | | `data.policy.deviceLogs` | number | | | `data.policy.vitals` | number | | | `data.policy.replays` | number | | | `data.policy.aiEvents` | number | | | `data.effective` | object | Days kept per stream now. | | `data.effective.offline` | integer | | | `data.effective.screenshots` | integer | | | `data.effective.playback` | integer | | | `data.effective.deviceLogs` | integer | | | `data.effective.vitals` | integer | | | `data.effective.replays` | integer | | | `data.effective.aiEvents` | integer | | | `data.bounds` | object | | | `data.bounds.offline` | object | | | `data.bounds.offline.min` | integer | | | `data.bounds.offline.max` | integer | | | `data.bounds.offline.platformDefault` | integer | | | `data.bounds.offline.label` | string | | | `data.bounds.offline.what` | string | | | `data.bounds.screenshots` | object | | | `data.bounds.screenshots.min` | integer | | | `data.bounds.screenshots.max` | integer | | | `data.bounds.screenshots.platformDefault` | integer | | | `data.bounds.screenshots.label` | string | | | `data.bounds.screenshots.what` | string | | | `data.bounds.playback` | object | | | `data.bounds.playback.min` | integer | | | `data.bounds.playback.max` | integer | | | `data.bounds.playback.platformDefault` | integer | | | `data.bounds.playback.label` | string | | | `data.bounds.playback.what` | string | | | `data.bounds.deviceLogs` | object | | | `data.bounds.deviceLogs.min` | integer | | | `data.bounds.deviceLogs.max` | integer | | | `data.bounds.deviceLogs.platformDefault` | integer | | | `data.bounds.deviceLogs.label` | string | | | `data.bounds.deviceLogs.what` | string | | | `data.bounds.vitals` | object | | | `data.bounds.vitals.min` | integer | | | `data.bounds.vitals.max` | integer | | | `data.bounds.vitals.platformDefault` | integer | | | `data.bounds.vitals.label` | string | | | `data.bounds.vitals.what` | string | | | `data.bounds.replays` | object | | | `data.bounds.replays.min` | integer | | | `data.bounds.replays.max` | integer | | | `data.bounds.replays.platformDefault` | integer | | | `data.bounds.replays.label` | string | | | `data.bounds.replays.what` | string | | | `data.bounds.aiEvents` | object | | | `data.bounds.aiEvents.min` | integer | | | `data.bounds.aiEvents.max` | integer | | | `data.bounds.aiEvents.platformDefault` | integer | | | `data.bounds.aiEvents.label` | string | | | `data.bounds.aiEvents.what` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/retention Set retention window Sets the retention window, in days, for one or more data streams. Sending `null` for a stream resets it to the platform default. Values are clamped to the allowed range for each stream. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `offline` | number \| null | no | | | `screenshots` | number \| null | no | | | `playback` | number \| null | no | | | `deviceLogs` | number \| null | no | | | `vitals` | number \| null | no | | | `replays` | number \| null | no | | | `aiEvents` | number \| null | no | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/retention" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | RetentionSchedule | | | `data.policy` | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. | | `data.policy.offline` | number | | | `data.policy.screenshots` | number | | | `data.policy.playback` | number | | | `data.policy.deviceLogs` | number | | | `data.policy.vitals` | number | | | `data.policy.replays` | number | | | `data.policy.aiEvents` | number | | | `data.effective` | object | Days kept per stream now. | | `data.effective.offline` | integer | | | `data.effective.screenshots` | integer | | | `data.effective.playback` | integer | | | `data.effective.deviceLogs` | integer | | | `data.effective.vitals` | integer | | | `data.effective.replays` | integer | | | `data.effective.aiEvents` | integer | | | `data.bounds` | object | | | `data.bounds.offline` | object | | | `data.bounds.offline.min` | integer | | | `data.bounds.offline.max` | integer | | | `data.bounds.offline.platformDefault` | integer | | | `data.bounds.offline.label` | string | | | `data.bounds.offline.what` | string | | | `data.bounds.screenshots` | object | | | `data.bounds.screenshots.min` | integer | | | `data.bounds.screenshots.max` | integer | | | `data.bounds.screenshots.platformDefault` | integer | | | `data.bounds.screenshots.label` | string | | | `data.bounds.screenshots.what` | string | | | `data.bounds.playback` | object | | | `data.bounds.playback.min` | integer | | | `data.bounds.playback.max` | integer | | | `data.bounds.playback.platformDefault` | integer | | | `data.bounds.playback.label` | string | | | `data.bounds.playback.what` | string | | | `data.bounds.deviceLogs` | object | | | `data.bounds.deviceLogs.min` | integer | | | `data.bounds.deviceLogs.max` | integer | | | `data.bounds.deviceLogs.platformDefault` | integer | | | `data.bounds.deviceLogs.label` | string | | | `data.bounds.deviceLogs.what` | string | | | `data.bounds.vitals` | object | | | `data.bounds.vitals.min` | integer | | | `data.bounds.vitals.max` | integer | | | `data.bounds.vitals.platformDefault` | integer | | | `data.bounds.vitals.label` | string | | | `data.bounds.vitals.what` | string | | | `data.bounds.replays` | object | | | `data.bounds.replays.min` | integer | | | `data.bounds.replays.max` | integer | | | `data.bounds.replays.platformDefault` | integer | | | `data.bounds.replays.label` | string | | | `data.bounds.replays.what` | string | | | `data.bounds.aiEvents` | object | | | `data.bounds.aiEvents.min` | integer | | | `data.bounds.aiEvents.max` | integer | | | `data.bounds.aiEvents.platformDefault` | integer | | | `data.bounds.aiEvents.label` | string | | | `data.bounds.aiEvents.what` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/screen-pool Buy screen licences Sets how many screens the workspace pays for. An increase is charged now, prorated, to the payment method on file (a very small amount is added to the renewal instead). A reduction on a paid plan takes effect at the renewal and is not refunded; during the free trial a change takes effect at once. You cannot set the plan below the number of screens that are running. **Notes.** - An increase is charged now (prorated). A reduction on a paid plan is queued for the renewal and answers `scheduled: true`; in the trial it changes at once. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `quantity` | integer | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/screen-pool" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 402: `card_declined` or `payment_incomplete`: the plan did not change (or needs our team). Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `screens_in_use` (below the screens running), `no_subscription`, `account_cancelled`, or `under_contract`. Response 422: `quantity` is not a whole number from 1 to 10000. Response 502: The change could not be made. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/screen-pool/estimate Estimate screen-pool change Returns the prorated cost of changing the screen pool before committing to it, including the exact amount that would be charged today and which card would be used. This is read-only and does not change anything; it uses POST rather than GET because the requested quantity must never be cached. **Notes.** - A POST because it takes an argument; it changes nothing. Auth: Bearer token. Permission: `billing.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `quantity` | integer | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/account/screen-pool/estimate" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.lines` | array of object | Line items of the invoice raised today. | | `data.lines[].description` | string | | | `data.lines[].amount` | number | | | `data.creditsApplied` | number | Credit for the unused part of the current term. | | `data.subTotal` | number | | | `data.amountDueNow` | number | Charged now, after credits (currency units, not cents). | | `data.currencyCode` | string | | | `data.nextBillingAt` | string \| null | | | `data.payWith` | string \| null | The payment method that is charged (`Visa •••• 4242`). | | `data.currentQuantity` | integer | | | `data.newQuantity` | integer | | | `data.renewalAmount` | number \| null | What each term costs after the change. | | `data.chargedToday` | boolean | False when the amount is too small to charge today (it is added to the renewal). | | `data.invoiced` | boolean | The account pays by invoice; nothing is charged to a card. | | `data.decreaseRequiresSupport` | false | Always false. Kept for older clients. | | `data.scheduledAtRenewal` | boolean | A reduction on a paid plan: it takes effect at `renewsAt`. | | `data.renewsAt` | string \| null | | | `data.inTrial` | boolean | | | `data.trialEndsAt` | string \| null | | | `data.minQuantity` | integer | The lowest allowed quantity: the screens running now (at least 1). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_subscription`, `account_cancelled`, or `under_contract`. Response 422: `quantity` is not a whole number from 1 to 10000. Response 502: `estimate_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/account/screen-pool/scheduled Cancel scheduled screen-pool change Cancels a screen-pool reduction that is queued to take effect at renewal, keeping the current plan instead. Calling this when nothing is scheduled has no effect. **Notes.** - Succeeds when nothing is queued too. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X DELETE "https://api.brixsignage.com/v1/account/screen-pool/scheduled" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_subscription`, `account_cancelled`, or `under_contract`. Response 502: The billing provider did not answer; nothing changed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/support-access Get support access status Returns the workspace's current Brix support access policy (always allowed, allowed with notification, or approval required), every access request Brix support has raised along with its decision, and every support session opened on the workspace, with any still in progress marked as live. **Notes.** - A read that can write: pending requests past their expiry are marked `expired` first. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/account/support-access" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.policy` | SupportAccessPolicy | | | `data.policy.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.policy.grantMinutes` | integer | How long an approval lasts. | | `data.policy.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | | `data.modes` | array of object | | | `data.modes[].id` | "open" \| "notify" \| "approve" | | | `data.modes[].label` | string | | | `data.modes[].what` | string | | | `data.requests` | array of object | Newest 100. | | `data.requests[].id` | string | | | `data.requests[].staffEmail` | string | The Brix support person who asked. | | `data.requests[].reason` | string | | | `data.requests[].reasonCategory` | string \| null | | | `data.requests[].status` | "pending" \| "approved" \| "denied" \| "expired" \| "revoked" | | | `data.requests[].requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.requests[].requestExpiresAt` | string | ISO-8601 timestamp (UTC). | | `data.requests[].decidedAt` | string \| null | | | `data.requests[].decidedByEmail` | string \| null | | | `data.requests[].decidedByName` | string \| null | | | `data.requests[].grantExpiresAt` | string \| null | | | `data.requests[].decisionNote` | string \| null | | | `data.requests[].grantLive` | boolean | | | `data.sessions` | array of object | Times Brix support opened the workspace, newest 100. | | `data.sessions[].id` | string | | | `data.sessions[].staffEmail` | string | | | `data.sessions[].reason` | string | | | `data.sessions[].startedAt` | string | ISO-8601 timestamp (UTC). | | `data.sessions[].endedAt` | string \| null | | | `data.sessions[].expiresAt` | string \| null | | | `data.sessions[].live` | boolean | | | `data.sessions[].recorded` | boolean | The session was screen-recorded. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/account/support-access/policy Set support access policy Sets whether Brix support may open the workspace: always allowed and recorded, allowed but the workspace is notified as it happens, or only with explicit approval for each request. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `mode` | "open" \| "notify" \| "approve" | no | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `grantMinutes` | integer | no | How long an approval lasts. | | `requestTtlMinutes` | integer | no | How long a request waits for an answer before it expires. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/account/support-access/policy" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SupportAccessPolicy | | | `data.mode` | "open" \| "notify" \| "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. | | `data.grantMinutes` | integer | How long an approval lasts. | | `data.requestTtlMinutes` | integer | How long a request waits for an answer before it expires. | Response 401: Missing, expired or revoked bearer token. Response 403: A Brix support session cannot change this. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/support-access/revoke Revoke support access Immediately withdraws consent for Brix support access: ends every live support session and cancels any outstanding approval, in that order. Auth: Bearer token. Permission: `settings.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/support-access/revoke" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.sessionsEnded` | integer | | | `data.grantsRevoked` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: A Brix support session cannot do this. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/account/upgrade-annual Switch to annual billing Switches the workspace's monthly subscription to annual, upfront billing. Returns 409 if the workspace is already on annual billing or has no active subscription. Auth: Bearer token. Permission: `billing.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/account/upgrade-annual" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.cadence` | "annual" | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_subscription`, `under_contract`, or `already_annual`. Response 502: The switch failed. Response 503: `annual_switch_unavailable`: the switch is not self-serve yet; contact support. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/account/upgrade-annual/estimate Estimate annual upgrade cost Returns the prorated cost of switching from monthly to annual billing before committing to it, including which card would be charged. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/account/upgrade-annual/estimate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.lines` | array of object | Line items of the invoice raised today. | | `data.lines[].description` | string | | | `data.lines[].amount` | number | | | `data.creditsApplied` | number | Credit for the unused part of the current term. | | `data.subTotal` | number | | | `data.amountDueNow` | number | Charged now, after credits (currency units, not cents). | | `data.currencyCode` | string | | | `data.nextBillingAt` | string \| null | | | `data.payWith` | string \| null | The payment method that is charged (`Visa •••• 4242`). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 409: `no_subscription` or `under_contract`. Response 502: `estimate_unavailable`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Ad slots 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/ad-slots List ad slots List the programmatic ad slots configured in the workspace. Each slot includes its provider, endpoint, venue or device identifiers, and its minimum and maximum duration limits. The exchange credential itself is never included; only the name of the stored credential reference is returned. **Notes.** - Newest first; only slots at locations the caller can see. `secretRefs` is always `[]` here: read one slot to see them. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/ad-slots" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AdSlot | | | `data[].id` | string | | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].enabled` | boolean | | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].config` | AdSlotConfig \| null | Null when the stored settings cannot be read. | | `data[].secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. | 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/ad-slots Create an ad slot with a `name` and a `config` object containing `provider`, `endpoint`, `credsRef`, `minSeconds`, `maxSeconds`, `podSeconds`, and `allowAudio`, plus optional `venueId`, `deviceTypeId`, and `nodeId`. The slot is created disabled and cannot request ads until you enable it with a later update. **Notes.** - A new slot is always created disabled (`enabled` in the body is ignored), and `secretRefs` is `[]`. Auth: Bearer token. Permission: `integration.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Up to 120 characters. | | `enabled` | boolean | no | Ignored: a new slot is always created disabled. Enable it with an update once its secret is set. | | `nodeId` | string \| null | no | Home location; you need `integration.create` there. | | `config` | object | yes | | | `config.provider` | "vast" \| "vistar" \| "broadsign" \| "hivestack" | yes | | | `config.endpoint` | string | yes | | | `config.credsRef` | string | no | The name of the secret (set with `PUT /v1/ad-slots/:id/secrets`) that holds the ad server credential. | | `config.venueId` | string \| null | no | | | `config.deviceTypeId` | string \| null | no | | | `config.minSeconds` | integer | no | Shortest ad to accept, 1–300 (default 5). | | `config.maxSeconds` | integer | no | Longest ad to accept, at least `minSeconds`. | | `config.podSeconds` | integer | no | Seconds of ads per break, at least `maxSeconds`. | | `config.allowAudio` | boolean | no | | | `config.vistar` | object | no | Vistar settings. Only for `provider` = `vistar`. The endpoint is fixed by `environment`. | | `config.vistar.environment` | "staging" \| "production" | yes | Which Vistar network the slot talks to. Staging and production use separate credentials. | | `config.vistar.spots` | integer | yes | Open spots requested per visit to the pod, 1–12. Each spot is one request and at most one ad. | | `config.vistar.staticSeconds` | integer | yes | Seconds a still image plays, 1–60. | ```bash curl -X POST "https://api.brixsignage.com/v1/ad-slots" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Lobby ads","enabled":true,"config":{"provider":"vast","endpoint":"https://ads.example.com/vast","credsRef":"vastKey"}}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AdSlot | A slot that fills airtime from a programmatic ad server. | | `data.id` | string | | | `data.spaceId` | string | | | `data.name` | string | | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. | | `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `integration.create` at the location. Response 422: `name` missing, or `config` has no provider or endpoint, or the endpoint is not a public http(s) URL. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/ad-slots/{id} Get an ad slot Retrieve one ad slot, including the names of the credentials stored against it. Credential values are write-only and are never returned by this or any other endpoint. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | ```bash curl "https://api.brixsignage.com/v1/ad-slots/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AdSlot | A slot that fills airtime from a programmatic ad server. | | `data.id` | string | | | `data.spaceId` | string | | | `data.name` | string | | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. | | `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. | 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 ad slot in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/ad-slots/{id} Update an ad slot Edit an ad slot's name, node, or exchange configuration, or turn ad requesting on and off. Enabling a slot is what allows it to start spending, so this action is recorded in the activity log. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `enabled` | boolean | no | | | `nodeId` | string \| null | no | Move the slot; you need `integration.edit` at the destination too. | | `config` | object | no | Replaces the settings (missing fields take their defaults). A change to `provider`, `endpoint` or `credsRef` deletes the stored secrets (except for Vistar); set them again with `PUT /v1/ad-slots/:id/secrets`. | | `config.provider` | "vast" \| "vistar" \| "broadsign" \| "hivestack" | yes | | | `config.endpoint` | string | yes | | | `config.credsRef` | string | no | The name of the secret (set with `PUT /v1/ad-slots/:id/secrets`) that holds the ad server credential. | | `config.venueId` | string \| null | no | | | `config.deviceTypeId` | string \| null | no | | | `config.minSeconds` | integer | no | Shortest ad to accept, 1–300 (default 5). | | `config.maxSeconds` | integer | no | Longest ad to accept, at least `minSeconds`. | | `config.podSeconds` | integer | no | Seconds of ads per break, at least `maxSeconds`. | | `config.allowAudio` | boolean | no | | | `config.vistar` | object | no | Vistar settings. Only for `provider` = `vistar`. The endpoint is fixed by `environment`. | | `config.vistar.environment` | "staging" \| "production" | yes | Which Vistar network the slot talks to. Staging and production use separate credentials. | | `config.vistar.spots` | integer | yes | Open spots requested per visit to the pod, 1–12. Each spot is one request and at most one ad. | | `config.vistar.staticSeconds` | integer | yes | Seconds a still image plays, 1–60. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/ad-slots/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AdSlot | A slot that fills airtime from a programmatic ad server. | | `data.id` | string | | | `data.spaceId` | string | | | `data.name` | string | | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. | | `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `integration.edit` at the destination. Response 404: No such ad slot in this workspace. Response 409: `conflict`: a `config` change found the slot settings or secrets changed while this request ran. Nothing was saved; read the slot again and resend. Response 422: An empty `name`, or an invalid `config`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/ad-slots/{id} Delete an ad slot and stop it from requesting ads. Cached creatives and the record of impressions already played are kept, so past playback history remains available after the slot is removed. **Notes.** - Answers `{ ok: true }`. The slot is also disabled; its impressions are kept. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/ad-slots/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | 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 ad slot in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/ad-slots/{id}/health Get an ad slot's fill health Returns fill health for an ad slot over a time window (24 hours by default): ads requested, leased, played, confirmed, expired and not filled, errors, spend, expiry rates, display and confirmation delays, and the screens that requested ads. These are the numbers the ad exchange checks. Available only to workspaces with digital-out-of-home enabled. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl "https://api.brixsignage.com/v1/ad-slots/{id}/health" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/ad-slots/{id}/impressions List ad slot impressions List what an ad slot has actually played, and whether each impression beacon was recorded successfully. Results are returned newest first and the response is capped at 200 records. Use this to reconcile playback against an advertiser's invoice. **Notes.** - The newest 200 plays. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | ```bash curl "https://api.brixsignage.com/v1/ad-slots/{id}/impressions" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].spaceId` | string | | | `data[].slotId` | string | | | `data[].screenId` | string | | | `data[].creativeId` | string | The ad server's creative id. | | `data[].playKey` | string | A unique key for this play. | | `data[].playedAt` | string | ISO-8601 timestamp (UTC). | | `data[].beaconsOk` | integer | Tracking beacons that the ad server accepted. | | `data[].beaconsFailed` | integer | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | 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 ad slot in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/ad-slots/{id}/secrets Set ad slot secrets Store the exchange credential for an ad slot. Send a map of reference names to values; the values are encrypted at rest and merged into any existing credentials. Setting a value to `null` deletes that reference. Only the credential names are ever returned, never the values. **Notes.** - Values are encrypted and never returned. Validation errors answer 400, not 422. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `secrets` | object | yes | Secret name → value (up to 20 names of up to 128 characters; values up to 8192). Null or empty removes that secret; names you do not send are kept. | ```bash curl -X PUT "https://api.brixsignage.com/v1/ad-slots/{id}/secrets" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.refs` | array of string | Every secret name that now holds a value. | Response 400: `too_many_secrets`, `ref_too_long` or `value_too_long`. 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 ad slot in this workspace. Response 409: The slot settings or secrets changed while this request ran. Nothing was saved; send it again. Response 429: More than 30 calls a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/ad-slots/{id}/test Test an ad slot's connection Makes one real ad request for one screen, releases the lease at once and plays nothing, to prove that the credentials and the venue id work. Returns whether the test passed, the reason, and the request with secrets removed. Available only to workspaces with digital-out-of-home enabled. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/ad-slots/{id}/test" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/ad-slots/{id}/venues List ad slot venues List the screens you can see, each with the Vistar venue id it uses for this ad slot. `venueId` is null for a screen with no venue. Vistar refuses ad requests that have no venue id registered in your Vistar network. **Notes.** - One entry for each screen the caller can see. `venueId` is null when the screen has no venue. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | ```bash curl "https://api.brixsignage.com/v1/ad-slots/{id}/venues" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].screenId` | string | | | `data[].screenName` | string | | | `data[].venueId` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: The `dooh` feature is off for this workspace (`feature_disabled`). Response 404: No such ad slot in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/ad-slots/{id}/venues Set ad slot venues Set or clear the Vistar venue id of many screens at once. Send a list of `screenId` and `venueId` entries. A `venueId` of null clears the mapping. If any entry is not valid, nothing is saved and the response lists each problem. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | Request body: `application/json` ```bash curl -X PUT "https://api.brixsignage.com/v1/ad-slots/{id}/venues" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.changed` | integer | Screens whose venue is now different. | Response 401: Missing, expired or revoked bearer token. Response 403: The `dooh` feature is off for this workspace (`feature_disabled`). Response 404: No such ad slot in this workspace. Response 422: An entry has an unknown screen or an invalid venue id. Nothing is saved; `errors` lists each entry. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/ad-slots/{id}/venues/import Import ad slot venues Set venue ids from CSV text. Each line is `screen,venue_id`, where `screen` is a screen id or an exact screen name. Valid lines are saved. The response gives the number saved and lists each line that was refused, with the reason. **Notes.** - Valid lines are saved. Lines with a problem are listed in `errors` and are not saved. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Ad slot id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `csv` | string | yes | Lines of `screen,venue_id`. `screen` is a screen id or an exact screen name. A header line is optional. | ```bash curl -X POST "https://api.brixsignage.com/v1/ad-slots/{id}/venues/import" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.applied` | integer | | | `data.errors` | array of object | | | `data.errors[].line` | integer | | | `data.errors[].screen` | string | | | `data.errors[].reason` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: The `dooh` feature is off for this workspace (`feature_disabled`). Response 404: No such ad slot in this workspace. Response 422: `csv` is missing or too large. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## AI 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/ai/events List AI activity events Return the workspace's record of every AI-powered call it made, including the feature, model, outcome, actor, duration, and number of redactions. Calls that were refused, for example because the feature is disabled or a usage limit was reached, also appear as entries, since a blocked request is only evidenced by a record of the refusal. The prompt and output text are never stored. Only events at locations where the caller holds the audit log view permission are returned, as in the audit log. The actor is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example `user` or `staff`. Results are paginated and can be filtered by feature, outcome, and a starting point in time; a page can hold fewer entries than the limit. **Notes.** - `nextCursor` sits beside `data`, outside the usual envelope. - Only events where the caller's `audit-log.view` reaches the event's location are returned, so a page can hold fewer than `limit` events while `nextCursor` is still set. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `feature` | query | string | no | Only this feature (an unknown value is ignored). | | `outcome` | query | "ok" \| "blocked" \| "error" \| "quota" \| "disabled" | no | Only this outcome (an unknown value is ignored). | | `since` | query | string | no | Only events at or after this ISO 8601 time. | | `cursor` | query | string | no | `nextCursor` from the previous page. | | `limit` | query | integer | no | Page size. | ```bash curl "https://api.brixsignage.com/v1/ai/events" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AiEvent | | | `data[].id` | string | | | `data[].spaceId` | string | | | `data[].nodeId` | string \| null | The location of the content the call was about; null for the workspace root. | | `data[].actor` | string | Who made the call. An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. Without `user.view` at the event's location, only the kind (`user`, `staff`, …). | | `data[].feature` | string | `tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`, … | | `data[].featureLabel` | string | The feature's display name (the raw key for an unknown feature). | | `data[].sends` | string \| null | What the feature sends to the model; null for an unknown feature. | | `data[].model` | string | | | `data[].provider` | string | | | `data[].outcome` | "ok" \| "blocked" \| "error" \| "quota" \| "disabled" | | | `data[].durationMs` | number \| null | | | `data[].inputKind` | string \| null | `image`, `text` or `audio`: what was sent, never the content. | | `data[].redactions` | integer | Personal-data patterns masked before the call. | | `data[].detail` | string \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `nextCursor` | string \| null | Pass as `cursor` for the next (older) page; null on the last page. | 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/ai/events.csv Export AI activity events as CSV Return the same AI activity data as a CSV file, suitable for sharing or importing elsewhere. It applies the same filters, the same location scope and the same actor rule as the JSON list, so the export always matches what the list view shows. **Notes.** - One page, as a file (`content-disposition: attachment`). Columns: when, feature, model, provider, outcome, actor, duration_ms, input, redactions, detail. There is no next-page cursor: page with `since` or the JSON list. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `feature` | query | string | no | Only this feature (an unknown value is ignored). | | `outcome` | query | "ok" \| "blocked" \| "error" \| "quota" \| "disabled" | no | Only this outcome (an unknown value is ignored). | | `since` | query | string | no | Only events at or after this ISO 8601 time. | | `cursor` | query | string | no | `nextCursor` from the previous page. | | `limit` | query | integer | no | Rows (default and maximum: the largest page). | ```bash curl "https://api.brixsignage.com/v1/ai/events.csv" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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/ai/models List AI models in use Return which AI model powers each AI feature, when it was adopted, what it replaced, and the safe-use guidance shown to users at the point of use. This reflects the exact configuration currently enforced, so it cannot drift out of step with actual behavior. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/ai/models" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.fingerprint` | string | Changes whenever any model below changes. | | `data.providers` | array of string | | | `data.firstParty` | string | A plain statement of who runs the models. | | `data.safeUse` | array of string | The safe-use guidance shown with AI features. | | `data.features` | array of object | | | `data.features[].feature` | string | | | `data.features[].label` | string | | | `data.features[].sends` | string | | | `data.features[].model` | string | | | `data.features[].provider` | string | | | `data.features[].since` | string | When this model started running the feature (a date). | | `data.features[].what` | string | | | `data.features[].previous` | array of object | | | `data.features[].previous[].model` | string | | | `data.features[].previous[].until` | string | | | `data.features[].previous[].why` | string | | | `data.features[].fallback` | object | | | `data.features[].fallback.model` | string | | | `data.features[].fallback.provider` | string | | | `data.features[].fallback.when` | string | | | `data.features[].configuredBy` | string | | | `data.safety` | array of object | Models that screen text before it is sent. | | `data.safety[].key` | string | | | `data.safety[].model` | string | | | `data.safety[].provider` | string | | | `data.safety[].since` | string | When this model started running the feature (a date). | | `data.safety[].what` | string | | | `data.safety[].runsWhen` | string | | | `data.rollback` | string | | 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/ai/summary Summarize AI activity Return counts of AI calls grouped by feature, model, and outcome over a time window that defaults to 30 days. Totals separate calls that ran successfully, calls that failed, and calls that were refused due to policy or usage limits, so a refusal is never confused with a failure. Only calls at locations where the caller holds the audit log view permission are counted. **Notes.** - `blocked` calls count in no total but appear in `byFeature`. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `days` | query | integer | no | Window in days, 1–365 (default 30). | ```bash curl "https://api.brixsignage.com/v1/ai/summary" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.windowDays` | integer | | | `data.since` | string | ISO-8601 timestamp (UTC). | | `data.totals` | object | | | `data.totals.ran` | integer | | | `data.totals.failed` | integer | | | `data.totals.refusedByPolicy` | integer | | | `data.totals.refusedByLimit` | integer | | | `data.totals.redactions` | integer | | | `data.byFeature` | array of object | One row per feature, model and outcome. | | `data.byFeature[].feature` | string | | | `data.byFeature[].featureLabel` | string | | | `data.byFeature[].model` | string | | | `data.byFeature[].outcome` | string | | | `data.byFeature[].calls` | integer | | | `data.byFeature[].redactions` | integer | | 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. ## Alert channels 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/alert-channels/teams/test Send a test Microsoft Teams alert Send a sample alert card to a Microsoft Teams webhook to confirm it is configured correctly. Provide the webhook `url` in the request body; it must be a Microsoft Teams Workflow URL. The response returns `ok`, `status`, and an optional `message`, and never includes the URL you sent. This operation is rate-limited to 10 requests per minute. A refusal from Microsoft Teams is NOT an HTTP error: the answer is 200 with `ok: false` and a `message` to show. Auth: Bearer token. Permission: `alert-rule.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | yes | A Microsoft Teams workflow URL, or the masked URL a saved rule shows (then send `ruleId` too). | | `ruleId` | string | no | With a masked `url`: the rule whose saved URL to use. | ```bash curl -X POST "https://api.brixsignage.com/v1/alert-channels/teams/test" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: The URL is not a Microsoft Teams workflow URL, or a masked URL matches no URL saved on `ruleId`. Response 429: More than 10 calls in a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Alert events 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/alert-events List alert events List alerts that have fired against your screens, each combined with the screen's name. This endpoint is read-only: alerts open automatically when a condition is detected and close automatically on recovery. Only currently open alerts are returned, as a limited list, so a long history does not push them out. Open events (up to 300, newest first) followed by recently closed ones (up to 300). Not paginated. **Notes.** - The route-registry description names `alert-rule.view`, but the route is gated by `screen.view`; `screen.view` is what a key needs. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/alert-events" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AlertEvent | | | `data[].id` | string | Alert event id. | | `data[].code` | string | What fired, e.g. `connection-lost`, `display-off`, `storage-critical`. | | `data[].severity` | string | `info`, `warning` or `critical`. | | `data[].screenId` | string | | | `data[].screenName` | string | `(unknown screen)` if the screen is gone. | | `data[].message` | string | | | `data[].nextAction` | string | Suggested next step; may be empty. | | `data[].openedAt` | string | ISO-8601 timestamp (UTC). | | `data[].closedAt` | string \| null | Null while open. | | `data[].detail` | object \| null | Structured detail keyed by `kind` (`recovery`, `outage-history`, `network-unstable`, `display-off`), or null. | 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/alert-events/{id}/close Close an alert event Manually close an alert event before it would close automatically on recovery. Access is checked against the screen where the alert fired. **Notes.** - The route-registry description names `alert-rule.edit`, but the route is gated by `screen.edit` at the event's location. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Alert event id. | ```bash curl -X POST "https://api.brixsignage.com/v1/alert-events/{id}/close" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AlertEvent | One firing of an alert rule against a screen. | | `data.id` | string | Alert event id. | | `data.code` | string | What fired, e.g. `connection-lost`, `display-off`, `storage-critical`. | | `data.severity` | string | `info`, `warning` or `critical`. | | `data.screenId` | string | | | `data.screenName` | string | `(unknown screen)` if the screen is gone. | | `data.message` | string | | | `data.nextAction` | string | Suggested next step; may be empty. | | `data.openedAt` | string | ISO-8601 timestamp (UTC). | | `data.closedAt` | string \| null | Null while open. | | `data.detail` | object \| null | Structured detail keyed by `kind` (`recovery`, `outage-history`, `network-unstable`, `display-off`), or 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 event. Response 409: `already_closed`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Alert rules 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/alert-rules List alert rules List the alert rules configured for your workspace. Each rule includes its name, trigger, scope configuration, and whether it is enabled. Results are limited to the organization nodes you have access to. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. Auth: Bearer token. Permission: `alert-rule.view`. Parameters: | Name | 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. | ```bash curl "https://api.brixsignage.com/v1/alert-rules" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AlertRule | | | `data[].id` | string | Alert rule id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].trigger` | string | The first trigger code, e.g. `connection-lost`. | | `data[].config` | AlertRuleConfig | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `data[].config.codes` | array of string | Every trigger code the rule watches; the first is also `trigger`. | | `data[].config.severity` | string | | | `data[].config.scopeKind` | string | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `data[].config.scopeId` | string | | | `data[].config.thresholds` | object | | | `data[].config.channels` | array of string | `in-app`, `email`, `webhook`, `teams`. | | `data[].config.recipients` | array of string | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data[].config.teamsUrls` | array of string | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data[].enabled` | boolean | | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `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/alert-rules Create an alert rule with a `name`, `trigger`, optional `config`, optional `enabled` flag, and optional `nodeId`. If the scope named in `config` does not resolve to an existing target, the request is refused rather than saved. A Microsoft Teams channel is also refused unless `config.teamsUrls` contains at least one valid Microsoft Teams Workflow HTTPS URL. The response shows each URL masked. **Notes.** - The 201 body is the row as written, not re-read: `nodeId` is absent when the create did not set one. Auth: Bearer token. Permission: `alert-rule.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `trigger` | string | yes | | | `config` | AlertRuleConfig | no | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `config.codes` | array of string | no | Every trigger code the rule watches; the first is also `trigger`. | | `config.severity` | string | no | | | `config.scopeKind` | string | no | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `config.scopeId` | string | no | | | `config.thresholds` | object | no | | | `config.channels` | array of string | no | `in-app`, `email`, `webhook`, `teams`. | | `config.recipients` | array of string | no | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `config.teamsUrls` | array of string | no | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `enabled` | boolean | no | | | `nodeId` | string \| null | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/alert-rules" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Alert rule id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.trigger` | string | The first trigger code, e.g. `connection-lost`. | | `data.config` | AlertRuleConfig | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `data.config.codes` | array of string | Every trigger code the rule watches; the first is also `trigger`. | | `data.config.severity` | string | | | `data.config.scopeKind` | string | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `data.config.scopeId` | string | | | `data.config.thresholds` | object | | | `data.config.channels` | array of string | `in-app`, `email`, `webhook`, `teams`. | | `data.config.recipients` | array of string | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.config.teamsUrls` | array of string | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | | | `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: The location does not exist. Response 422: `name` or `trigger` is missing, the scope target does not exist, or a Microsoft Teams URL is not a workflow URL. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/alert-rules/{id} Get an alert rule Get one alert rule, including its full trigger configuration. Access is limited to the organization nodes you can see. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. Auth: Bearer token. Permission: `alert-rule.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Alert rule id. | ```bash curl "https://api.brixsignage.com/v1/alert-rules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AlertRule | | | `data.id` | string | Alert rule id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.trigger` | string | The first trigger code, e.g. `connection-lost`. | | `data.config` | AlertRuleConfig | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `data.config.codes` | array of string | Every trigger code the rule watches; the first is also `trigger`. | | `data.config.severity` | string | | | `data.config.scopeKind` | string | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `data.config.scopeId` | string | | | `data.config.thresholds` | object | | | `data.config.channels` | array of string | `in-app`, `email`, `webhook`, `teams`. | | `data.config.recipients` | array of string | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.config.teamsUrls` | array of string | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `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 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/alert-rules/{id} Update an alert rule's `name`, `trigger`, `config`, `enabled` flag, or `nodeId`. The same scope validation used when creating a rule applies here. To keep a saved URL, send its masked value back unchanged. To replace it, send the new URL. A masked value that matches no saved URL is refused. Auth: Bearer token. Permission: `alert-rule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Alert rule id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `trigger` | string | no | | | `config` | AlertRuleConfig | no | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `config.codes` | array of string | no | Every trigger code the rule watches; the first is also `trigger`. | | `config.severity` | string | no | | | `config.scopeKind` | string | no | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `config.scopeId` | string | no | | | `config.thresholds` | object | no | | | `config.channels` | array of string | no | `in-app`, `email`, `webhook`, `teams`. | | `config.recipients` | array of string | no | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `config.teamsUrls` | array of string | no | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `enabled` | boolean | no | | | `nodeId` | string \| null | no | | | `baseUpdatedAt` | string | no | The `updatedAt` your edit is based on; 409 with the current row if it moved. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/alert-rules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AlertRule | | | `data.id` | string | Alert rule id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.trigger` | string | The first trigger code, e.g. `connection-lost`. | | `data.config` | AlertRuleConfig | The rule's trigger, scope and delivery settings. Other keys pass through unchanged. | | `data.config.codes` | array of string | Every trigger code the rule watches; the first is also `trigger`. | | `data.config.severity` | string | | | `data.config.scopeKind` | string | `workspace`, `org_unit`, `location`, `screen_group` or `screen`. | | `data.config.scopeId` | string | | | `data.config.thresholds` | object | | | `data.config.channels` | array of string | `in-app`, `email`, `webhook`, `teams`. | | `data.config.recipients` | array of string | Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.config.teamsUrls` | array of string | Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it. | | `data.enabled` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `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 rule with this id. Response 409: `conflict`: changed since `baseUpdatedAt`; the body carries `current`. Response 422: The scope target does not exist, a Microsoft Teams URL is not a workflow URL, or a masked URL matches no saved URL. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/alert-rules/{id} Delete an alert rule. It moves to the recycle bin and stops firing immediately. Auth: Bearer token. Permission: `alert-rule.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Alert rule id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/alert-rules/{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 alert rule in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/alert-rules/{id}/restore Restore a deleted alert rule Restore an alert rule that was deleted within the last 30 days. The rule resumes firing once restored. Auth: Bearer token. Permission: `alert-rule.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Alert rule id. | ```bash curl -X POST "https://api.brixsignage.com/v1/alert-rules/{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 alert rule in this workspace, or it was purged. Response 409: `not_deleted`: the rule is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Alerts 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/alerts/bulk Close alert events in bulk Close up to 500 alert events in one call with the action `close`. The answer lists the events that closed in `ok` and the ones that did not in `failed`, so one failure does not stop the rest. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/alerts/bulk" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## API keys 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/api-keys List API keys Returns the workspace's API keys: name, assigned permissions, the location the key is pinned to (if any), and when each was created and last used. Key secrets are never returned. A key is listed only where the caller holds the API key view permission at the key's location; a workspace-wide key needs that permission for the whole workspace. **Notes.** - Not paginated. Revoked keys are listed too (`revokedAt` set). Auth: Bearer token. Permission: `api-key.view`. ```bash curl "https://api.brixsignage.com/v1/api-keys" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of ApiKey | | | `data[].id` | string | | | `data[].name` | string | | | `data[].preview` | string | The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential. | | `data[].permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data[].nodeId` | string \| null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. | | `data[].lastUsedAt` | string \| null | | | `data[].expiresAt` | string \| null | Null = never expires. | | `data[].expired` | boolean | | | `data[].revokedAt` | string \| null | Set when the key was revoked; a revoked key no longer authenticates. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | 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/api-keys Create API key Creates a new API key. Provide `name`, `permissions` (a list of `resource.action` strings, or `"all"`), and an optional `nodeId` to restrict the key to one location and everything beneath it. The raw key secret is returned exactly once, in this response; only its hash is stored afterward, so it cannot be retrieved again. Auth: Bearer token. Permission: `api-key.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `permissions` | "all" \| array of string | no | You must hold each one where the key applies. Default `[]` (a key that can do nothing). | | `nodeId` | string \| null | no | Pin the key to this location. Omit for a workspace-wide key, which needs its permissions workspace-wide. | | `expiresInDays` | number \| null | no | Days until the key stops working (at most 3650). Omit, null or 0 = never expires. | ```bash curl -X POST "https://api.brixsignage.com/v1/api-keys" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Menu board sync","permissions":["screen.view","media.create"],"expiresInDays":365}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.name` | string | | | `data.preview` | string | The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.nodeId` | string \| null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. | | `data.lastUsedAt` | string \| null | | | `data.expiresAt` | string \| null | Null = never expires. | | `data.expired` | boolean | | | `data.revokedAt` | string \| null | Set when the key was revoked; a revoked key no longer authenticates. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.secret` | string | The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer `. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold every permission you grant, or not at the key's location (a workspace-wide key needs them workspace-wide). Also refused for a Brix support session. Response 422: `name` missing, `expiresInDays` over 3650 or not a number, or `nodeId` not a location of this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/api-keys/{id} Revoke API key Revokes an API key immediately, so it can no longer be used. You must hold the permission to delete keys at or above the location the key is pinned to, not merely somewhere else in the workspace. **Notes.** - The key stays in the list with `revokedAt` set. Revoking a key again answers 200 and moves `revokedAt` to now. Auth: Bearer token. Permission: `api-key.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | API key id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/api-keys/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.revoked` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You lack `api-key.delete` at the key's location. Response 404: No such key in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/api-keys/{id}/rotate Rotate API key Replaces an API key's secret with a new one, invalidating the old secret immediately. The new secret is returned exactly once, in this response. You must hold the permission to create keys at or above the location the key is pinned to. **Notes.** - The key keeps its id, name, permissions, location and expiry; `lastUsedAt` is reset to null. An expired key can be rotated and stays expired. Auth: Bearer token. Permission: `api-key.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | API key id. | ```bash curl -X POST "https://api.brixsignage.com/v1/api-keys/{id}/rotate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.name` | string | | | `data.preview` | string | The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.nodeId` | string \| null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. | | `data.lastUsedAt` | string \| null | | | `data.expiresAt` | string \| null | Null = never expires. | | `data.expired` | boolean | | | `data.revokedAt` | string \| null | Set when the key was revoked; a revoked key no longer authenticates. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.secret` | string | The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer `. | Response 401: Missing, expired or revoked bearer token. Response 403: The key holds permissions you cannot grant at its location, you lack `api-key.create` there, or a Brix support session. Response 404: No such key in this workspace. Response 409: `revoked`: a revoked key cannot be rotated; create a new one. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## App instances 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/app-instances List app instances List every app configured in the workspace, including its id, `appKey`, name, configuration, and node. This is the data behind the My apps grid. Auth: Bearer token. Permission: `app-instance.view`. Parameters: | Name | 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). | ```bash curl "https://api.brixsignage.com/v1/app-instances" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AppInstance | | | `data[].id` | string | App instance id. | | `data[].spaceId` | string | Workspace id. | | `data[].appKey` | string | The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …). | | `data[].name` | string | | | `data[].config` | any | The app's settings (JSON). The keys depend on `appKey`. | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `data[].lastSnapshotKey` | string \| null | Internal key of the last rendered thumbnail. | | `data[].lastSnapshotAt` | string \| null | | | `data[].importSourceId` | string \| null | Id in the system it was imported from, if imported. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `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. | ```json { "data": [ { "id": "app_3c4d5e6f7a8b9c0d", "spaceId": "space_1a2b3c4d5e6f7a8b", "appKey": "clock", "name": "Lobby clock", "config": { "format": "24h" }, "nodeId": null, "lastSnapshotKey": null, "lastSnapshotAt": null, "importSourceId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null } ] } ``` 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/app-instances Create an app instance Configure an app for the workspace with an `appKey`, `name`, and optional `config` and `nodeId`. `appKey` must match one of the apps offered by the store; list the available keys first with GET /v1/apps/catalog. **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. Auth: Bearer token. Permission: `app-instance.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `appKey` | string | yes | A key from `GET /v1/apps/catalog`. An unknown key is refused (422 `unknown_app`). | | `name` | string | yes | | | `config` | object \| string | no | The app's settings: a JSON object, or the same as a JSON string. Default `{}`. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | ```bash curl -X POST "https://api.brixsignage.com/v1/app-instances" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"appKey":"clock","name":"Lobby clock","config":{"format":"24h"}}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | App instance id. | | `data.spaceId` | string | Workspace id. | | `data.appKey` | string | The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …). | | `data.name` | string | | | `data.config` | any | The app's settings (JSON). The keys depend on `appKey`. | | `data.nodeId` | string \| null | Home location, when one was set or derived. | | `data.lastSnapshotKey` | string \| null | | | `data.lastSnapshotAt` | string \| null | | | `data.importSourceId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | ```json { "data": { "id": "app_3c4d5e6f7a8b9c0d", "spaceId": "space_1a2b3c4d5e6f7a8b", "appKey": "clock", "name": "Lobby clock", "config": { "format": "24h" }, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": 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: Missing `appKey`/`name`, invalid JSON config, unknown app (`unknown_app`), or a location outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/app-instances/{id} Get an app instance Retrieve one configured app instance, including its full configuration. Auth: Bearer token. Permission: `app-instance.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | ```bash curl "https://api.brixsignage.com/v1/app-instances/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AppInstance | An installed, configured app. | | `data.id` | string | App instance id. | | `data.spaceId` | string | Workspace id. | | `data.appKey` | string | The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …). | | `data.name` | string | | | `data.config` | any | The app's settings (JSON). The keys depend on `appKey`. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.lastSnapshotKey` | string \| null | Internal key of the last rendered thumbnail. | | `data.lastSnapshotAt` | string \| null | | | `data.importSourceId` | string \| null | Id in the system it was imported from, if imported. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | 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 app instance in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/app-instances/{id} Update an app instance Edit a configured app's name, configuration, or node. `config` replaces the entire configuration, so read the current value first before submitting changes. Auth: Bearer token. Permission: `app-instance.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `appKey` | string | no | A key from `GET /v1/apps/catalog`. An unknown key is refused (422 `unknown_app`). | | `name` | string | no | | | `config` | object \| string | no | The app's settings: a JSON object, or the same as a JSON string. Default `{}`. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `baseUpdatedAt` | string | no | Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/app-instances/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AppInstance | An installed, configured app. | | `data.id` | string | App instance id. | | `data.spaceId` | string | Workspace id. | | `data.appKey` | string | The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …). | | `data.name` | string | | | `data.config` | any | The app's settings (JSON). The keys depend on `appKey`. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.lastSnapshotKey` | string \| null | Internal key of the last rendered thumbnail. | | `data.lastSnapshotAt` | string \| null | | | `data.importSourceId` | string \| null | Id in the system it was imported from, if imported. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | 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 app instance in this workspace. Response 409: `conflict`: the row changed since `baseUpdatedAt`; the body carries `current`. Response 422: Invalid JSON config or unknown app. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/app-instances/{id} Delete an app instance Delete a configured app instance. Screens and playlists that reference it stop showing it. Auth: Bearer token. Permission: `app-instance.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | | `force` | query | "true" | no | Delete even when it is shared into other places; the shares go with it. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/app-instances/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | Shares removed with it. | 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 app instance in this workspace. Response 409: `content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/app-instances/{id}/duplicate Duplicate an app instance Create a copy of a configured app instance, including its configuration and home node, named " copy". Use this to reuse a tuned configuration instead of re-entering it. Requires permission to create app instances at the source instance's node. **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. Auth: Bearer token. Permission: `app-instance.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | ```bash curl -X POST "https://api.brixsignage.com/v1/app-instances/{id}/duplicate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | App instance id. | | `data.spaceId` | string | Workspace id. | | `data.appKey` | string | The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …). | | `data.name` | string | | | `data.config` | any | The app's settings (JSON). The keys depend on `appKey`. | | `data.nodeId` | string \| null | Home location, when one was set or derived. | | `data.lastSnapshotKey` | string \| null | | | `data.lastSnapshotAt` | string \| null | | | `data.importSourceId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | 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 app instance in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/app-instances/{id}/restore Restore a deleted app instance Restore an app instance that was deleted within the last 30 days. The shares removed by the delete come back. Playlist items removed by the delete do not come back; add the app to those playlists again. Auth: Bearer token. Permission: `app-instance.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | ```bash curl -X POST "https://api.brixsignage.com/v1/app-instances/{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 app instance in this workspace, or it was purged. Response 409: `not_deleted`: it is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/app-instances/{id}/thumbnail Get an app instance thumbnail Retrieve a shared preview image of an app instance. The same image is reused everywhere the app is previewed, so it loads quickly. Add `?fresh=1` to force a new image to be generated after a configuration change. **Notes.** - A cached image is `image/jpeg`. When there is none yet, the answer is a neutral `image/svg+xml` placeholder (header `x-brix-cache: pending`, not cached) while the image is drawn in the background; fetch it again shortly. Auth: Bearer token. Permission: `app-instance.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | App instance id. | | `fresh` | query | "1" | no | Skip the cached image and draw it again. | ```bash curl "https://api.brixsignage.com/v1/app-instances/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 app instance in this workspace. Response 503: `browser_unavailable`: images cannot be drawn in this environment. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Approvals 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/approvals List approval requests the caller is allowed to see, newest first. Use `?state=` to narrow the list to requests still awaiting a decision. The response is capped because approval history only grows over time. Newest first. The route needs `screen.view`, but each request is listed only if the caller can also view (or approve) that content kind at its location — e.g. `playlist.view` for a playlist. A `screen.view`-only key gets an empty list. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `state` | query | "pending" \| "approved" \| "rejected" \| "withdrawn" | no | Only requests in this state (`pending` = the inbox). | | `limit` | query | integer | no | At most this many (default and max 500). | ```bash curl "https://api.brixsignage.com/v1/approvals" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of ApprovalRequest | | | `data[].id` | string | Approval request id. | | `data[].contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data[].contentId` | string | | | `data[].contentName` | string | | | `data[].thumbnailUrl` | string \| null | | | `data[].nodeId` | string | The content's home location; empty string for the workspace root. | | `data[].nodeName` | string | | | `data[].requestedByName` | string | | | `data[].requestedAt` | string | ISO-8601 timestamp (UTC). | | `data[].note` | string \| null | | | `data[].changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data[].state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data[].requestedById` | string | User id, or `apikey:` for a key. | | `data[].levels` | array of object | The approval chain, one entry per tier. | | `data[].levels[].nodeId` | string | | | `data[].levels[].nodeName` | string | | | `data[].levels[].approverIds` | array of string | | | `data[].levels[].approverNames` | array of string | | | `data[].currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data[].decisions` | array of object | | | `data[].decisions[].level` | integer | | | `data[].decisions[].decidedById` | string | | | `data[].decisions[].decidedByName` | string \| null | | | `data[].decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data[].decisions[].note` | string \| null | | | `data[].decidedByName` | string \| null | | | `data[].decidedAt` | string \| null | | | `data[].decisionNote` | string \| null | | | `data[].canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | 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/approvals Request approval for content Open an approval request for a piece of content. The authenticated caller becomes the requester. Decide the request with POST /v1/approvals/:id/decide, or cancel it with POST /v1/approvals/:id/withdraw. **Notes.** - The request goes to the content's own location; a `nodeId` in the body is ignored. The content's review state becomes `pending`. - The requester is the caller (`apikey:` for a key). Auth: Bearer token. Permission: `screen.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `contentKind` | string | yes | `playlist`, `schedule`, `creative`, `layout`, `media`, `app`, … | | `contentId` | string | yes | | | `contentName` | string | yes | | | `note` | string | no | | | `thumbnailUrl` | string | no | | | `changes` | array of any | no | Used only for content kinds the server does not compare itself. | ```bash curl -X POST "https://api.brixsignage.com/v1/approvals" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contentKind":"playlist","contentId":"pl_2b3c4d5e6f7a8b9c","contentName":"Lobby Loop","note":"New spring menu"}' ``` Response 200: Success: A request for this content is already pending: that request is returned and nothing is created. | Field | Type | Description | | --- | --- | --- | | `data` | ApprovalRequest | A request to approve content before it can air. | | `data.id` | string | Approval request id. | | `data.contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data.contentId` | string | | | `data.contentName` | string | | | `data.thumbnailUrl` | string \| null | | | `data.nodeId` | string | The content's home location; empty string for the workspace root. | | `data.nodeName` | string | | | `data.requestedByName` | string | | | `data.requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.note` | string \| null | | | `data.changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data.state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data.requestedById` | string | User id, or `apikey:` for a key. | | `data.levels` | array of object | The approval chain, one entry per tier. | | `data.levels[].nodeId` | string | | | `data.levels[].nodeName` | string | | | `data.levels[].approverIds` | array of string | | | `data.levels[].approverNames` | array of string | | | `data.currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data.decisions` | array of object | | | `data.decisions[].level` | integer | | | `data.decisions[].decidedById` | string | | | `data.decisions[].decidedByName` | string \| null | | | `data.decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data.decisions[].note` | string \| null | | | `data.decidedByName` | string \| null | | | `data.decidedAt` | string \| null | | | `data.decisionNote` | string \| null | | | `data.canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ApprovalRequest | A request to approve content before it can air. | | `data.id` | string | Approval request id. | | `data.contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data.contentId` | string | | | `data.contentName` | string | | | `data.thumbnailUrl` | string \| null | | | `data.nodeId` | string | The content's home location; empty string for the workspace root. | | `data.nodeName` | string | | | `data.requestedByName` | string | | | `data.requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.note` | string \| null | | | `data.changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data.state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data.requestedById` | string | User id, or `apikey:` for a key. | | `data.levels` | array of object | The approval chain, one entry per tier. | | `data.levels[].nodeId` | string | | | `data.levels[].nodeName` | string | | | `data.levels[].approverIds` | array of string | | | `data.levels[].approverNames` | array of string | | | `data.currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data.decisions` | array of object | | | `data.decisions[].level` | integer | | | `data.decisions[].decidedById` | string | | | `data.decisions[].decidedByName` | string \| null | | | `data.decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data.decisions[].note` | string \| null | | | `data.decidedByName` | string \| null | | | `data.decidedAt` | string \| null | | | `data.decisionNote` | string \| null | | | `data.canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | Response 401: Missing, expired or revoked bearer token. Response 403: The content is approved, and you do not hold its approve permission (`playlist.approve`, …) at its location. Response 404: No such content, or it is at a location where you do not hold `screen.view`. Response 422: `contentKind`, `contentId` or `contentName` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/approvals/{id} Get an approval request Retrieve one approval request. If the request falls outside what you are allowed to see, this returns 404 rather than 403, so its existence is not revealed. **Notes.** - Besides `screen.view`, the caller must be able to view or approve the content kind at its location (e.g. `playlist.view`); otherwise 404. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Approval request id. | ```bash curl "https://api.brixsignage.com/v1/approvals/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ApprovalRequest | A request to approve content before it can air. | | `data.id` | string | Approval request id. | | `data.contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data.contentId` | string | | | `data.contentName` | string | | | `data.thumbnailUrl` | string \| null | | | `data.nodeId` | string | The content's home location; empty string for the workspace root. | | `data.nodeName` | string | | | `data.requestedByName` | string | | | `data.requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.note` | string \| null | | | `data.changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data.state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data.requestedById` | string | User id, or `apikey:` for a key. | | `data.levels` | array of object | The approval chain, one entry per tier. | | `data.levels[].nodeId` | string | | | `data.levels[].nodeName` | string | | | `data.levels[].approverIds` | array of string | | | `data.levels[].approverNames` | array of string | | | `data.currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data.decisions` | array of object | | | `data.decisions[].level` | integer | | | `data.decisions[].decidedById` | string | | | `data.decisions[].decidedByName` | string \| null | | | `data.decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data.decisions[].note` | string \| null | | | `data.decidedByName` | string \| null | | | `data.decidedAt` | string \| null | | | `data.decisionNote` | string \| null | | | `data.canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | 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 request, or you cannot view (or approve) that kind of content at its location. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/approvals/{id}/decide Approve or reject content Approve or reject a pending approval request. A reason is required when rejecting. The decision is applied to the underlying content's approval status. Decides the CURRENT level of the chain. Approving the last level lets the content air; approving an earlier level passes it to the next. Besides `screen.view`, the caller must be a named approver for the level or hold the content kind's approve permission (`playlist.approve`, `schedule.approve`, …) at the level's location. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Approval request id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `decision` | "approved" \| "rejected" | yes | | | `decisionNote` | string | no | Required to reject. | ```bash curl -X POST "https://api.brixsignage.com/v1/approvals/{id}/decide" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ApprovalRequest | A request to approve content before it can air. | | `data.id` | string | Approval request id. | | `data.contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data.contentId` | string | | | `data.contentName` | string | | | `data.thumbnailUrl` | string \| null | | | `data.nodeId` | string | The content's home location; empty string for the workspace root. | | `data.nodeName` | string | | | `data.requestedByName` | string | | | `data.requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.note` | string \| null | | | `data.changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data.state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data.requestedById` | string | User id, or `apikey:` for a key. | | `data.levels` | array of object | The approval chain, one entry per tier. | | `data.levels[].nodeId` | string | | | `data.levels[].nodeName` | string | | | `data.levels[].approverIds` | array of string | | | `data.levels[].approverNames` | array of string | | | `data.currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data.decisions` | array of object | | | `data.decisions[].level` | integer | | | `data.decisions[].decidedById` | string | | | `data.decisions[].decidedByName` | string \| null | | | `data.decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data.decisions[].note` | string \| null | | | `data.decidedByName` | string \| null | | | `data.decidedAt` | string \| null | | | `data.decisionNote` | string \| null | | | `data.canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | Response 401: Missing, expired or revoked bearer token. Response 403: Not eligible to decide this level, or `self_approval` (another approver exists). Response 404: No such request. Response 409: `already_decided`. Response 422: Bad `decision`, or a rejection without `decisionNote`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/approvals/{id}/withdraw Withdraw an approval request Cancel your own pending approval request. The content it was attached to returns to draft status. **Notes.** - The content's review state goes back to `draft`. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Approval request id. | ```bash curl -X POST "https://api.brixsignage.com/v1/approvals/{id}/withdraw" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ApprovalRequest | A request to approve content before it can air. | | `data.id` | string | Approval request id. | | `data.contentKind` | string | `playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, … | | `data.contentId` | string | | | `data.contentName` | string | | | `data.thumbnailUrl` | string \| null | | | `data.nodeId` | string | The content's home location; empty string for the workspace root. | | `data.nodeName` | string | | | `data.requestedByName` | string | | | `data.requestedAt` | string | ISO-8601 timestamp (UTC). | | `data.note` | string \| null | | | `data.changes` | array of any | What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent. | | `data.state` | "pending" \| "approved" \| "rejected" \| "withdrawn" | | | `data.requestedById` | string | User id, or `apikey:` for a key. | | `data.levels` | array of object | The approval chain, one entry per tier. | | `data.levels[].nodeId` | string | | | `data.levels[].nodeName` | string | | | `data.levels[].approverIds` | array of string | | | `data.levels[].approverNames` | array of string | | | `data.currentLevel` | integer | Index into `levels` awaiting a decision while pending. | | `data.decisions` | array of object | | | `data.decisions[].level` | integer | | | `data.decisions[].decidedById` | string | | | `data.decisions[].decidedByName` | string \| null | | | `data.decisions[].decidedAt` | string | ISO-8601 timestamp (UTC). | | `data.decisions[].note` | string \| null | | | `data.decidedByName` | string \| null | | | `data.decidedAt` | string \| null | | | `data.decisionNote` | string \| null | | | `data.canDecide` | boolean | On the list and single reads: whether the caller may approve or reject the request at its current level (a named approver, or the kind's approve permission there). False once it is decided. | Response 401: Missing, expired or revoked bearer token. Response 403: You are not the requester, and not an approver for the current level. Response 404: No such request. Response 409: `already_decided`: the request is no longer pending. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Apps 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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 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. **Notes.** - HTML for an iframe, with a strict content security policy; who may frame it is limited to Brix players and the console. Auth: none. Parameters: | Name | 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`). | ```bash 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 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. 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 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. **Notes.** - An unknown token answers 200 with `value: null`, not 404. Auth: none. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `token` | path | string | yes | The counter's control code (8–64 letters, digits, `_` or `-`), from the app's settings. | ```bash 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 action from the control page or a Next button. 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 the numbers start again 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} Update a live counter value 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 Now Serving action from the control page: 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. Auth: none. Parameters: | Name | 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. | ```bash 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 action from the control page or a Next button. 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 the numbers start again 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. ### POST /v1/apps/counter/{token}/button Get the Next button link of one counter Get the id of the Next button link for one counter of a Now Serving app. Send the button `key` of the counter from the app's settings. The same control code and key always give the same id. The link can only call the next number; it cannot read or change anything else. Access is controlled by the `token` in the URL. **Notes.** - The console calls this to show the link. The id does not contain the control code in readable form, and it only calls Next. Auth: none. Parameters: | Name | 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 | | --- | --- | --- | --- | | `key` | string | yes | The counter's button key from the app's `nextButtons` setting (16 letters and digits). | ```bash curl -X POST "https://api.brixsignage.com/v1/apps/counter/{token}/button" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | The button id for `/v1/apps/next/{buttonId}`. The same token and key always give the same id. | Response 400: `bad_token`, or `bad_key`: the key is not 16 letters and digits. Response 401: Missing, expired or revoked bearer token. Response 404: `unknown_token`: no saved Now Serving app uses this control code. Response 429: More than 60 requests a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/apps/counter/{token}/card Get the printable counter card Get an HTML page to print and keep behind the counter. For Now Serving it is an A6 card; for Goal Tracker it is a page with a QR code. The QR code opens the control page of the saved app. Access is controlled by the `token` in the URL. **Notes.** - Now Serving: the A6 card to keep behind the counter. 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. Auth: none. Parameters: | Name | 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`). | ```bash 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 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 | 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. | ```bash 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 Get the shop logo for a control code Get the logo from the Brand settings of the workspace that owns the app. The phone pages and the printable card show this image. Access is controlled by the `token` in the URL. Auth: none. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `token` | path | string | yes | The counter's control code (8–64 letters, digits, `_` or `-`), from the app's settings. | ```bash 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/next/{buttonId} Call the next number for one counter (Wi-Fi button) Call the next number for the counter that this button link belongs to. Use it for a Wi-Fi button that can only send a GET request. The answer gives the number called, the counter and how many customers wait. A link-preview robot gets an empty answer and nothing changes. Access is controlled by the button id in the URL. **Notes.** - For a button that can only send a GET request (Shelly). A link-preview robot (WhatsApp, Slack and others) gets 204 and nothing changes. - The link stops when the owner makes a new link for that counter, removes it, removes or renames the counter, or makes a new control code. Auth: none. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `buttonId` | path | string | yes | A Next button id from the app's settings: the control code and one counter's button key, sealed with a server key (base64url). | ```bash curl "https://api.brixsignage.com/v1/apps/next/{buttonId}" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.n` | integer | The number this press called. | | `data.counter` | string \| null | The counter of the button, or null for a shop with no counters. | | `data.waiting` | integer | How many customers still wait (phone queue); 0 otherwise. | Response 401: Missing, expired or revoked bearer token. Response 404: `not_found`: the id does not open, or the app no longer holds this key for a counter in its list. Response 409: `too_soon`: the same counter called less than 1 second ago; `nobody_waiting`: phone queue and nobody waits. Response 429: More than 30 presses a minute from one address. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/apps/next/{buttonId} Call the next number for one counter (Wi-Fi button, POST) Call the next number for the counter that this button link belongs to. This is the same call as the GET, for a Wi-Fi button that sends a POST request. The body is ignored. Access is controlled by the button id in the URL. **Notes.** - The same call as the GET, for a button that sends a POST request (Flic). The body is ignored. Auth: none. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `buttonId` | path | string | yes | A Next button id from the app's settings: the control code and one counter's button key, sealed with a server key (base64url). | ```bash curl -X POST "https://api.brixsignage.com/v1/apps/next/{buttonId}" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.n` | integer | The number this press called. | | `data.counter` | string \| null | The counter of the button, or null for a shop with no counters. | | `data.waiting` | integer | How many customers still wait (phone queue); 0 otherwise. | Response 401: Missing, expired or revoked bearer token. Response 404: `not_found`: the id does not open, or the app no longer holds this key for a counter in its list. Response 409: `too_soon`: the same counter called less than 1 second ago; `nobody_waiting`: phone queue and nobody waits. Response 429: More than 30 presses a minute from one address. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/apps/queue/{joinId} Get the take-a-number page 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. Auth: none. Parameters: | Name | 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`). | ```bash 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 Cancel a ticket Give a queue number back. The place is free at once: the screen and the control 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. Auth: none. Parameters: | Name | 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. | ```bash 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 Get the shop logo for a join id Get the logo from the Brand settings of the workspace that owns the app. The take-a-number page shows this image. Access is controlled by the join id in the URL. Auth: none. Parameters: | Name | 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). | ```bash 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 queue state for a customer 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. Auth: none. Parameters: | Name | 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. | ```bash 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 the numbers start again 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 Take a number 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. Auth: none. Parameters: | Name | 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). | ```bash 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. ## Audit 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/audit List activity log events Returns the workspace's append-only activity log, newest first, with each event's actor shown by name rather than raw id, whether the actor was a person, an API key, or the system. Page with `limit` and `cursor`; `nextCursor` sits beside `data`. There are no filters: use the export for a time window. A caller limited to some locations sees only the events at those locations. **Notes.** - Newest first. There are no filters: page with `cursor`. - A caller limited to some locations sees only events at those locations, so a page can hold fewer than `limit` events while `nextCursor` is still set. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | integer | no | Page size (default 200, max 500). | | `cursor` | query | string | no | `nextCursor` of the previous page. | ```bash curl "https://api.brixsignage.com/v1/audit" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of AuditEvent | | | `data[].id` | string | | | `data[].at` | string | ISO-8601 timestamp (UTC). | | `data[].workspaceId` | string | | | `data[].actor` | string | `user:`, `apikey:`, `system`, `staff` (our support team), or another internal actor. | | `data[].actorKind` | "user" \| "api-key" \| "system" \| "brix-support" \| "support" | Our support team made the change: `support` in a workspace a white-label partner owns, `brix-support` otherwise. | | `data[].actorName` | string | The person's or key's name; `System` for the system; the support team's name for `support` / `brix-support`. | | `data[].actorEmail` | string | The person's email; `n/a` for a key; `system@brix` for the system (`system` in a white-label partner's workspace); empty for `support` / `brix-support`. | | `data[].action` | string | What happened, e.g. `screen.renamed`. | | `data[].target` | string \| null | The id of the thing acted on. | | `data[].detail` | string \| null | | | `data[].nodeId` | string \| null | The location the event belongs to; null for the workspace. | | `data[].nodeName` | string \| null | | | `data[].ipAddress` | string \| null | | | `data[].userAgent` | string \| null | | | `data[].via` | "mcp" \| "api" \| null | How it arrived: `mcp` (an MCP tool such as Claude or ChatGPT), `api` (an API key on REST), null (in the Brix app). | | `data[].viaApp` | string \| null | The connector or API key behind an `mcp`/`api` event; null for the app. | | `nextCursor` | string \| null | Pass as `cursor` for the next (older) page; null on the last page. | 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/audit Add activity log event Appends one client event to the workspace's activity log, for example that a help panel was opened. The `action` must be in the `cms.` namespace, so only events of that kind can be added this way. The actor is always the caller, never taken from the request body. The activity log is append-only: events can be added but never updated or deleted. Limited to 120 events a minute. **Notes.** - Needs only `audit-log.view`. The actor is always the caller; `ipAddress` and `userAgent` come from the request. Auth: Bearer token. Permission: `audit-log.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `action` | string | yes | Must be in the `cms.` namespace: `cms.` then lower-case letters, digits, `.`, `_` or `-` (up to 122 more characters). | | `target` | string | no | | | `detail` | string | no | | | `nodeId` | string \| null | no | A location you can see. | ```bash curl -X POST "https://api.brixsignage.com/v1/audit" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | AuditEvent | One activity log event, with the actor resolved to a name. | | `data.id` | string | | | `data.at` | string | ISO-8601 timestamp (UTC). | | `data.workspaceId` | string | | | `data.actor` | string | `user:`, `apikey:`, `system`, `staff` (our support team), or another internal actor. | | `data.actorKind` | "user" \| "api-key" \| "system" \| "brix-support" \| "support" | Our support team made the change: `support` in a workspace a white-label partner owns, `brix-support` otherwise. | | `data.actorName` | string | The person's or key's name; `System` for the system; the support team's name for `support` / `brix-support`. | | `data.actorEmail` | string | The person's email; `n/a` for a key; `system@brix` for the system (`system` in a white-label partner's workspace); empty for `support` / `brix-support`. | | `data.action` | string | What happened, e.g. `screen.renamed`. | | `data.target` | string \| null | The id of the thing acted on. | | `data.detail` | string \| null | | | `data.nodeId` | string \| null | The location the event belongs to; null for the workspace. | | `data.nodeName` | string \| null | | | `data.ipAddress` | string \| null | | | `data.userAgent` | string \| null | | | `data.via` | "mcp" \| "api" \| null | How it arrived: `mcp` (an MCP tool such as Claude or ChatGPT), `api` (an API key on REST), null (in the Brix app). | | `data.viaApp` | string \| null | The connector or API key behind an `mcp`/`api` event; null for the app. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `action` is missing or outside the `cms.` namespace, or `nodeId` is not a location you can see. Response 429: More than 120 events a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/audit/export Export activity log feed Returns the activity log as a feed suitable for a log collector or SIEM tool. Unlike the regular activity log listing, results are returned oldest first, so a collector can page forward from a saved position without missing or re-reading events. Returns newline-delimited JSON by default; pass `?format=json` for a human-readable array. Use the `from` and `to` parameters for a half-open time window, and the `x-brix-next-cursor` and `x-brix-has-more` response headers to page through results. **Notes.** - Oldest first. The default body is NDJSON: one `AuditEvent` object per line. The next-page cursor is in the `X-Brix-Next-Cursor` header (empty on the last page) and `X-Brix-Has-More` is `1` or `0`. - With `format=json` the body is JSON: `{ data: AuditEvent[], nextCursor: string | null }`. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | integer | no | Page size (default 500, max 1000). | | `cursor` | query | string | no | The `X-Brix-Next-Cursor` header (or `nextCursor`) of the previous page. | | `from` | query | string | no | ISO-8601; events at or after this time. | | `to` | query | string | no | ISO-8601; events before this time. | | `format` | query | "json" | no | `json` answers `{ data: AuditEvent[], nextCursor }` instead of NDJSON. | ```bash curl "https://api.brixsignage.com/v1/audit/export" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `from` or `to` is not an ISO-8601 timestamp. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/audit/integrity Get activity log integrity chain Returns the tamper-evidence chain for the workspace's activity log: a digest to record for later comparison, and the daily checkpoints behind it. Each complete UTC day of events is combined into one checkpoint linked to the day before. The current, still-open day is deliberately not yet included, since a checkpoint over data still being written would have to be recalculated. Auth: Bearer token. Permission: `audit-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | integer | no | Checkpoints to return, newest first (default 90, max 400). | ```bash curl "https://api.brixsignage.com/v1/audit/integrity" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.latestDigest` | string \| null | The value to record. Null before the first day is covered. | | `data.coveredThrough` | string \| null | The end of the last covered day. | | `data.canonicalVersion` | string | The newest row encoding the hashes use (`3`). Each checkpoint names its own in `leafVersion`. | | `data.note` | string | | | `data.checkpoints` | array of object | | | `data.checkpoints[].seq` | integer | | | `data.checkpoints[].periodStart` | string | ISO-8601 timestamp (UTC). | | `data.checkpoints[].periodEnd` | string | ISO-8601 timestamp (UTC). | | `data.checkpoints[].rowCount` | integer | | | `data.checkpoints[].firstEventId` | string \| null | | | `data.checkpoints[].lastEventId` | string \| null | | | `data.checkpoints[].merkleRoot` | string | | | `data.checkpoints[].leafVersion` | string \| null | The row encoding this checkpoint's root was taken over. `3`: every field escaped (backslash as `\\`, U+001F as `\u`) and joined on U+001F, `via` last. Null: a checkpoint written before version 3, whose rows are joined unescaped, each starting with its own version (`1` with no `via`, `2` with `via` last). | | `data.checkpoints[].prevDigest` | string | The previous checkpoint's digest, or `genesis`. | | `data.checkpoints[].digest` | string | | 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/audit/integrity/verify Verify activity log integrity Re-reads every event behind the integrity chain and recomputes it, to prove the activity log has not been altered since a digest was recorded. Returns HTTP 200 with `ok: false` when verification fails, rather than an error status, so a monitoring script can distinguish "the log was altered" from "the check itself failed". This is rate-limited because it re-reads the full log. **Notes.** - Answers 200 with `ok: false` when verification fails. Auth: Bearer token. Permission: `audit-log.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | no | Checkpoints to check, newest first (default 90). | ```bash curl -X POST "https://api.brixsignage.com/v1/audit/integrity/verify" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.checkpoints` | array of object | | | `data.checkpoints[].id` | string | | | `data.checkpoints[].seq` | integer | | | `data.checkpoints[].periodStart` | string | ISO-8601 timestamp (UTC). | | `data.checkpoints[].periodEnd` | string | ISO-8601 timestamp (UTC). | | `data.checkpoints[].storedRowCount` | integer | | | `data.checkpoints[].actualRowCount` | integer | | | `data.checkpoints[].recomputedRoot` | string \| null | | | `data.checkpoints[].rootMatches` | boolean | | | `data.checkpoints[].digestMatches` | boolean | | | `data.checkpoints[].chainIntact` | boolean | | | `data.checkpoints[].ok` | boolean | | | `data.ok` | boolean | False when any checkpoint failed: the log was changed. | | `data.latestDigest` | 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 429: More than 10 checks in 5 minutes. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Banners 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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 List banners 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. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | 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). | ```bash 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 Create a banner 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. Auth: Bearer token. Permission: `integration.create`. 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. | ```bash 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} Get a banner Retrieve one announcement banner. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Banner id. | ```bash 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} Update a banner Edit an announcement banner's title, body, tone, audience, or active state. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | 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. | ```bash 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} Delete a banner Delete an announcement banner. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Banner id. | ```bash 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 Restore a banner Restore a previously deleted announcement banner so it is active again. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Banner id. | ```bash 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. ## Billing groups 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/billing-groups List billing groups Returns the workspace's billing groups (who pays for which screens), each with its current count of billable screens. **Notes.** - Sorted by name; not paginated. Unlike the single read, list rows have no `createdAt` / `updatedAt`. Auth: Bearer token. Permission: `billing.view`. ```bash curl "https://api.brixsignage.com/v1/billing-groups" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].name` | string | | | `data[].financeContactName` | string \| null | | | `data[].financeContactEmail` | string \| null | Where this group's invoices go. | | `data[].chargebeeCustomerId` | string \| null | The billing customer linked by Brix; null until linked. | | `data[].chargebeeSubscriptionId` | string \| null | The subscription linked by Brix; null until linked. | | `data[].subscriptionStatus` | string \| null | | | `data[].paymentTermsDays` | integer \| null | Net payment terms in days; null = the workspace default. | | `data[].screenCount` | integer | Screens billed to this group. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/billing-groups Create billing group Creates a billing group with a name and finance contact. Connecting it to an account with the billing provider is a separate step; one is never created automatically here. **Notes.** - The group bills nothing until Brix links it to a billing account. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `financeContactName` | string | no | | | `financeContactEmail` | string | no | Stored in lower case. | | `paymentTermsDays` | number | no | Net terms in days; rounded. Not range-checked on create. | ```bash curl -X POST "https://api.brixsignage.com/v1/billing-groups" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | BillingGroup | A group of screens billed separately (its own invoice and finance contact). | | `data.id` | string | | | `data.name` | string | | | `data.financeContactName` | string \| null | | | `data.financeContactEmail` | string \| null | Where this group's invoices go. | | `data.chargebeeCustomerId` | string \| null | The billing customer linked by Brix; null until linked. | | `data.chargebeeSubscriptionId` | string \| null | The subscription linked by Brix; null until linked. | | `data.subscriptionStatus` | string \| null | | | `data.paymentTermsDays` | integer \| null | Net payment terms in days; null = the workspace default. | | `data.screenCount` | integer | Screens billed to this group. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 422: `name` missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/billing-groups/{id} Get billing group Returns one billing group by id. Auth: Bearer token. Permission: `billing.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Billing group id. | ```bash curl "https://api.brixsignage.com/v1/billing-groups/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | BillingGroup | A group of screens billed separately (its own invoice and finance contact). | | `data.id` | string | | | `data.name` | string | | | `data.financeContactName` | string \| null | | | `data.financeContactEmail` | string \| null | Where this group's invoices go. | | `data.chargebeeCustomerId` | string \| null | The billing customer linked by Brix; null until linked. | | `data.chargebeeSubscriptionId` | string \| null | The subscription linked by Brix; null until linked. | | `data.subscriptionStatus` | string \| null | | | `data.paymentTermsDays` | integer \| null | Net payment terms in days; null = the workspace default. | | `data.screenCount` | integer | Screens billed to this group. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such group in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/billing-groups/{id} Update billing group Updates a billing group's name, finance contact, or invoice terms. **Notes.** - `paymentTermsDays` is range-checked here (1–365) but not on create. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Billing group id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `financeContactName` | string \| null | no | | | `financeContactEmail` | string \| null | no | | | `paymentTermsDays` | number \| null | no | 1–365, or null to use the workspace default. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/billing-groups/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | BillingGroup | A group of screens billed separately (its own invoice and finance contact). | | `data.id` | string | | | `data.name` | string | | | `data.financeContactName` | string \| null | | | `data.financeContactEmail` | string \| null | Where this group's invoices go. | | `data.chargebeeCustomerId` | string \| null | The billing customer linked by Brix; null until linked. | | `data.chargebeeSubscriptionId` | string \| null | The subscription linked by Brix; null until linked. | | `data.subscriptionStatus` | string \| null | | | `data.paymentTermsDays` | integer \| null | Net payment terms in days; null = the workspace default. | | `data.screenCount` | integer | Screens billed to this group. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such group. Response 422: Empty `name`, or `paymentTermsDays` outside 1–365. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/billing-groups/{id} Delete billing group Soft-deletes a billing group. Returns 409 if any screens are still billed to it; move or remove those screens first. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Billing group id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/billing-groups/{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: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such group. Response 409: `group_in_use`: screens still bill to it; move them first (`PATCH /v1/screens/:id` `billingGroupId`). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/billing-groups/{id}/screens Assign screens to billing group Assigns a batch of screens to a billing group. This updates the destination group, every group the screens are moving from, and the workspace subscription, so screen counts and billing stay in sync. Auth: Bearer token. Permission: `billing.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Billing group id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | yes | Up to 500 are read; more are ignored. Ids that are not live screens are skipped. | ```bash curl -X POST "https://api.brixsignage.com/v1/billing-groups/{id}/screens" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.assigned` | integer | Screens moved into the group. | | `data.skipped` | integer | Ids not moved (unknown, or already in the group). | | `data.screenCount` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: You lack `billing.edit` at one of the screens' locations (the response names them in `screenIds`); nothing changes. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough). Response 404: No such group, or none of the ids is a live screen. Response 422: `screenIds` missing or empty. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Casts 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/casts List casts, which are timed content takeovers, newest first. Use `?status=active` to filter to casts currently on air, and `?limit` (up to 500, default 200) to bound the number of results. Cast history is kept indefinitely. Auth: Bearer token. Permission: `screen.cast`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | "active" \| "cleared" \| "expired" | no | Only casts in this state. | | `limit` | query | integer | no | At most this many, newest first (default 200, max 500). | ```bash curl "https://api.brixsignage.com/v1/casts" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Override | | | `data[].id` | string | Override (cast_… or emg_…) id. | | `data[].spaceId` | string | Workspace id. | | `data[].kind` | "emergency" \| "cast" | | | `data[].status` | "active" \| "cleared" \| "expired" | | | `data[].severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data[].headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data[].body` | string \| null | | | `data[].contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data[].contentId` | string \| null | | | `data[].contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data[].scopeKind` | "all" \| "node" \| "screens" | | | `data[].scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data[].nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data[].screenCount` | integer | Screens targeted, snapshotted when it started. | | `data[].triggeredBy` | string | User id, or `system`. | | `data[].triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data[].expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data[].clearedBy` | string \| null | | | `data[].clearedAt` | string \| null | | | `data[].triggeredByName` | string | Display name of `triggeredBy`. | | `data[].clearedByName` | string \| null | | | `data[].scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data[].confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | ```json { "data": [ { "id": "cast_9f2c4a1b7d3e5f60", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "cast", "status": "active", "severity": "info", "headline": "Friday lunch special", "body": null, "contentKind": "media", "contentId": "med_0c1d2e3f4a5b6c7d", "contentName": "Friday lunch special", "scopeKind": "screens", "scopeNodeId": null, "nodeId": null, "screenCount": 2, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": "2026-09-28T13:30:00.000Z", "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": null, "confirmedCount": null } ] } ``` 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/casts Cast content to screens Put content on air across a set of screens for a period of time, after which the screens automatically revert to their normal content. Send `contentKind` (media, playlist, app, creative, or schedule), `contentId`, `scopeKind`, and optionally `scopeNodeId`, `screenIds`, and `expiresAt`. `scopeKind` accepts all, node, or screens and defaults to all: a request sent with no scope casts to every screen the caller can reach. An active emergency override takes priority over a cast, and the cast resumes automatically once the emergency is cleared. Puts one piece of content on the chosen screens now, above their schedule, until it expires or is cleared. An emergency still pre-empts a cast. Auth: Bearer token. Permission: `screen.cast`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `contentKind` | "media" \| "playlist" \| "app" \| "creative" \| "schedule" | yes | What kind of thing `contentId` names. | | `contentId` | string | yes | The media, playlist, app instance, creative or schedule to put on air. | | `contentName` | string | no | Label for the cast (shown in the console). Defaults to "Cast". | | `scopeKind` | "all" \| "node" \| "screens" | no | Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the cast goes to EVERY screen you can reach.** | | `scopeNodeId` | string | no | Location id, with `scopeKind: node`. | | `screenIds` | array of string | no | Screen ids, with `scopeKind: screens`. | | `expiresAt` | string \| number \| null | no | When the cast ends by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared. | ```bash curl -X POST "https://api.brixsignage.com/v1/casts" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contentKind":"media","contentId":"med_0c1d2e3f4a5b6c7d","contentName":"Friday lunch special","scopeKind":"screens","screenIds":["scr_1a2b3c4d5e6f7a8b","scr_2b3c4d5e6f7a8b9c"],"expiresAt":"2026-09-28T13:30:00.000Z"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | ```json { "data": { "id": "cast_9f2c4a1b7d3e5f60", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "cast", "status": "active", "severity": "info", "headline": "Friday lunch special", "body": null, "contentKind": "media", "contentId": "med_0c1d2e3f4a5b6c7d", "contentName": "Friday lunch special", "scopeKind": "screens", "scopeNodeId": null, "nodeId": null, "screenCount": 2, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": "2026-09-28T13:30:00.000Z", "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": null, "confirmedCount": null } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not shared to one or more target locations. Response 404: The content does not exist in this workspace. Response 422: Invalid body, the scope matched no screens you can reach (`no_screens`), or the content cannot play (empty playlist, unprocessed media). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/casts/{id}/clear End a cast immediately and return its screens to their scheduled content. Ends an active cast; its screens return to their scheduled content immediately. Auth: Bearer token. Permission: `screen.cast`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Cast id. | ```bash curl -X POST "https://api.brixsignage.com/v1/casts/{id}/clear" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | 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 cast in this workspace. Response 409: `already_inactive`: the cast is already cleared or expired. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Celebration entries 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/celebration-entries List celebration entries Return the roster of birthdays, anniversaries, and other occasions that the Celebrations app displays. **Notes.** - Only entries at locations the caller can see. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | 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). | ```bash curl "https://api.brixsignage.com/v1/celebration-entries" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of CelebrationEntry | | | `data[].id` | string | | | `data[].spaceId` | string | | | `data[].nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. | | `data[].sourceId` | string \| null | The data source it came from, if any. | | `data[].name` | string | | | `data[].photoUrl` | string \| null | | | `data[].occasionType` | "birthday" \| "anniversary" \| "custom" | | | `data[].occasionMonth` | integer \| null | 1–12. | | `data[].occasionDay` | integer \| null | 1–31. | | `data[].occasionYear` | integer \| null | The start year for an anniversary. | | `data[].department` | string \| null | | | `data[].title` | string \| null | | | `data[].location` | string \| null | | | `data[].customMessage` | string \| null | | | `data[].externalId` | string \| null | The id in the source system, for de-duplication. | | `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/celebration-entries Create a celebration entry Add an entry to the celebration roster. Requires name; also accepts occasionType, occasionMonth, occasionDay, occasionYear, photoUrl, department, title, location, customMessage, sourceId, and externalId, all optional. **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. Auth: Bearer token. Permission: `integration.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `sourceId` | string \| null | no | | | `photoUrl` | string \| null | no | | | `occasionType` | "birthday" \| "anniversary" \| "custom" | no | Default `birthday`. | | `occasionMonth` | integer \| null | no | | | `occasionDay` | integer \| null | no | | | `occasionYear` | integer \| null | no | | | `department` | string \| null | no | | | `title` | string \| null | no | | | `location` | string \| null | no | | | `customMessage` | string \| null | no | | | `externalId` | string \| null | no | | | `nodeId` | string \| null | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/celebration-entries" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Sam Rivera","occasionType":"birthday","occasionMonth":10,"occasionDay":4,"department":"Kitchen"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. | | `data.sourceId` | string \| null | The data source it came from, if any. | | `data.name` | string | | | `data.photoUrl` | string \| null | | | `data.occasionType` | "birthday" \| "anniversary" \| "custom" | | | `data.occasionMonth` | integer \| null | 1–12. | | `data.occasionDay` | integer \| null | 1–31. | | `data.occasionYear` | integer \| null | The start year for an anniversary. | | `data.department` | string \| null | | | `data.title` | string \| null | | | `data.location` | string \| null | | | `data.customMessage` | string \| null | | | `data.externalId` | string \| null | The id in the source system, for de-duplication. | | `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: You do not hold `integration.create` at the location. Response 422: `name` is missing, or a location or data source outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/celebration-entries/{id} Get a celebration entry Return one entry from the celebration roster. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Celebration entry id. | ```bash curl "https://api.brixsignage.com/v1/celebration-entries/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | CelebrationEntry | A person's birthday, work anniversary or other occasion for the Celebrations app. | | `data.id` | string | | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. | | `data.sourceId` | string \| null | The data source it came from, if any. | | `data.name` | string | | | `data.photoUrl` | string \| null | | | `data.occasionType` | "birthday" \| "anniversary" \| "custom" | | | `data.occasionMonth` | integer \| null | 1–12. | | `data.occasionDay` | integer \| null | 1–31. | | `data.occasionYear` | integer \| null | The start year for an anniversary. | | `data.department` | string \| null | | | `data.title` | string \| null | | | `data.location` | string \| null | | | `data.customMessage` | string \| null | | | `data.externalId` | string \| null | The id in the source system, for de-duplication. | | `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 entry in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/celebration-entries/{id} Update a celebration entry Edit one entry in the celebration roster. Accepts any of the fields used when creating an entry. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Celebration entry id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `sourceId` | string \| null | no | | | `photoUrl` | string \| null | no | | | `occasionType` | "birthday" \| "anniversary" \| "custom" | no | Default `birthday`. | | `occasionMonth` | integer \| null | no | | | `occasionDay` | integer \| null | no | | | `occasionYear` | integer \| null | no | | | `department` | string \| null | no | | | `title` | string \| null | no | | | `location` | string \| null | no | | | `customMessage` | string \| null | no | | | `externalId` | string \| null | no | | | `nodeId` | string \| null | no | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/celebration-entries/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | CelebrationEntry | A person's birthday, work anniversary or other occasion for the Celebrations app. | | `data.id` | string | | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. | | `data.sourceId` | string \| null | The data source it came from, if any. | | `data.name` | string | | | `data.photoUrl` | string \| null | | | `data.occasionType` | "birthday" \| "anniversary" \| "custom" | | | `data.occasionMonth` | integer \| null | 1–12. | | `data.occasionDay` | integer \| null | 1–31. | | `data.occasionYear` | integer \| null | The start year for an anniversary. | | `data.department` | string \| null | | | `data.title` | string \| null | | | `data.location` | string \| null | | | `data.customMessage` | string \| null | | | `data.externalId` | string \| null | The id in the source system, for de-duplication. | | `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: You do not hold `integration.edit` at the destination location. Response 404: No such entry in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/celebration-entries/{id} Delete a celebration entry Remove an entry from the celebration roster. The entry moves to the recycle bin and can be brought back with the restore operation. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Celebration entry id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/celebration-entries/{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 entry in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/celebration-entries/{id}/restore Restore a celebration entry Bring back a deleted celebration entry so it appears again in the celebration app's roster. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Celebration entry id. | ```bash curl -X POST "https://api.brixsignage.com/v1/celebration-entries/{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 entry in this workspace, or it was purged. Response 409: `not_deleted`: the entry is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Connected apps 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/connected-apps List connected apps Returns the AI assistants and other MCP clients that people in this workspace connected with OAuth: the client, who connected it, its permissions, the location it is pinned to, and when it was last used. You see a connection only where you hold the permission to view API keys at its location. **Notes.** - Newest first. Only connections whose location the caller can see with `api-key.view` are listed. Auth: Bearer token. Permission: `api-key.view`. ```bash curl "https://api.brixsignage.com/v1/connected-apps" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | Connection id. | | `data[].clientId` | string | | | `data[].clientName` | string | The app's name, as it registered. | | `data[].redirectHost` | string \| null | The host the app signs in through. | | `data[].connectedBy` | object \| null | The person who approved it; null if they no longer exist. | | `data[].permissions` | "all" \| array of string | | | `data[].nodeId` | string \| null | The location the connection is limited to; null for the whole workspace. | | `data[].lastUsedAt` | string \| null | | | `data[].connectedAt` | string | ISO-8601 timestamp (UTC). | | `data[].recent` | array of object \| null | The connection's latest actions (up to 5), newest first. Null without `audit-log.view`. | 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. ### DELETE /v1/connected-apps/{id} Disconnect connected app Disconnects an app that was connected with OAuth. Its access stops immediately. You must hold the permission to delete API keys at the location the connection is pinned to. **Notes.** - Answers the same for a connection that was already revoked. Auth: Bearer token. Permission: `api-key.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Connection id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/connected-apps/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.revoked` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `api-key.delete` where the connection is limited to. Response 404: No such connection in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Connectors 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/connectors List connector types List the data-source connector types: the `type` to use when you create a data source, its label and category, and whether it is available yet. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/connectors" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Connector | | | `data[].type` | string | The value for a data source's `type` (`http-json`, `csv`, `google-sheets`, …). | | `data[].label` | string | | | `data[].category` | string | Group the connector is listed under (`generic`, `celebrations`, …). | | `data[].available` | boolean | False for a connector that is listed as coming soon and cannot be used yet. | 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/connectors/probe Test a connector URL Test whether the platform can reach a given endpoint, behind the Test connection action used before creating a data source. The request is made from the server rather than the browser. Requests to private or internal network addresses are blocked. Sends a GET to the URL from the server and returns the status and the start of the body. Rate limited to 20 calls a minute. **Notes.** - A URL that cannot be reached is not an HTTP error: the answer is 200 with `ok: false`, `status: 0` and `error`. - A blocked private or internal address answers 400 with the `{ data: { ok: false, status: 0, error } }` body, not the usual error body. Auth: Bearer token. Permission: `integration.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | yes | An http(s) URL on the public internet. | | `token` | string | no | Sent as `Authorization: Bearer `. Not stored. | ```bash curl -X POST "https://api.brixsignage.com/v1/connectors/probe" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 400: `bad_request`: the URL is not http(s). A private or internal address also answers 400, with the `data` body (`ok: false`, `status: 0`, `error`) instead of an error body. Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 20 calls in a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Content folders 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/content-folders List content folders List the folders of the Designs, Playlists and Layouts lists. Set `kind` to `design`, `playlist` or `layout` to get the folders of one list. Without `kind`, the answer contains the folders of each list that you have permission to view. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/content-folders" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/content-folders Create a content folder Create a folder in the Designs, Playlists or Layouts list. Send `kind` and `name`. Send `parentId` to put the folder inside a different folder; folders can be 4 levels deep. A folder only files items. It does not change who can see an item or what plays on a screen. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/content-folders" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/content-folders/{id} Get a content folder Get one folder of the Designs, Playlists or Layouts list. A folder in a different workspace, or in a part of the workspace that you cannot access, returns a not-found error. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl "https://api.brixsignage.com/v1/content-folders/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/content-folders/{id} Update a content folder Rename a folder, move it into a different folder, or file items. Send the ids of items of the same kind as the folder in `addItems` to put them in the folder, or in `removeItems` to take them out. You can file at most 500 items in one call. You need edit permission on each item that you file. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/content-folders/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/content-folders/{id} Delete a content folder Move a folder and its subfolders to the recycle bin. The items in them are not deleted; they move up to the parent of the deleted folder. The folder stays in the recycle bin for 30 days. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/content-folders/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/content-folders/{id}/restore Restore a deleted content folder Restore a folder from the recycle bin together with its subfolders. The items that the delete moved up go back into the folder, unless they are in a different folder now. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/content-folders/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Creative overrides 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/creative-overrides/{creativeId} Get a creative's overrides at a location Return the edits a location has made to a creative that was shared with it, the merged result of applying those edits, and any edits that have stopped applying. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `creativeId` | path | string | yes | Creative id: one of yours, or one shared into this workspace. | | `node` | query | string | no | Location id. Default: the workspace root. | | `view` | query | "values" | no | `values`: leave out `creative` and `base` (the two full designs) and add `editable`. For setting prices from a script or an AI tool. | ```bash curl "https://api.brixsignage.com/v1/creative-overrides/{creativeId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.creativeId` | string | | | `data.nodeId` | string | The location the edits apply at. | | `data.values` | object | The location's edits: box id → the box fields it changes (for example `{ "price": { "text": "13.00" } }`). | | `data.overrideId` | string \| null | Id of the stored edits (what an approval request is opened against); null before the first save. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state of the edits (not of the design). | | `data.requiresApproval` | boolean | The location requires approval before the edits air. | | `data.skipsApproval` | boolean | The author waived that review for this design. | | `data.creative` | OverrideCreative | A creative's design: the boxes and scenes with their settings. | | `data.creative.id` | string | | | `data.creative.nodeId` | string \| null | | | `data.creative.name` | string | | | `data.creative.backgroundUrl` | string \| null | | | `data.creative.boxes` | array of object | | | `data.creative.scenes` | array of object | | | `data.creative.dataSourceId` | string \| null | | | `data.creative.stage` | string | Absent when not set. | | `data.creative.shareLockDefault` | any \| null | | | `data.creative.shareEditsSkipApproval` | boolean | | | `data.creative.stageWidth` | integer | | | `data.creative.stageHeight` | integer | | | `data.creative.touchEnabled` | boolean | | | `data.creative.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.creative.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.orphanedBoxIds` | array of string | Edited box ids the design no longer has. | | `data.sharedFrom` | string \| null | The workspace that owns the design, when it was shared in from another workspace. | | `data.base` | OverrideCreative | A creative's design: the boxes and scenes with their settings. | | `data.base.id` | string | | | `data.base.nodeId` | string \| null | | | `data.base.name` | string | | | `data.base.backgroundUrl` | string \| null | | | `data.base.boxes` | array of object | | | `data.base.scenes` | array of object | | | `data.base.dataSourceId` | string \| null | | | `data.base.stage` | string | Absent when not set. | | `data.base.shareLockDefault` | any \| null | | | `data.base.shareEditsSkipApproval` | boolean | | | `data.base.stageWidth` | integer | | | `data.base.stageHeight` | integer | | | `data.base.touchEnabled` | boolean | | | `data.base.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.base.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.editable` | array of object | With view=values: every text box the author left editable, with the text it shows now. | | `data.editable[].boxId` | string | | | `data.editable[].name` | string \| null | | | `data.editable[].text` | string | | | `data.rejectedFields` | array of string | `boxId.field` edits that no longer apply because the author locked the field. | | `data.updatedAt` | string \| null | When the edits were last saved; null before the first save. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: Unknown location, no such creative, or the creative is not usable at that location. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/creative-overrides/{creativeId} Replace a creative's overrides at a location Replace a location's edits to a shared creative. If the creative's author has locked a field against editing, the request is rejected with a 422 error for that field. **Notes.** - The response has no `sharedFrom`, `base` or `rejectedFields` (GET has them). A save returns approved edits to `draft`. Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `creativeId` | path | string | yes | Creative id: one of yours, or one shared into this workspace. | | `node` | query | string | no | Location id. Default: the workspace root. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `values` | object | yes | Every edit to keep, at most 300 boxes. Edits left out are removed. | ```bash curl -X PUT "https://api.brixsignage.com/v1/creative-overrides/{creativeId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.creativeId` | string | | | `data.nodeId` | string | The location the edits apply at. | | `data.values` | object | The location's edits: box id → the box fields it changes (for example `{ "price": { "text": "13.00" } }`). | | `data.overrideId` | string \| null | Id of the stored edits (what an approval request is opened against); null before the first save. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state of the edits (not of the design). | | `data.requiresApproval` | boolean | The location requires approval before the edits air. | | `data.skipsApproval` | boolean | The author waived that review for this design. | | `data.creative` | OverrideCreative | A creative's design: the boxes and scenes with their settings. | | `data.creative.id` | string | | | `data.creative.nodeId` | string \| null | | | `data.creative.name` | string | | | `data.creative.backgroundUrl` | string \| null | | | `data.creative.boxes` | array of object | | | `data.creative.scenes` | array of object | | | `data.creative.dataSourceId` | string \| null | | | `data.creative.stage` | string | Absent when not set. | | `data.creative.shareLockDefault` | any \| null | | | `data.creative.shareEditsSkipApproval` | boolean | | | `data.creative.stageWidth` | integer | | | `data.creative.stageHeight` | integer | | | `data.creative.touchEnabled` | boolean | | | `data.creative.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.creative.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.orphanedBoxIds` | array of string | Edited box ids the design no longer has. | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You lack creative.edit at that location. Response 404: Unknown location, no such creative, or the creative is not usable at that location. Response 422: `validation_error` (bad `values`, more than 300 boxes, unknown box ids in `unknownBoxes`) or `locked` (fields the author locked, in `violations`). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/creative-overrides/{creativeId} Change some of a creative's overrides at a location Change only the edits you name on a creative shared with a location, keeping every other edit. Send null for a box to remove its edits. Fields the creative's author locked are rejected with a 422 error. **Notes.** - Use this to set one price without resending the others. `values` in the response is every stored edit after the change. A save returns approved edits to `draft`. Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `creativeId` | path | string | yes | Creative id: one of yours, or one shared into this workspace. | | `node` | query | string | no | Location id. Default: the workspace root. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `values` | object | yes | Only the boxes to change, keyed by box id. A box's fields are layered over its stored edits; null removes that box's edits. Boxes left out keep their edits. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/creative-overrides/{creativeId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.creativeId` | string | | | `data.nodeId` | string | The location the edits apply at. | | `data.values` | object | The location's edits: box id → the box fields it changes (for example `{ "price": { "text": "13.00" } }`). | | `data.overrideId` | string \| null | Id of the stored edits (what an approval request is opened against); null before the first save. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state of the edits (not of the design). | | `data.requiresApproval` | boolean | The location requires approval before the edits air. | | `data.skipsApproval` | boolean | The author waived that review for this design. | | `data.creative` | OverrideCreative | A creative's design: the boxes and scenes with their settings. | | `data.creative.id` | string | | | `data.creative.nodeId` | string \| null | | | `data.creative.name` | string | | | `data.creative.backgroundUrl` | string \| null | | | `data.creative.boxes` | array of object | | | `data.creative.scenes` | array of object | | | `data.creative.dataSourceId` | string \| null | | | `data.creative.stage` | string | Absent when not set. | | `data.creative.shareLockDefault` | any \| null | | | `data.creative.shareEditsSkipApproval` | boolean | | | `data.creative.stageWidth` | integer | | | `data.creative.stageHeight` | integer | | | `data.creative.touchEnabled` | boolean | | | `data.creative.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.creative.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.orphanedBoxIds` | array of string | Edited box ids the design no longer has. | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You lack creative.edit at that location. Response 404: Unknown location, no such creative, or the creative is not usable at that location. Response 422: `validation_error` (bad `values`, more than 300 boxes in total, unknown box ids in `unknownBoxes`) or `locked` (fields the author locked, in `violations`). Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Creatives 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/creatives List creatives Return the workspace's canvas creatives, including each one's name, stage size, location, and sharing state. The full layout of shapes is not included; use the get-creative operation to retrieve that. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | 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). | ```bash curl "https://api.brixsignage.com/v1/creatives" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Creative | | | `data[].id` | string | Creative id. | | `data[].folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].backgroundUrl` | string \| null | | | `data[].boxes` | array of object | The design's boxes (text, image, data-bound fields…), in paint order. | | `data[].dataSourceId` | string \| null | The data source the boxes bind to, if any. | | `data[].stage` | string \| null | Stage preset name. | | `data[].stageWidth` | integer \| null | | | `data[].stageHeight` | integer \| null | | | `data[].scenes` | array of object | Scenes, for a multi-scene design; often empty. | | `data[].touchEnabled` | boolean \| null | | | `data[].tags` | array of string | Free-text tags. | | `data[].pauseWhileUsed` | boolean \| null | Hold the playlist while something a tap opened is up. Null = true. | | `data[].repeat` | object \| null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. | | `data[].nodeId` | string \| null | | | `data[].approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data[].approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data[].sourceSignage` | any \| null | The template it was made from (JSON), if any. | | `data[].look` | any \| null | Accent / Brand Kit / light-dark settings (JSON), if set. | | `data[].masterId` | string \| null | The master template id, for a design made from one. | | `data[].shareLockDefault` | any \| null | Which boxes recipients may edit when shared (JSON), if set. | | `data[].shareEditsSkipApproval` | boolean | | | `data[].templateSource` | any \| null | The fill-in form behind a design made from a new template (JSON), if any. | | `data[].recalledAt` | string \| null | | | `data[].recalledBy` | string \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `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/creatives Create a creative Create a canvas creative. Accepts name and optional boxes, scenes, stageWidth, stageHeight, backgroundUrl, dataSourceId, touchEnabled, nodeId, and masterId. Safe to retry with the same Idempotency-Key header without creating duplicates. **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. - Send an `Idempotency-Key` header to make a retry safe. Auth: Bearer token. Permission: `creative.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `backgroundUrl` | string \| null | no | An unsafe URL scheme is stored as null. | | `boxes` | array of object | no | The whole box list; each box is checked and filled out with defaults. Default `[]`. | | `dataSourceId` | string \| null | no | A data source in this workspace. | | `stage` | string \| null | no | | | `stageWidth` | integer \| null | no | | | `stageHeight` | integer \| null | no | | | `scenes` | array of object | no | Default `[]`. | | `touchEnabled` | boolean \| null | no | | | `tags` | array of string | no | Free-text tags, at most 50. Proof of Play can report on a tag. | | `pauseWhileUsed` | boolean \| null | no | Hold the playlist while something a tap opened is up. Null = true. | | `repeat` | object \| null | no | Repeat for each row (beta): plays the design once per row of its data source, with `{{row.column}}` values following the row. `null` turns it off. Answers 403 `feature_disabled` where the workspace does not have the feature. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `sourceSignage` | any | no | | | `masterId` | string \| null | no | The master template it was made from (`GET /v1/signage-master-templates`). | | `shareLockDefault` | any | no | Which box fields recipients may edit when it is shared (JSON). | | `shareEditsSkipApproval` | boolean | no | Recipients' edits air without review. Needs `creative.approve`. | | `look` | object \| null | no | | | `templateSource` | object \| null | no | The fill-in form behind a design made from a new template (template id, data, look). Editor state only. `null` clears it. | ```bash curl -X POST "https://api.brixsignage.com/v1/creatives" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Creative id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.backgroundUrl` | string \| null | | | `data.boxes` | array of object | The design's boxes (text, image, data-bound fields…), in paint order. | | `data.dataSourceId` | string \| null | The data source the boxes bind to, if any. | | `data.stage` | string \| null | Stage preset name. | | `data.stageWidth` | integer \| null | | | `data.stageHeight` | integer \| null | | | `data.scenes` | array of object | Scenes, for a multi-scene design; often empty. | | `data.touchEnabled` | boolean \| null | | | `data.tags` | array of string | Free-text tags. | | `data.pauseWhileUsed` | boolean \| null | Hold the playlist while something a tap opened is up. Null = true. | | `data.repeat` | object \| null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. | | `data.nodeId` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data.sourceSignage` | any \| null | The template it was made from (JSON), if any. | | `data.look` | any \| null | Accent / Brand Kit / light-dark settings (JSON), if set. | | `data.masterId` | string \| null | The master template id, for a design made from one. | | `data.shareLockDefault` | any \| null | Which boxes recipients may edit when shared (JSON), if set. | | `data.shareEditsSkipApproval` | boolean | | | `data.templateSource` | any \| null | The fill-in form behind a design made from a new template (JSON), if any. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | Response 401: Missing, expired or revoked bearer token. Response 403: Setting `shareEditsSkipApproval` without `creative.approve`, or a `dataSourceId` homed where you lack integration.view. Response 404: `dataSourceId` names no data source in this workspace. Response 422: Missing name, invalid JSON, malformed boxes, scenes or look, or a location outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/creatives/{id} Get a creative Return one creative in full, including its boxes, scenes, background, any linked data source, and stage dimensions. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Creative id. | ```bash curl "https://api.brixsignage.com/v1/creatives/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Creative id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.backgroundUrl` | string \| null | | | `data.boxes` | array of object | The design's boxes (text, image, data-bound fields…), in paint order. | | `data.dataSourceId` | string \| null | The data source the boxes bind to, if any. | | `data.stage` | string \| null | Stage preset name. | | `data.stageWidth` | integer \| null | | | `data.stageHeight` | integer \| null | | | `data.scenes` | array of object | Scenes, for a multi-scene design; often empty. | | `data.touchEnabled` | boolean \| null | | | `data.tags` | array of string | Free-text tags. | | `data.pauseWhileUsed` | boolean \| null | Hold the playlist while something a tap opened is up. Null = true. | | `data.repeat` | object \| null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. | | `data.nodeId` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data.sourceSignage` | any \| null | The template it was made from (JSON), if any. | | `data.look` | any \| null | Accent / Brand Kit / light-dark settings (JSON), if set. | | `data.masterId` | string \| null | The master template id, for a design made from one. | | `data.shareLockDefault` | any \| null | Which boxes recipients may edit when shared (JSON), if set. | | `data.shareEditsSkipApproval` | boolean | | | `data.templateSource` | any \| null | The fill-in form behind a design made from a new template (JSON), if any. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `data.requiresApproval` | boolean | The home location requires approval before content airs. | | `data.canEditBase` | boolean | The caller may edit the design itself (not only its unlocked boxes). | | `data.canWaiveApproval` | boolean | The caller holds `creative.approve` at its home location. | 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 creative in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/creatives/{id} Update a creative Edit a creative. The boxes and scenes fields each replace the entire existing list, so retrieve the creative first and send back the complete array with changes included. If the location requires approval before content goes live, updating the creative resets that approval. **Notes.** - The response is the stored row: it has no `requiresApproval`, `canEditBase` or `canWaiveApproval` (GET has them). Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Creative id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `backgroundUrl` | string \| null | no | An unsafe URL scheme is stored as null. | | `boxes` | array of object | no | The whole box list; each box is checked and filled out with defaults. Default `[]`. | | `dataSourceId` | string \| null | no | A data source in this workspace. | | `stage` | string \| null | no | | | `stageWidth` | integer \| null | no | | | `stageHeight` | integer \| null | no | | | `scenes` | array of object | no | Default `[]`. | | `touchEnabled` | boolean \| null | no | | | `tags` | array of string | no | Free-text tags, at most 50. Proof of Play can report on a tag. | | `pauseWhileUsed` | boolean \| null | no | Hold the playlist while something a tap opened is up. Null = true. | | `repeat` | object \| null | no | Repeat for each row (beta): plays the design once per row of its data source, with `{{row.column}}` values following the row. `null` turns it off. Answers 403 `feature_disabled` where the workspace does not have the feature. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `sourceSignage` | any | no | | | `masterId` | string \| null | no | The master template it was made from (`GET /v1/signage-master-templates`). | | `shareLockDefault` | any | no | Which box fields recipients may edit when it is shared (JSON). | | `shareEditsSkipApproval` | boolean | no | Recipients' edits air without review. Needs `creative.approve`. | | `look` | object \| null | no | | | `templateSource` | object \| null | no | The fill-in form behind a design made from a new template (template id, data, look). Editor state only. `null` clears it. | | `baseUpdatedAt` | string | no | Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/creatives/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Creative | A canvas design (data-bound boxes on a stage). | | `data.id` | string | Creative id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.backgroundUrl` | string \| null | | | `data.boxes` | array of object | The design's boxes (text, image, data-bound fields…), in paint order. | | `data.dataSourceId` | string \| null | The data source the boxes bind to, if any. | | `data.stage` | string \| null | Stage preset name. | | `data.stageWidth` | integer \| null | | | `data.stageHeight` | integer \| null | | | `data.scenes` | array of object | Scenes, for a multi-scene design; often empty. | | `data.touchEnabled` | boolean \| null | | | `data.tags` | array of string | Free-text tags. | | `data.pauseWhileUsed` | boolean \| null | Hold the playlist while something a tap opened is up. Null = true. | | `data.repeat` | object \| null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. | | `data.nodeId` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data.sourceSignage` | any \| null | The template it was made from (JSON), if any. | | `data.look` | any \| null | Accent / Brand Kit / light-dark settings (JSON), if set. | | `data.masterId` | string \| null | The master template id, for a design made from one. | | `data.shareLockDefault` | any \| null | Which boxes recipients may edit when shared (JSON), if set. | | `data.shareEditsSkipApproval` | boolean | | | `data.templateSource` | any \| null | The fill-in form behind a design made from a new template (JSON), if any. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | Response 401: Missing, expired or revoked bearer token. Response 403: Moving it to a location where you lack creative.edit, changing `shareEditsSkipApproval` without `creative.approve`, or a new `dataSourceId` homed where you lack integration.view. Response 404: No such creative (or `dataSourceId`) in this workspace. Response 409: `conflict`: the row changed since `baseUpdatedAt`; the body carries `current`. Response 422: Invalid JSON or malformed boxes, scenes or look. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/creatives/{id} Delete a creative Move a creative to the recycle bin. If the creative is shared into other locations, the request fails with a 409 error unless the deletion is explicitly confirmed, since deleting a shared creative removes it everywhere it is shared. Auth: Bearer token. Permission: `creative.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Creative id. | | `force` | query | "true" | no | Delete even when it is shared into other places; the shares go with it. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/creatives/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | Shares removed with it. | 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 creative in this workspace. Response 409: `content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/creatives/{id}/restore Restore a creative Bring back a deleted creative so it returns to the library. The shares removed by the delete come back with it. Auth: Bearer token. Permission: `creative.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Creative id. | ```bash curl -X POST "https://api.brixsignage.com/v1/creatives/{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 creative in this workspace, or it was purged. Response 409: `not_deleted`: the creative is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/creatives/{id}/thumbnail Get a creative's thumbnail Return an image of the creative, showing its shapes and pictures along with a representative preview of each content slot, such as a file's poster image, a playlist's first item, or an app's most recent snapshot. Text boxes are not drawn. The image is cached; add ?fresh=1 to bypass the cache after making an edit. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Creative id. | | `fresh` | query | "1" | no | Skip the cached image and draw it again. | ```bash curl "https://api.brixsignage.com/v1/creatives/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 creative in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/creatives/bulk-delete Delete creatives in bulk Move up to 500 creatives to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in `ok` and the rest in `failed`, so one failure does not stop the rest. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/creatives/bulk-delete" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Cross space shares 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/cross-space-shares List cross-workspace shares List content this space shares into its child spaces, and content shared with it in turn. A space receiving a share can read it but cannot change or remove it. **Notes.** - Lists the shares this workspace RECEIVES (it is the target), not the ones it grants. Auth: Bearer token. Permission: `playlist.view`. ```bash curl "https://api.brixsignage.com/v1/cross-space-shares" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].sourceSpaceId` | string | The workspace that shares. | | `data[].targetSpaceId` | string | The child workspace that receives. | | `data[].contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … | | `data[].contentId` | string | | | `data[].mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. | | `data[].lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. | | `data[].lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. | | `data[].grantedBy` | string | The user who shared it; `system` for an API key. | | `data[].grantedAt` | string | ISO-8601 timestamp (UTC). | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | | | `data[].packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. | | `data[].contentName` | string \| null | Null when the content no longer exists. | | `data[].sourceSpaceName` | string \| null | | | `data[].available` | boolean | False when the shared content was deleted. | | `data[].thumbnailUrl` | string \| null | The item's picture through the share (`GET /v1/shared-in/{kind}/{id}/thumbnail`). Null for an app, a schedule or a deleted item. | | `data[].fileKind` | string \| null | For a shared file: its kind (`image`, `video`, `pdf`…), so a Files page can filter it by type. Null for every other kind and for a deleted file. | | `data[].copyable` | boolean | True when this workspace may make its own copy (`POST /v1/cross-space-shares/{id}/copy`): an item a partner shares live. | | `data[].items` | integer | A shared folder (`contentKind` `folder`): how many files it brings now. | | `data[].folders` | array of object | A shared folder: the folder and every folder inside it (the shared folder's own `parentId` is null). | | `data[].folders[].id` | string | | | `data[].folders[].name` | string | | | `data[].folders[].parentId` | string \| null | | | `data[].folderId` | string \| null | A file that comes with a shared folder: the folder it is in. | 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/cross-space-shares Share content with a child workspace Share a playlist, layout, schedule, or creative from this space into a child space. The shared content appears in the child space alongside its own content. Only the space that owns the content can create the share. Requires view permission on shares plus the appropriate permission on the content itself. **Notes.** - Besides the `playlist.view` gate, the caller needs the content kind's edit permission at the content's location. Auth: Bearer token. Permission: `playlist.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `targetSpaceId` | string | yes | A child workspace of yours. | | `contentKind` | string | yes | | | `contentId` | string | yes | | | `lockLevel` | "playlist" \| "items" \| "both" | no | Default `both`. | | `lockedItemIds` | array of string | no | | | `mode` | string | no | Ignored: a share is always `linked`. | ```bash curl -X POST "https://api.brixsignage.com/v1/cross-space-shares" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success: The content is already shared with that workspace: the existing share is returned. | Field | Type | Description | | --- | --- | --- | | `data` | CrossSpaceShare | Content a parent workspace shares with a child workspace. | | `data.id` | string | | | `data.sourceSpaceId` | string | The workspace that shares. | | `data.targetSpaceId` | string | The child workspace that receives. | | `data.contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … | | `data.contentId` | string | | | `data.mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. | | `data.lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. | | `data.lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. | | `data.grantedBy` | string | The user who shared it; `system` for an API key. | | `data.grantedAt` | string | ISO-8601 timestamp (UTC). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | CrossSpaceShare | Content a parent workspace shares with a child workspace. | | `data.id` | string | | | `data.sourceSpaceId` | string | The workspace that shares. | | `data.targetSpaceId` | string | The child workspace that receives. | | `data.contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … | | `data.contentId` | string | | | `data.mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. | | `data.lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. | | `data.lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. | | `data.grantedBy` | string | The user who shared it; `system` for an API key. | | `data.grantedAt` | string | ISO-8601 timestamp (UTC). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. | Response 401: Missing, expired or revoked bearer token. Response 403: The target is not a child workspace of yours, or you lack the content kind's edit permission (`playlist.edit`, …) where it lives. Response 404: No such content in your workspace. Response 422: `targetSpaceId`, `contentKind` or `contentId` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/cross-space-shares/{id} Revoke a cross-workspace share Withdraw a share. Only the space that created the share can remove it; the receiving space cannot. **Notes.** - Only the sharing workspace can revoke; it needs the content kind's edit permission too. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Share id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/cross-space-shares/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.revoked` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You lack the content kind's edit permission where the content lives. Response 404: No such share granted by this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/cross-space-shares/{id}/copy Make your own copy of a shared item Copy an item that a partner shares with your workspace into your own library, so that you can change it. The copy is a draft and has no link to the original. The share continues: the original plays where you use it, and later changes from the partner reach it. Data sources and sign-in values are not copied. You need create permission for each kind of content that the copy makes. A large copy continues in the background and the answer gives a job id. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/cross-space-shares/{id}/copy" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Data sources 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/data-sources List data sources List the data feeds, such as spreadsheets, APIs, and other connectors, that creatives and apps can connect to. Credentials are encrypted at rest and are never returned. **Notes.** - Not paginated: every data source you can see comes back in one response (no `?limit`/`?cursor`, unlike the app instance, creative and layout lists). Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/data-sources" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of DataSource | | | `data[].id` | string | Data source id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. | | `data[].config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. | | `data[].cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. | | `data[].rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. | | `data[].connected` | boolean | The last sync succeeded. | | `data[].lastSyncedAt` | string \| null | | | `data[].syncError` | string \| null | Why the last sync failed; null when it succeeded. | | `data[].nodeId` | string \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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/data-sources Create a data source Connect a data feed with a `name`, a connector `type`, a `config`, and an optional `nodeId`. Any credentials included in `config` are encrypted at rest. Test the configuration first with POST /v1/data-sources/test before creating it. **Notes.** - Gated by `integration.edit`, not `integration.create`. Auth: Bearer token. Permission: `integration.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `type` | string | yes | Connector type from `GET /v1/connectors`. The value is not checked here: an unknown type fails at the first sync. | | `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. | | `nodeId` | string \| null | no | Home location; null or absent = workspace root. The key needs the permission there. | ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | DataSource | A connected data feed. Credentials are never returned. | | `data.id` | string | Data source id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. | | `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. | | `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. | | `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. | | `data.connected` | boolean | The last sync succeeded. | | `data.lastSyncedAt` | string \| null | | | `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. | | `data.nodeId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `name` or `type` is missing, or `invalid_node`: the location is not in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/data-sources/{id} Get a data source Retrieve one data source, including its connector configuration, the time of its last sync, and its row schema. Secret values are redacted. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Data source id. | ```bash curl "https://api.brixsignage.com/v1/data-sources/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | DataSource | A connected data feed. Credentials are never returned. | | `data.id` | string | Data source id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. | | `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. | | `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. | | `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. | | `data.connected` | boolean | The last sync succeeded. | | `data.lastSyncedAt` | string \| null | | | `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. | | `data.nodeId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | 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 data source in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/data-sources/{id} Update a data source Edit a data source's name, connector configuration, or node. Send `••••••••` back for a credential to keep the stored value. To point the source at a different address or connector type, enter the credential again. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Data source id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `type` | string | no | A change of type needs `config` with the credentials entered again. | | `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. | | `nodeId` | string \| null | no | Move it; the key needs `integration.edit` at the destination too. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/data-sources/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | DataSource | A connected data feed. Credentials are never returned. | | `data.id` | string | Data source id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. | | `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. | | `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. | | `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. | | `data.connected` | boolean | The last sync succeeded. | | `data.lastSyncedAt` | string \| null | | | `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. | | `data.nodeId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: No `integration.edit` at the destination location. Response 404: No such data source in this workspace. Response 409: `conflict`: the type or config changed while this request ran. Nothing was saved; read the source again and resend. Response 422: `credential_reentry_required`: the change moves a masked credential to a new address or connector type (`fields` names what moved); or `invalid_node`: the destination is not in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/data-sources/{id} Delete a data source. It can be restored later with POST /v1/data-sources/:id/restore. Creatives connected to it display their fallback values while it is deleted. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Data source id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/data-sources/{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 data source in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/data-sources/{id}/restore Restore a deleted data source connector. Apps and creatives connected to it begin receiving fresh data again the next time their content refreshes. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Data source id. | ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/{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 data source in this workspace. Response 409: `not_deleted`: the data source is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/data-sources/{id}/revel/establishments List Revel establishments and locations List the Revel establishments that the saved key can read, and the locations where this data source shows. Each location gives its chosen establishment and, when there is no choice, a suggested one. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl "https://api.brixsignage.com/v1/data-sources/{id}/revel/establishments" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/data-sources/{id}/revel/locations Set the Revel establishment for each location Save which Revel establishment each location reads its menu from. Send `map` as `{ location id: establishment id }`. Each location must be one where this data source shows, and each establishment must be one that Revel lists for the key. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X PUT "https://api.brixsignage.com/v1/data-sources/{id}/revel/locations" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/data-sources/{id}/revel/test Test a saved Revel connection Check the Revel key that this data source holds. Send an optional `establishmentId` to check one establishment. Nothing is changed. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/{id}/revel/test" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/data-sources/{id}/sync Sync a data source now Pull fresh data for one data source immediately instead of waiting for its regular schedule. Runs the connector once and caches the result. A connector failure is NOT an HTTP error: the answer is 200 with `synced: false` and the reason. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Data source id. | ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/{id}/sync" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | 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 data source in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/data-sources/refresh-all Sync every data source Pull fresh data for every data source in the workspace immediately. This action is rate-limited to 5 requests per minute. Syncs, one after another, every data source the caller may edit. Rate limited to 5 calls a minute. Auth: Bearer token. Permission: `integration.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/refresh-all" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.total` | integer | | | `data.ok` | integer | | | `data.failed` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 5 calls in a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/data-sources/revel/test Test a Revel connection Check a Revel address, API key and API secret before you save them. Send an optional `establishmentId` to check one establishment. Nothing is saved. The Revel connector must be turned on for the workspace. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/revel/test" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/data-sources/sheets-methods List Google Sheets sharing methods List the ways a Google Sheet can be shared with the platform, and the address to share it with. The response may include `publicLink`, `serviceAccount`, and `oauth`, depending on what the platform supports; a method is listed only if it is actually available. `serviceAccount` is not a secret; it is the address you enter into Google's Share dialog. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/data-sources/sheets-methods" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.publicLink` | true | A sheet shared as "anyone with the link" always works. | | `data.serviceAccount` | string \| null | The address to share a private sheet with; null when this method is not available. | | `data.oauth` | boolean | A private sheet can be picked by signing in with Google. | 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/data-sources/test Test a data source config Validate a connector configuration without saving it. Returns `{ ok: true, preview }` on success or `{ ok: false, error }` on failure, so a misconfigured feed can be caught before it is created. Runs the connector once with a config that is not saved. A connector failure is NOT an HTTP error: the answer is 200 with `ok: false` and the reason. Rate limited to 20 calls a minute. Auth: Bearer token. Permission: `integration.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string | yes | | | `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. | ```bash curl -X POST "https://api.brixsignage.com/v1/data-sources/test" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 20 calls in a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Device preassignments 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/device-preassignments List pre-assigned devices List devices pre-assigned to locations in your workspace. Each entry shows the end of the device serial number, the location, the screen name, and whether the device is still waiting to be claimed or has already been claimed. Results are limited to the organization nodes you can see. **Notes.** - Carries `available` beside `data`. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/device-preassignments" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].serialHint` | string \| null | The last 4 characters of the serial. The full serial is not stored. | | `data[].nodeId` | string | | | `data[].locationName` | string \| null | | | `data[].locationId` | string \| null | The location's own id (its Location ID), when set. | | `data[].name` | string \| null | | | `data[].status` | "waiting" \| "claimed" | | | `data[].claimedAt` | string \| null | | | `data[].claimedScreenId` | string \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `available` | boolean | False when the workspace's data region does not support pre-assignment yet (`data` is then empty). | 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/device-preassignments Pre-assign devices to locations Pre-assign device serial numbers to locations, identified by Location ID or `nodeId`, so each device pairs automatically into its assigned location the first time it is plugged in. Submit up to 1000 rows in one request; all rows are validated before any are saved. Re-uploading the same rows is safe and does not create duplicates, and `dryRun` validates rows without saving them. A serial number already assigned to another workspace is refused with a conflict error, and the action is recorded in the activity log. Auth: Bearer token. Permission: `screen.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `rows` | array of object | yes | | | `rows[].serial` | string | yes | The device serial number. | | `rows[].locationId` | string | no | The location's Location ID (case-insensitive). Give this or `nodeId`. | | `rows[].nodeId` | string | no | | | `rows[].name` | string | no | Screen name; default: the location name and the serial's last 4 characters. | | `dryRun` | boolean | no | True: check and report, change nothing (answers 200). | ```bash curl -X POST "https://api.brixsignage.com/v1/device-preassignments" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success: a dry run (`dryRun: true`): the same report, nothing changed. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.dryRun` | boolean | | | `data.counts` | object | | | `data.counts.claimed` | integer | | | `data.counts.created` | integer | | | `data.counts.updated` | integer | | | `data.counts.unchanged` | integer | | | `data.rows` | array of object | | | `data.rows[].index` | integer | | | `data.rows[].serial` | string | The serial's last 4 characters. | | `data.rows[].outcome` | "claimed" \| "created" \| "updated" \| "unchanged" | | | `data.rows[].nodeId` | string | | | `data.rows[].locationName` | string | | | `data.rows[].locationId` | string \| null | | | `data.rows[].name` | string | | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.dryRun` | boolean | | | `data.counts` | object | | | `data.counts.claimed` | integer | | | `data.counts.created` | integer | | | `data.counts.updated` | integer | | | `data.counts.unchanged` | integer | | | `data.rows` | array of object | | | `data.rows[].index` | integer | | | `data.rows[].serial` | string | The serial's last 4 characters. | | `data.rows[].outcome` | "claimed" \| "created" \| "updated" \| "unchanged" | | | `data.rows[].nodeId` | string | | | `data.rows[].locationName` | string | | | `data.rows[].locationId` | string \| null | | | `data.rows[].name` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 409: A serial is held by another workspace, or the data region does not support pre-assignment. Response 422: No rows, too many rows, or a row is invalid; `data.errors` lists each by `index` and `code`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/device-preassignments/{id} Cancel a device pre-assignment Cancel a pending device pre-assignment. If the device has already been claimed and turned into a screen, that screen is not affected. The action is recorded in the activity log. Auth: Bearer token. Permission: `screen.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Pre-assignment id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/device-preassignments/{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 5XX: Server error. The body carries a `requestId` to quote to support. ## Emergencies 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/emergencies List emergency overrides, newest first. Use `?status=active` to filter to overrides currently taking over screens. Auth: Bearer token. Permission: `emergency-override.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | "active" \| "cleared" \| "expired" | no | Only overrides in this state. | | `limit` | query | integer | no | At most this many, newest first (default 200, max 500). | ```bash curl "https://api.brixsignage.com/v1/emergencies" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Override | | | `data[].id` | string | Override (cast_… or emg_…) id. | | `data[].spaceId` | string | Workspace id. | | `data[].kind` | "emergency" \| "cast" | | | `data[].status` | "active" \| "cleared" \| "expired" | | | `data[].severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data[].headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data[].body` | string \| null | | | `data[].contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data[].contentId` | string \| null | | | `data[].contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data[].scopeKind` | "all" \| "node" \| "screens" | | | `data[].scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data[].nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data[].screenCount` | integer | Screens targeted, snapshotted when it started. | | `data[].triggeredBy` | string | User id, or `system`. | | `data[].triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data[].expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data[].clearedBy` | string \| null | | | `data[].clearedAt` | string \| null | | | `data[].triggeredByName` | string | Display name of `triggeredBy`. | | `data[].clearedByName` | string \| null | | | `data[].scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data[].confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | ```json { "data": [ { "id": "emg_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "emergency", "status": "active", "severity": "critical", "headline": "Evacuate the building now", "body": "Use the nearest exit. Do not use the lifts.", "contentKind": null, "contentId": null, "contentName": null, "scopeKind": "all", "scopeNodeId": null, "nodeId": null, "screenCount": 42, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": null, "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": "All screens", "confirmedCount": 0 } ] } ``` 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/emergencies Trigger an emergency takeover across a set of screens. An emergency takes the highest priority and layers over each screen's normal content, so clearing it restores exactly what was playing before. Takes over the chosen screens now, above every schedule and cast, until cleared or expired. Clearing restores exactly what was playing. **Notes.** - The route is gated by `emergency-override.create`; the route registry's description names `emergency-override.trigger`, which is not a permission the API checks. Auth: Bearer token. Permission: `emergency-override.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `headline` | string | yes | The message on every targeted screen. Required, non-blank. | | `body` | string | no | Optional second line. | | `severity` | "info" \| "warning" \| "critical" | no | Default `critical`. | | `contentKind` | "media" \| "creative" | no | Attach content to show under the banner. Needs `contentId`. | | `contentId` | string | no | The media or creative id. Needs `contentKind`. | | `scopeKind` | "all" \| "node" \| "screens" | no | Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the emergency goes to EVERY screen you can reach.** | | `scopeNodeId` | string | no | Location id, with `scopeKind: node`. | | `screenIds` | array of string | no | Screen ids, with `scopeKind: screens`. | | `expiresAt` | string \| number \| null | no | When it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared. | ```bash curl -X POST "https://api.brixsignage.com/v1/emergencies" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"headline":"Evacuate the building now","body":"Use the nearest exit. Do not use the lifts.","severity":"critical","scopeKind":"all"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | ```json { "data": { "id": "emg_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "emergency", "status": "active", "severity": "critical", "headline": "Evacuate the building now", "body": "Use the nearest exit. Do not use the lifts.", "contentKind": null, "contentId": null, "contentName": null, "scopeKind": "all", "scopeNodeId": null, "nodeId": null, "screenCount": 42, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": null, "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": "All screens", "confirmedCount": 0 } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not shared to one or more target locations. Response 404: The content does not exist in this workspace. Response 422: Missing headline, a half content pointer, a bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play (`content_unplayable`). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/emergencies/{id} Get an emergency override Retrieve one emergency override, including its scope, content, and expiry. Auth: Bearer token. Permission: `emergency-override.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Emergency id. | ```bash curl "https://api.brixsignage.com/v1/emergencies/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | 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 emergency in this workspace (or outside your locations). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/emergencies/{id}/clear Clear an emergency override Clear an active emergency override. This releases its screens back to their normal content, and the action is recorded in the activity log. Auth: Bearer token. Permission: `emergency-override.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Emergency id. | ```bash curl -X POST "https://api.brixsignage.com/v1/emergencies/{id}/clear" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | 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 emergency in this workspace. Response 409: `already_inactive`: already cleared or expired. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/emergencies/from-template/{templateId} Trigger an emergency from a template Trigger an emergency using a stored template. Any scope or expiry sent with the request overrides the template's defaults. Fires a stored template. Scope and expiry given here override the template's defaults. Send `{}` to use the template as stored. Auth: Bearer token. Permission: `emergency-override.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `templateId` | path | string | yes | Emergency template id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `scopeKind` | "all" \| "node" \| "screens" | no | Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the emergency goes to EVERY screen you can reach.** | | `scopeNodeId` | string | no | Location id, with `scopeKind: node`. | | `screenIds` | array of string | no | Screen ids, with `scopeKind: screens`. | | `expiresAt` | string \| number \| null | no | When it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared. | ```bash curl -X POST "https://api.brixsignage.com/v1/emergencies/from-template/{templateId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Override | A cast or an emergency override. | | `data.id` | string | Override (cast_… or emg_…) id. | | `data.spaceId` | string | Workspace id. | | `data.kind` | "emergency" \| "cast" | | | `data.status` | "active" \| "cleared" \| "expired" | | | `data.severity` | "info" \| "warning" \| "critical" | Always `info` for a cast. | | `data.headline` | string | An emergency's message; for a cast, the content's name (or "Cast"). | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| "schedule" \| null | | | `data.contentId` | string \| null | | | `data.contentName` | string \| null | Name of the content on air: for a cast, the label it was started with, else the content's current name; null when there is no content or it no longer exists. | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | The location, when `scopeKind` is `node`. | | `data.nodeId` | string \| null | Location the override is attributed to (null = workspace root). | | `data.screenCount` | integer | Screens targeted, snapshotted when it started. | | `data.triggeredBy` | string | User id, or `system`. | | `data.triggeredAt` | string | ISO-8601 timestamp (UTC). | | `data.expiresAt` | string \| null | Auto-clear time; null = until cleared. | | `data.clearedBy` | string \| null | | | `data.clearedAt` | string \| null | | | `data.triggeredByName` | string | Display name of `triggeredBy`. | | `data.clearedByName` | string \| null | | | `data.scopeName` | string \| null | Location name, `All screens`, or null for a screen list. | | `data.confirmedCount` | integer \| null | Active emergencies only: screens confirmed showing it now. Null otherwise. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the template's content is not shared to one or more target locations. Response 404: No such template, or its content is gone. Response 422: Bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Emergency templates 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/emergency-templates List emergency templates List pre-configured emergency recipes, such as Lockdown, Severe weather, or Fire drill, used for one-click triggering. A template with `prestage` set to true has its content cached on every screen in scope in advance, before it is ever triggered. Auth: Bearer token. Permission: `emergency-override.view`. ```bash curl "https://api.brixsignage.com/v1/emergency-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of EmergencyTemplate | | | `data[].id` | string | Emergency template id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].severity` | "info" \| "warning" \| "critical" | | | `data[].headline` | string | | | `data[].body` | string \| null | | | `data[].contentKind` | "media" \| "creative" \| "playlist" \| "app" \| null | | | `data[].contentId` | string \| null | | | `data[].scopeKind` | "all" \| "node" \| "screens" | | | `data[].scopeNodeId` | string \| null | | | `data[].nodeId` | string \| null | Home location (null = workspace root); permissions are checked here. | | `data[].prestage` | boolean | Content is cached on every in-scope screen before any trigger. | | `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 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/emergency-templates Create an emergency template Create a reusable emergency recipe with a `name`, `contentKind`, `contentId`, `scope`, `severity`, and an optional `prestage` flag. Trigger it later with POST /v1/emergencies/from-template/:templateId. Auth: Bearer token. Permission: `emergency-override.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default "Untitled template". | | `headline` | string | no | Default "Emergency". | | `body` | string | no | | | `severity` | "info" \| "warning" \| "critical" | no | Default `critical`. | | `contentKind` | "media" \| "creative" \| "playlist" \| "app" | no | | | `contentId` | string | no | | | `scopeKind` | "all" \| "node" \| "screens" | no | Default `all`. | | `scopeNodeId` | string | no | Required with `scopeKind: node`. | | `nodeId` | string | no | Home location. Default: the API key's location, else the workspace root. | | `prestage` | boolean | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/emergency-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | EmergencyTemplate | A pre-armed emergency recipe. | | `data.id` | string | Emergency template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.severity` | "info" \| "warning" \| "critical" | | | `data.headline` | string | | | `data.body` | string \| null | | | `data.contentKind` | "media" \| "creative" \| "playlist" \| "app" \| null | | | `data.contentId` | string \| null | | | `data.scopeKind` | "all" \| "node" \| "screens" | | | `data.scopeNodeId` | string \| null | | | `data.nodeId` | string \| null | Home location (null = workspace root); permissions are checked here. | | `data.prestage` | boolean | Content is cached on every in-scope screen before any trigger. | | `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: Missing `emergency-override.edit` at the home or scope location. Response 404: The content or a location does not exist in this workspace. Response 422: A content kind outside media/creative/playlist/app, a half content pointer, or `scopeKind: node` without `scopeNodeId`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/emergency-templates/{id} Update an emergency template Edit an emergency template's content, scope, severity, or prestaging setting. **Notes.** - Answers only `{ id }`, not the updated template; read it back with the list. A `severity` outside `critical`/`warning`/`info` is ignored. Auth: Bearer token. Permission: `emergency-override.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Emergency template id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default "Untitled template". | | `headline` | string | no | Default "Emergency". | | `body` | string \| null | no | Empty or null clears it. | | `severity` | "info" \| "warning" \| "critical" | no | Default `critical`. | | `contentKind` | "media" \| "creative" \| "playlist" \| "app" | no | | | `contentId` | string | no | | | `scopeKind` | "all" \| "node" \| "screens" | no | Default `all`. | | `scopeNodeId` | string \| null | no | | | `nodeId` | string \| null | no | Move the template; you need `emergency-override.edit` at the destination too. | | `prestage` | boolean | no | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/emergency-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: Missing `emergency-override.edit` at the template's location or at the destination. Response 404: No such template, or the content or a location does not exist in this workspace. Response 422: An empty `name` or `headline`, a bad content pointer, or a scope that cannot be fired. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/emergency-templates/{id} Delete an emergency template. Emergencies already triggered from it are unaffected. **Notes.** - Needs `emergency-override.edit`; there is no `.delete` permission for templates. Auth: Bearer token. Permission: `emergency-override.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Emergency template id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/emergency-templates/{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: Missing `emergency-override.edit` at the template's location. Response 404: No such template in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Folder shares 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/folder-shares/{folderId} Get who a folder is shared with Read who a Files folder is shared with: its own shares (a location, person or role, with `use` or `edit` access), shares inherited from folders above it, and general access. You must be able to edit the folder. A folder in another workspace answers 404. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `folderId` | path | string | yes | Identifier for folderId. | ```bash curl "https://api.brixsignage.com/v1/folder-shares/{folderId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/folder-shares/{folderId} Set who a folder is shared with Replace who a Files folder is shared with. A location includes its sub-locations, and access is `use` or `edit`. Content already on screens keeps playing when a share is removed. You need permission to share folders and edit rights on this folder. Auth: Bearer token. Permission: `media-folder.shared`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `folderId` | path | string | yes | Identifier for folderId. | ```bash curl -X PUT "https://api.brixsignage.com/v1/folder-shares/{folderId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/folder-shares/{folderId}/reach Preview who a folder share reaches Before saving a share, see who the proposed targets would give access to: a count and up to 100 names, limited to people you are allowed to see. Nothing is saved. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `folderId` | path | string | yes | Identifier for folderId. | ```bash curl -X POST "https://api.brixsignage.com/v1/folder-shares/{folderId}/reach" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/folder-shares/notices List folders recently unshared from you List folders that were unshared from the caller in the last 30 days. Content already on screens keeps playing, but the files can no longer be picked. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/folder-shares/notices" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/folder-shares/targets Search for folder share targets Find the people, locations and roles matching `q` that you can share a folder with. Each list is limited to what you are allowed to see. Auth: Bearer token. Permission: `folder.share`. ```bash curl "https://api.brixsignage.com/v1/folder-shares/targets" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/folder-shares/targets/locations List locations to share a folder with List one level of the location tree for picking a share target. Without `parentId` this is the top level. A location you cannot pick is included with `selectable: false` when it leads to one you can. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/folder-shares/targets/locations" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## GDPR 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/gdpr/erase Erase user under GDPR Permanently anonymizes a user's profile and deletes their associated personal data, including linked identities, passkeys, sessions, and pending email verifications, to satisfy a right-to-be-forgotten request. You cannot erase your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner. **Notes.** - Irreversible. Unlike `POST /v1/users/:id/erase`, the person does not have to be deactivated first. Auth: Bearer token. Permission: `user.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `userId` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/gdpr/erase" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.userId` | string | | | `data.erased` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also `owner_required` or `outranked`: the person is an owner, or holds a permission you do not hold. Response 404: No such person in this workspace. Response 409: `cant_erase_self` or `last_owner`. Response 422: `userId` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/gdpr/export Export user data (GDPR) Assembles a data subject access request export for the whole workspace: every person, screen and piece of content, and the last 365 days of the activity log, as one JSON file with secret values withheld. The key or person must have `billing.export` for the whole workspace. Each table is capped; `complete` is false when one was cut. **Notes.** - Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log. - No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`). - Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker. Auth: Bearer token. Permission: `billing.export`. ```bash curl "https://api.brixsignage.com/v1/gdpr/export" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `schemaVersion` | 1 | | | `generatedAt` | string | ISO-8601 timestamp (UTC). | | `subject` | object | | | `subject.spaceId` | string | The workspace exported. | | `subject.requestedByUserId` | string \| null | Null for an API key. | | `limits` | object | | | `limits.perTable` | integer | At most this many rows per table. | | `limits.auditEvents` | integer | At most this many activity log events. | | `limits.auditWindowDays` | integer | Activity log events from this many days back. | | `truncated` | object | The tables cut at the limit; empty when none. | | `complete` | boolean | False when a table was cut at the limit. | | `tables` | object | | | `tables.workspace` | object \| null | The workspace record, every column (the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`). | | `tables.users` | array of object | | | `tables.users[].id` | string | | | `tables.users[].name` | string | | | `tables.users[].email` | string | | | `tables.users[].title` | string \| null | | | `tables.users[].phone` | string \| null | | | `tables.users[].status` | string | | | `tables.users[].lastLoginAt` | string \| null | | | `tables.users[].emailVerifiedAt` | string \| null | | | `tables.users[].createdAt` | string | ISO-8601 timestamp (UTC). | | `tables.users[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `tables.users[].deletedAt` | string \| null | | | `tables.screens` | array of object | Every column; credentials withheld, and `kioskHasCustomPin` / `kioskHasRecovery` added. | | `tables.media` | array of object | | | `tables.playlists` | array of object | | | `tables.schedules` | array of object | | | `tables.layouts` | array of object | | | `tables.creatives` | array of object | | | `tables.appInstances` | array of object | | | `tables.dataSources` | array of object | `config` is `[encrypted; not exported]` (or null). | | `tables.banners` | array of object | | | `tables.auditEvents` | array of object | Newest first. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/gdpr/export Export user data (GDPR) Same as the GET version of this operation: assembles a data subject access request export for the whole workspace as one JSON file, with secret values withheld. The key or person must have `billing.export` for the whole workspace. Takes no request body. **Notes.** - Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log. - No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`). - Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker. - Takes no body; the same export as the GET. Auth: Bearer token. Permission: `billing.export`. ```bash curl -X POST "https://api.brixsignage.com/v1/gdpr/export" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `schemaVersion` | 1 | | | `generatedAt` | string | ISO-8601 timestamp (UTC). | | `subject` | object | | | `subject.spaceId` | string | The workspace exported. | | `subject.requestedByUserId` | string \| null | Null for an API key. | | `limits` | object | | | `limits.perTable` | integer | At most this many rows per table. | | `limits.auditEvents` | integer | At most this many activity log events. | | `limits.auditWindowDays` | integer | Activity log events from this many days back. | | `truncated` | object | The tables cut at the limit; empty when none. | | `complete` | boolean | False when a table was cut at the limit. | | `tables` | object | | | `tables.workspace` | object \| null | The workspace record, every column (the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`). | | `tables.users` | array of object | | | `tables.users[].id` | string | | | `tables.users[].name` | string | | | `tables.users[].email` | string | | | `tables.users[].title` | string \| null | | | `tables.users[].phone` | string \| null | | | `tables.users[].status` | string | | | `tables.users[].lastLoginAt` | string \| null | | | `tables.users[].emailVerifiedAt` | string \| null | | | `tables.users[].createdAt` | string | ISO-8601 timestamp (UTC). | | `tables.users[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `tables.users[].deletedAt` | string \| null | | | `tables.screens` | array of object | Every column; credentials withheld, and `kioskHasCustomPin` / `kioskHasRecovery` added. | | `tables.media` | array of object | | | `tables.playlists` | array of object | | | `tables.schedules` | array of object | | | `tables.layouts` | array of object | | | `tables.creatives` | array of object | | | `tables.appInstances` | array of object | | | `tables.dataSources` | array of object | `config` is `[encrypted; not exported]` (or null). | | `tables.banners` | array of object | | | `tables.auditEvents` | array of object | Newest first. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Interactions 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/interactions List interaction events List engagement events from your screens, such as on-screen taps, QR code scans, presenter joins, and form submissions. **Notes.** - Newest first, at most 1000, from screens at locations the caller can see. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | ISO-8601 start (default: 7 days ago). | | `to` | query | string | no | ISO-8601 end (default: now). | | `screenId` | query | string | no | | ```bash curl "https://api.brixsignage.com/v1/interactions" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].screenId` | string | | | `data[].screenName` | string | The screen id when the screen no longer exists. | | `data[].at` | string | ISO-8601 timestamp (UTC). | | `data[].kind` | "touch" \| "qr-scan" \| "screenshare-join" \| "form-submit" | | | `data[].detail` | string | A short human-readable summary. | | `data[].boxId` | string \| null | A counted button tap only: the box that was tapped. | | `data[].creativeId` | string \| null | A counted button tap only: the design the box is on. | | `data[].action` | string \| null | A counted button tap only: the tap action kind (for example `open-url`). | 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/interactions/taps Count taps per button Returns the number of taps on each button of a design in a date range, with the design and box names. Only tap actions saved with `count: true` are counted. The busiest buttons come first, and at most 20,000 taps are read, from screens at the locations you can see. Counted taps per button (a box on a design) in the window. Only tap actions saved with `count: true` are counted. **Notes.** - Most taps first. Reads at most 20,000 taps, from screens at locations the caller can see. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | ISO-8601 start (default: 7 days ago). | | `to` | query | string | no | ISO-8601 end (default: now). | | `screenId` | query | string | no | | ```bash curl "https://api.brixsignage.com/v1/interactions/taps" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].creativeId` | string \| null | | | `data[].creativeName` | string \| null | Null when the design is gone. | | `data[].boxId` | string | | | `data[].boxName` | string \| null | The layer name, else its text. Null when the box is gone. | | `data[].action` | string \| null | The tap action kind of the newest tap. | | `data[].count` | integer | | | `data[].lastAt` | string | ISO-8601 timestamp (UTC). | 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. ## Layouts 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/layouts List layouts List the workspace's multi-zone layouts, including each layout's name, resolution, and zone count. Auth: Bearer token. Permission: `layout.view`. Parameters: | Name | 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). | ```bash curl "https://api.brixsignage.com/v1/layouts" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Layout | | | `data[].id` | string | Layout id. | | `data[].folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].resolution` | object | Design canvas size in pixels. | | `data[].resolution.w` | number | | | `data[].resolution.h` | number | | | `data[].zones` | array of object | Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list. | | `data[].autoFullscreenForVideo` | boolean \| null | | | `data[].approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data[].approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data[].nodeId` | string \| null | | | `data[].importSourceId` | string \| null | | | `data[].theme` | any \| null | Brand Kit look (`{ source: "brand", mode?, radius? }`), or null for a bare canvas. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `data[].usedByScreenCount` | integer | Screens showing this layout now, directly or through a playlist or schedule. | | `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/layouts Create a layout Create a multi-zone layout with a `name` and optional `resolution`, `zones`, `autoFullscreenForVideo`, `nodeId`, and `theme`. Setting `theme` to `{ source: "brand", mode?, radius? }` paints the layout using the workspace Brand Kit; omit it or set it to `null` for a plain canvas. Each zone can also carry a frame style (bare, card, accent, or glass), a corner radius in pixels, and a role of "logo" for a zone that shows the Brand Kit logo without needing its own content. **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. - The 201 body has no `usedByScreenCount`. Auth: Bearer token. Permission: `layout.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `resolution` | object | no | Canvas size in pixels. Default 1920 x 1080. | | `resolution.w` | number | yes | | | `resolution.h` | number | yes | | | `zones` | array of LayoutZone | no | The whole zone list. Default: one full-canvas zone named Main. | | `zones[].id` | string | yes | | | `zones[].name` | string | yes | | | `zones[].x` | number | yes | Left edge, in layout pixels. | | `zones[].y` | number | yes | | | `zones[].w` | number | yes | | | `zones[].h` | number | yes | | | `zones[].locked` | boolean | yes | | | `zones[].contentName` | string | no | Label of the bound content. Absent on the zone a new layout starts with. | | `zones[].content` | object \| null | no | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `zones[].zIndex` | number | no | | | `zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | no | | | `zones[].ownerNodeId` | string \| null | no | | | `zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | no | Paint style on a themed layout. | | `zones[].radius` | number | no | Corner radius in layout pixels. | | `zones[].role` | "logo" | no | `logo`: the zone shows the Brand Kit logo instead of content. | | `autoFullscreenForVideo` | boolean \| null | no | | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `theme` | object \| null | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/layouts" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.resolution` | object | Design canvas size in pixels. | | `data.resolution.w` | number | | | `data.resolution.h` | number | | | `data.zones` | array of object | Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list. | | `data.autoFullscreenForVideo` | boolean \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Absent: the create does not set it (it is `draft`). | | `data.approvedSnapshot` | string \| null | | | `data.nodeId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.theme` | any \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: zone content that is not usable at the layout's location. Response 422: Missing name, invalid JSON, a bad theme or zone paint, zone content that does not exist or loops, or a location outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/layouts/{id} Get a layout Retrieve one layout, including its zone geometry with each zone's content assignment and frame, radius, and role styling, its theme (the Brand Kit look, or null), and its video-fullscreen behaviour. Auth: Bearer token. Permission: `layout.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | ```bash curl "https://api.brixsignage.com/v1/layouts/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.resolution` | object | Design canvas size in pixels. | | `data.resolution.w` | number | | | `data.resolution.h` | number | | | `data.zones` | array of object | Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list. | | `data.autoFullscreenForVideo` | boolean \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data.nodeId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.theme` | any \| null | Brand Kit look (`{ source: "brand", mode?, radius? }`), or null for a bare canvas. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `data.usedByScreenCount` | integer | Screens showing this layout now, directly or through a playlist or schedule. | | `data.requiresApproval` | boolean | The home location requires approval before content airs. | 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 layout in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/layouts/{id} Update a layout Edit a layout's name, resolution, zones, `autoFullscreenForVideo`, node, or theme. Setting `theme` to `{ source: "brand", mode?, radius? }` turns the Brand Kit look on, and `null` turns it off. Zones accept a frame style (bare, card, accent, or glass), a radius, and a role of "logo". An invalid theme, or an unrecognized frame or role, returns 422. **Notes.** - The response is the stored row: it has no `usedByScreenCount` or `requiresApproval` (GET has them). Auth: Bearer token. Permission: `layout.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `resolution` | object | no | Canvas size in pixels. Default 1920 x 1080. | | `resolution.w` | number | yes | | | `resolution.h` | number | yes | | | `zones` | array of LayoutZone | no | The whole zone list. Default: one full-canvas zone named Main. | | `zones[].id` | string | yes | | | `zones[].name` | string | yes | | | `zones[].x` | number | yes | Left edge, in layout pixels. | | `zones[].y` | number | yes | | | `zones[].w` | number | yes | | | `zones[].h` | number | yes | | | `zones[].locked` | boolean | yes | | | `zones[].contentName` | string | no | Label of the bound content. Absent on the zone a new layout starts with. | | `zones[].content` | object \| null | no | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `zones[].zIndex` | number | no | | | `zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | no | | | `zones[].ownerNodeId` | string \| null | no | | | `zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | no | Paint style on a themed layout. | | `zones[].radius` | number | no | Corner radius in layout pixels. | | `zones[].role` | "logo" | no | `logo`: the zone shows the Brand Kit logo instead of content. | | `autoFullscreenForVideo` | boolean \| null | no | | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `theme` | object \| null | no | | | `baseUpdatedAt` | string | no | Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/layouts/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.spaceId` | string | | | `data.name` | string | | | `data.resolution` | object | Design canvas size in pixels. | | `data.resolution.w` | number | | | `data.resolution.h` | number | | | `data.zones` | array of object | Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list. | | `data.autoFullscreenForVideo` | boolean \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. | | `data.approvedSnapshot` | string \| null | JSON TEXT of the last approved version (not parsed). | | `data.nodeId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.theme` | any \| null | Brand Kit look (`{ source: "brand", mode?, radius? }`), or null for a bare canvas. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | Response 401: Missing, expired or revoked bearer token. Response 403: Moving it to a location where you lack layout.edit, or zone content that is not usable there (`not_shared`). Response 404: No such layout in this workspace. Response 409: `conflict`: the row changed since `baseUpdatedAt`; the body carries `current`. Response 422: Invalid JSON, a bad theme or zone paint, zone content that does not exist or loops back into this layout. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/layouts/{id} Delete a layout. This fails with 409 `content_shared` if the layout is actively shared into other spaces; pass `?force=true` to delete it anyway. Auth: Bearer token. Permission: `layout.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | | `force` | query | "true" | no | Delete even when it is shared into other places; the shares go with it. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/layouts/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | Shares removed with it. | 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 layout in this workspace. Response 409: `content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/layouts/{id}/restore Restore a deleted layout so it returns to the layout library. Auth: Bearer token. Permission: `layout.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | ```bash curl -X POST "https://api.brixsignage.com/v1/layouts/{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 layout in this workspace, or it was purged. Response 409: `not_deleted`: the layout is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/layouts/{id}/thumbnail Get a layout thumbnail Retrieve a preview image of a layout, showing each zone at its real position filled with a still of its content. The same image is used everywhere the layout is previewed. Add `?fresh=1` to regenerate it after an edit. Auth: Bearer token. Permission: `layout.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | | `fresh` | query | "1" | no | Skip the cached image and draw it again. | ```bash curl "https://api.brixsignage.com/v1/layouts/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 layout in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/layouts/{id}/zones List a layout's zones, including the content attached to each one. Auth: Bearer token. Permission: `layout.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | ```bash curl "https://api.brixsignage.com/v1/layouts/{id}/zones" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of LayoutZone | | | `data[].id` | string | | | `data[].name` | string | | | `data[].x` | number | Left edge, in layout pixels. | | `data[].y` | number | | | `data[].w` | number | | | `data[].h` | number | | | `data[].locked` | boolean | | | `data[].contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data[].content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data[].zIndex` | number | | | `data[].ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data[].ownerNodeId` | string \| null | | | `data[].frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data[].radius` | number | Corner radius in layout pixels. | | `data[].role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | 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 layout in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/layouts/{id}/zones Add a zone to a layout Add one zone to a layout, specifying its geometry, the content attached to it, and, on a themed layout, its frame (bare, card, accent, or glass), radius, and role. A zone with role "logo" does not need content of its own. **Notes.** - Editing zones returns an approved layout to `draft` where approval is required. Auth: Bearer token. Permission: `layout.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default `Zone `. | | `x` | number | no | Default 0. | | `y` | number | no | Default 0. | | `w` | number | no | Default 480. | | `h` | number | no | Default 270. | | `locked` | boolean | no | | | `contentName` | string | no | | | `content` | object \| null | no | What the zone plays. It must exist in this workspace, be usable at the layout's location, and not contain this layout. | | `ownerScope` | "workspace" \| "org_unit" \| "location" | no | | | `ownerNodeId` | string \| null | no | | | `frame` | "bare" \| "card" \| "accent" \| "glass" | no | | | `radius` | number | no | | | `role` | "logo" | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/layouts/{id}/zones" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.zones` | array of LayoutZone | Every zone, in paint order. | | `data.zones[].id` | string | | | `data.zones[].name` | string | | | `data.zones[].x` | number | Left edge, in layout pixels. | | `data.zones[].y` | number | | | `data.zones[].w` | number | | | `data.zones[].h` | number | | | `data.zones[].locked` | boolean | | | `data.zones[].contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zones[].content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zones[].zIndex` | number | | | `data.zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zones[].ownerNodeId` | string \| null | | | `data.zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zones[].radius` | number | Corner radius in layout pixels. | | `data.zones[].role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | | `data.zone` | LayoutZone | A zone. Open: a whole-array write (`PUT /v1/layouts/{id}/zones` with `zones`, or `PATCH /v1/layouts/{id}`) stores each zone as sent, so other keys come back too. | | `data.zone.id` | string | | | `data.zone.name` | string | | | `data.zone.x` | number | Left edge, in layout pixels. | | `data.zone.y` | number | | | `data.zone.w` | number | | | `data.zone.h` | number | | | `data.zone.locked` | boolean | | | `data.zone.contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zone.content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zone.zIndex` | number | | | `data.zone.ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zone.ownerNodeId` | string \| null | | | `data.zone.frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zone.radius` | number | Corner radius in layout pixels. | | `data.zone.role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not usable at the layout's location. Response 404: No such layout (or zone) in this workspace. Response 409: `conflict`: the layout changed during the write three times running; retry. Response 422: A bad frame, radius or role, content that does not exist, or zone content that plays this layout again (a loop). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/layouts/{id}/zones Replace a layout's zones Replace a layout's entire set of zones in one call. Send every zone you want to keep, including each zone's frame, radius, and role on a themed layout; a zone sent without those becomes a plain, unframed zone. Send `zones` to replace the whole list, or `zoneIds` (every current zone id, once) to reorder it. **Notes.** - `zones` is stored as sent: keys the API does not know are kept and returned. Auth: Bearer token. Permission: `layout.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | Request body: `application/json` ```bash curl -X PUT "https://api.brixsignage.com/v1/layouts/{id}/zones" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.zones` | array of LayoutZone | Every zone, in paint order. | | `data.zones[].id` | string | | | `data.zones[].name` | string | | | `data.zones[].x` | number | Left edge, in layout pixels. | | `data.zones[].y` | number | | | `data.zones[].w` | number | | | `data.zones[].h` | number | | | `data.zones[].locked` | boolean | | | `data.zones[].contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zones[].content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zones[].zIndex` | number | | | `data.zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zones[].ownerNodeId` | string \| null | | | `data.zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zones[].radius` | number | Corner radius in layout pixels. | | `data.zones[].role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not usable at the layout's location. Response 404: No such layout (or zone) in this workspace. Response 409: `conflict`: the layout changed during the write three times running; retry. Response 422: `zoneIds` that are not every zone exactly once, neither `zones` nor `zoneIds`, or a bad or looping zone. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/layouts/{id}/zones/{zoneId} Update a layout zone Edit one zone's geometry, attached content, or, on a themed layout, its frame, radius, or role. Send `null` for any of those to clear it. Rejects a change that would create a loop back into the same layout. Auth: Bearer token. Permission: `layout.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | | `zoneId` | path | string | yes | Zone id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default `Zone `. | | `x` | number | no | Default 0. | | `y` | number | no | Default 0. | | `w` | number | no | Default 480. | | `h` | number | no | Default 270. | | `locked` | boolean | no | | | `contentName` | string | no | | | `content` | object \| null | no | What the zone plays. It must exist in this workspace, be usable at the layout's location, and not contain this layout. | | `ownerScope` | "workspace" \| "org_unit" \| "location" | no | | | `ownerNodeId` | string \| null | no | | | `frame` | "bare" \| "card" \| "accent" \| "glass" \| null | no | `null` removes it. | | `radius` | number \| null | no | `null` removes it. | | `role` | "logo" \| null | no | `null` removes it. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/layouts/{id}/zones/{zoneId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.zones` | array of LayoutZone | Every zone, in paint order. | | `data.zones[].id` | string | | | `data.zones[].name` | string | | | `data.zones[].x` | number | Left edge, in layout pixels. | | `data.zones[].y` | number | | | `data.zones[].w` | number | | | `data.zones[].h` | number | | | `data.zones[].locked` | boolean | | | `data.zones[].contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zones[].content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zones[].zIndex` | number | | | `data.zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zones[].ownerNodeId` | string \| null | | | `data.zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zones[].radius` | number | Corner radius in layout pixels. | | `data.zones[].role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | | `data.zone` | LayoutZone | A zone. Open: a whole-array write (`PUT /v1/layouts/{id}/zones` with `zones`, or `PATCH /v1/layouts/{id}`) stores each zone as sent, so other keys come back too. | | `data.zone.id` | string | | | `data.zone.name` | string | | | `data.zone.x` | number | Left edge, in layout pixels. | | `data.zone.y` | number | | | `data.zone.w` | number | | | `data.zone.h` | number | | | `data.zone.locked` | boolean | | | `data.zone.contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zone.content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zone.zIndex` | number | | | `data.zone.ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zone.ownerNodeId` | string \| null | | | `data.zone.frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zone.radius` | number | Corner radius in layout pixels. | | `data.zone.role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not usable at the layout's location. Response 404: No such layout (or zone) in this workspace. Response 409: `conflict`: the layout changed during the write three times running; retry. Response 422: A bad frame, radius or role, content that does not exist, or zone content that plays this layout again (a loop). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/layouts/{id}/zones/{zoneId} Delete a layout zone Remove one zone from a layout. Auth: Bearer token. Permission: `layout.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Layout id. | | `zoneId` | path | string | yes | Zone id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/layouts/{id}/zones/{zoneId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Layout id. | | `data.zones` | array of LayoutZone | Every zone, in paint order. | | `data.zones[].id` | string | | | `data.zones[].name` | string | | | `data.zones[].x` | number | Left edge, in layout pixels. | | `data.zones[].y` | number | | | `data.zones[].w` | number | | | `data.zones[].h` | number | | | `data.zones[].locked` | boolean | | | `data.zones[].contentName` | string | Label of the bound content. Absent on the zone a new layout starts with. | | `data.zones[].content` | object \| null | What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`). | | `data.zones[].zIndex` | number | | | `data.zones[].ownerScope` | "workspace" \| "org_unit" \| "location" | | | `data.zones[].ownerNodeId` | string \| null | | | `data.zones[].frame` | "bare" \| "card" \| "accent" \| "glass" | Paint style on a themed layout. | | `data.zones[].radius` | number | Corner radius in layout pixels. | | `data.zones[].role` | "logo" | `logo`: the zone shows the Brand Kit logo instead of content. | 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 layout or zone in this workspace. Response 409: `conflict`: the layout changed during the write three times running; retry. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Me 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/me Describe the calling credential Returns who is calling and what they are allowed to do: whether the caller is a signed-in person, an API key, or Brix support; the location an API key is pinned to, if any; the workspace; and the caller's full set of permissions. Who is calling (API key, user, or Brix support), which workspace the call resolves to, and the permissions held. Call it first when a request is refused: `actor.nodeId` shows a key pinned to one location. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/me" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.actor` | object \| object \| object | The credential making the call: an API key, a user session, or Brix support. | | `data.workspace` | WorkspaceRef | | | `data.workspace.id` | string | Workspace id. | | `data.workspace.name` | string \| null | Workspace name; null only if the workspace row is missing. | | `data.permissions` | "all" \| array of string | `all` for an owner-style credential, else every `resource.verb` held anywhere in the workspace. A planning hint: node-scoped checks still run on each call. | | `data.paymentRequired` | object \| null | Set when every seat this person holds is in a location that pays before it goes live and has not paid yet: they can read, and add a card with `POST /v1/org-nodes/{id}/payment/checkout`; every other write answers 402 `payment_required`. Null otherwise. | ```json { "data": { "actor": { "kind": "key", "id": "key_6f7a8b9c0d1e2f3a", "name": "Menu board sync", "nodeId": null }, "workspace": { "id": "space_1a2b3c4d5e6f7a8b", "name": "Riverside Coffee" }, "permissions": [ "screen.view", "screen.cast", "media.view", "media.create" ], "paymentRequired": null } } ``` 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. ## Media (part 1 of 3) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/media List media Return the media library: images, videos, PDFs, presentations, fonts, web links, and app-backed assets. Use limit and cursor to page through results, count=1 to include a total count, search to search by name or tag, and the comma-separated kind, state, and folderId parameters to filter. Paging is optional but recommended, since a library can hold thousands of items. Without `limit`, every visible asset comes back unordered and without `nextCursor`. With `limit`, rows are newest first. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `search` | query | string | no | Case-insensitive match on name or tags. | | `kind` | query | string | no | Comma-separated kinds, e.g. `image,video`. | | `state` | query | string | no | Comma-separated processing states. | | `folderId` | query | string | no | Comma-separated folder ids. | | `usableAt` | query | string | no | Location id: only assets that may play there (own, root library, or shared in). | | `limit` | query | integer | no | Page size (max 500). Omit to get every row. | | `cursor` | query | string | no | The `nextCursor` of the previous page. | | `count` | query | "1" | no | With `limit`: also return `total`. | ```bash curl "https://api.brixsignage.com/v1/media" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of MediaAsset | | | `data[].id` | string | Media asset id. | | `data[].spaceId` | string | Workspace id. | | `data[].name` | string | | | `data[].kind` | string | Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value. | | `data[].url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data[].bytes` | integer | Stored size in bytes (0 for links and apps). | | `data[].checksum` | string \| null | | | `data[].active` | boolean | False when archived. | | `data[].folderId` | string \| null | | | `data[].tags` | any | Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON). | | `data[].altText` | string \| null | | | `data[].thumbnailUrl` | string \| null | | | `data[].width` | integer \| null | | | `data[].height` | integer \| null | | | `data[].durationSec` | number \| null | Video/audio length in seconds. | | `data[].pdfPageCount` | integer \| null | | | `data[].loopDurationMs` | integer \| null | Animated image loop length. | | `data[].fontFamily` | string \| null | | | `data[].fontWeights` | any \| null | Font assets: the weights in the file (decoded JSON). | | `data[].state` | string | Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, … | | `data[].stateReason` | string \| null | | | `data[].stateCode` | string \| null | | | `data[].stateFault` | "user" \| "platform" \| null | | | `data[].stateProgress` | integer \| null | | | `data[].codec` | string \| null | | | `data[].playableRev` | integer | Bumped whenever the playable bytes change. | | `data[].loopState` | "queued" \| "ready" \| "failed" \| null | | | `data[].loopCodecs` | string \| null | | | `data[].loopRev` | integer \| null | | | `data[].loopRotation` | integer \| null | | | `data[].loopBytes` | integer \| null | | | `data[].seqState` | "queued" \| "ready" \| "failed" \| null | Playlist-sequencer rendition state (video only; minted when the video plays in a run of consecutive videos). | | `data[].seqCodecs` | string \| null | | | `data[].seqRev` | integer \| null | | | `data[].seqRotation` | integer \| null | | | `data[].seqBytes` | integer \| null | | | `data[].seqConform` | integer \| null | | | `data[].masterKey` | string \| null | | | `data[].masterBytes` | integer \| null | | | `data[].masterProbe` | string \| null | | | `data[].rendition4k` | string \| null | | | `data[].frameLumaMean` | number \| null | | | `data[].frameLumaVariance` | number \| null | | | `data[].frameEdgeDensity` | number \| null | | | `data[].startsAt` | string \| null | Plays only from this time. | | `data[].expiresAt` | string \| null | Stops playing after this time. | | `data[].autoArchiveOnExpiry` | boolean | | | `data[].qr` | any \| null | QR overlay settings (decoded JSON). | | `data[].webConfig` | any \| null | Web link settings — refresh, zoom, header auth, … (decoded JSON). | | `data[].replayState` | "healthy" \| "replay_pending" \| "replay_failed" \| null | | | `data[].lastReplayAt` | string \| null | | | `data[].lastReplaySuccessAt` | string \| null | | | `data[].lastFailedStep` | integer \| null | | | `data[].lastFailedReason` | string \| null | | | `data[].autoCaption` | boolean | | | `data[].captionTrackKey` | string \| null | | | `data[].captionState` | "pending" \| "ready" \| "failed" \| null | | | `data[].showCaptions` | boolean | | | `data[].audioEnabled` | boolean | | | `data[].focalRegion` | string \| null | Smart-fit focal region, as stored JSON text. | | `data[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | How the asset fills a box. | | `data[].autoSmartFit` | boolean | | | `data[].rotation` | integer | Clockwise rotation in degrees. | | `data[].originalFormat` | string \| null | | | `data[].packageEntry` | string \| null | | | `data[].packageFiles` | integer \| null | | | `data[].packageBytes` | integer \| null | | | `data[].importSourceId` | string \| null | | | `data[].copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data[].nodeId` | string \| null | Home location; null = workspace library root. | | `data[].recalledAt` | string \| null | | | `data[].recalledBy` | string \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | | | `data[].usageCount` | integer | Playlists, schedules, layouts, creatives, boards and screens that use this asset. | | `data[].uploadedByName` | string \| null | Who uploaded it, from the audit log. | | `data[].uploadSource` | "ui" \| "api" \| "mcp" \| null | How it was uploaded. | | `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. | ```json { "data": [ { "id": "med_0c1d2e3f4a5b6c7d", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "lunch-special.jpg", "kind": "image", "url": "/v1/media/med_0c1d2e3f4a5b6c7d/file", "bytes": 482113, "checksum": null, "active": true, "folderId": null, "tags": [ "menu", "lunch" ], "altText": "Grilled chicken wrap with fries", "thumbnailUrl": null, "width": 1920, "height": 1080, "durationSec": null, "pdfPageCount": null, "loopDurationMs": null, "fontFamily": null, "fontWeights": null, "state": "ready", "stateReason": null, "stateCode": null, "stateFault": null, "stateProgress": null, "codec": null, "playableRev": 0, "loopState": null, "loopCodecs": null, "loopRev": null, "loopRotation": null, "loopBytes": null, "seqState": null, "seqCodecs": null, "seqRev": null, "seqRotation": null, "seqBytes": null, "seqConform": null, "masterKey": null, "masterBytes": null, "masterProbe": null, "rendition4k": null, "frameLumaMean": null, "frameLumaVariance": null, "frameEdgeDensity": null, "startsAt": null, "expiresAt": null, "autoArchiveOnExpiry": false, "qr": null, "webConfig": null, "replayState": null, "lastReplayAt": null, "lastReplaySuccessAt": null, "lastFailedStep": null, "lastFailedReason": null, "autoCaption": false, "captionTrackKey": null, "captionState": null, "showCaptions": true, "audioEnabled": false, "focalRegion": null, "fit": "contain", "autoSmartFit": true, "rotation": 0, "originalFormat": null, "packageEntry": null, "packageFiles": null, "packageBytes": null, "importSourceId": null, "nodeId": null, "recalledAt": null, "recalledBy": null, "createdAt": "2026-09-20T10:15:00.000Z", "updatedAt": "2026-09-20T10:15:00.000Z", "deletedAt": null, "usageCount": 2, "uploadedByName": "Sam Rivera", "uploadSource": "ui" } ], "nextCursor": null, "total": 1 } ``` 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/media Create a media item Create a media asset record for a file whose bytes are already stored elsewhere, by providing name, kind, and url. This creates only the metadata record; to upload new file bytes, use POST /v1/media/upload, PUT /v1/media/upload/:uploadId, or POST /v1/media/import-url instead. **Notes.** - The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column. - Use this for links (web pages, streams, dashboards). To add a FILE, use POST /v1/media/upload, the multipart upload, or POST /v1/media/import-url. Auth: Bearer token. Permission: `media.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `kind` | string | yes | | | `url` | string | yes | An https URL, a /v1/ path, or (for a web link) the page address. Private and internal network addresses are refused. | | `active` | boolean | no | | | `folderId` | string \| null | no | | | `tags` | array of string | no | | | `altText` | string \| null | no | | | `thumbnailUrl` | string \| null | no | | | `width` | integer \| null | no | | | `height` | integer \| null | no | | | `durationSec` | number \| null | no | | | `startsAt` | string \| null | no | | | `expiresAt` | string \| null | no | | | `autoArchiveOnExpiry` | boolean | no | | | `qr` | object \| null | no | | | `webConfig` | object \| null | no | Web link settings (refresh, zoom, …). | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `audioEnabled` | boolean | no | | | `fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/media" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Media asset id. | | `data.spaceId` | string | Workspace id. | | `data.name` | string | | | `data.kind` | string | Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value. | | `data.url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data.bytes` | integer | Stored size in bytes (0 for links and apps). | | `data.active` | boolean | False when archived. | | `data.tags` | any | Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON). | | `data.state` | string | Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, … | | `data.autoArchiveOnExpiry` | boolean | | | `data.nodeId` | string \| null | Home location; null = workspace library root. | | `data.folderId` | string \| null | | | `data.altText` | string \| null | | | `data.thumbnailUrl` | string \| null | | | `data.width` | integer \| null | | | `data.height` | integer \| null | | | `data.durationSec` | number \| null | Video/audio length in seconds. | | `data.startsAt` | string \| null | Plays only from this time. | | `data.expiresAt` | string \| null | Stops playing after this time. | | `data.qr` | any \| null | QR overlay settings (decoded JSON). | | `data.webConfig` | any \| null | Web link settings — refresh, zoom, header auth, … (decoded JSON). | | `data.audioEnabled` | boolean | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | How the asset fills a box. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | null | | Response 400: `fit` is not a known value. Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: The folder or location does not exist. Response 422: `name`, `kind` or `url` is missing, or `kind` is unknown. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id} Get a media asset Return one media asset with its full details, including kind, url, dimensions, duration, tags, folder, play window, and web configuration. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | MediaAssetDetail | One media asset, as GET /v1/media/{id} returns it. | | `data.id` | string | Media asset id. | | `data.spaceId` | string | Workspace id. | | `data.name` | string | | | `data.kind` | string | Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value. | | `data.url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data.bytes` | integer | Stored size in bytes (0 for links and apps). | | `data.checksum` | string \| null | | | `data.active` | boolean | False when archived. | | `data.folderId` | string \| null | | | `data.tags` | any | Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON). | | `data.altText` | string \| null | | | `data.thumbnailUrl` | string \| null | | | `data.width` | integer \| null | | | `data.height` | integer \| null | | | `data.durationSec` | number \| null | Video/audio length in seconds. | | `data.pdfPageCount` | integer \| null | | | `data.loopDurationMs` | integer \| null | Animated image loop length. | | `data.fontFamily` | string \| null | | | `data.fontWeights` | any \| null | Font assets: the weights in the file (decoded JSON). | | `data.state` | string | Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, … | | `data.stateReason` | string \| null | | | `data.stateCode` | string \| null | | | `data.stateFault` | "user" \| "platform" \| null | | | `data.stateProgress` | integer \| null | | | `data.codec` | string \| null | | | `data.playableRev` | integer | Bumped whenever the playable bytes change. | | `data.loopState` | "queued" \| "ready" \| "failed" \| null | | | `data.loopCodecs` | string \| null | | | `data.loopRev` | integer \| null | | | `data.loopRotation` | integer \| null | | | `data.loopBytes` | integer \| null | | | `data.seqState` | "queued" \| "ready" \| "failed" \| null | Playlist-sequencer rendition state (video only; minted when the video plays in a run of consecutive videos). | | `data.seqCodecs` | string \| null | | | `data.seqRev` | integer \| null | | | `data.seqRotation` | integer \| null | | | `data.seqBytes` | integer \| null | | | `data.seqConform` | integer \| null | | | `data.masterKey` | string \| null | | | `data.masterBytes` | integer \| null | | | `data.masterProbe` | string \| null | | | `data.rendition4k` | string \| null | | | `data.frameLumaMean` | number \| null | | | `data.frameLumaVariance` | number \| null | | | `data.frameEdgeDensity` | number \| null | | | `data.startsAt` | string \| null | Plays only from this time. | | `data.expiresAt` | string \| null | Stops playing after this time. | | `data.autoArchiveOnExpiry` | boolean | | | `data.qr` | any \| null | QR overlay settings (decoded JSON). | | `data.webConfig` | any \| null | Web link settings — refresh, zoom, header auth, … (decoded JSON). | | `data.replayState` | "healthy" \| "replay_pending" \| "replay_failed" \| null | | | `data.lastReplayAt` | string \| null | | | `data.lastReplaySuccessAt` | string \| null | | | `data.lastFailedStep` | integer \| null | | | `data.lastFailedReason` | string \| null | | | `data.autoCaption` | boolean | | | `data.captionTrackKey` | string \| null | | | `data.captionState` | "pending" \| "ready" \| "failed" \| null | | | `data.showCaptions` | boolean | | | `data.audioEnabled` | boolean | | | `data.focalRegion` | string \| null | Smart-fit focal region, as stored JSON text. | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | How the asset fills a box. | | `data.autoSmartFit` | boolean | | | `data.rotation` | integer | Clockwise rotation in degrees. | | `data.originalFormat` | string \| null | | | `data.packageEntry` | string \| null | | | `data.packageFiles` | integer \| null | | | `data.packageBytes` | integer \| null | | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.nodeId` | string \| null | Home location; null = workspace library root. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.usageCount` | integer | Playlists, schedules, layouts, creatives, boards and screens that use this asset. | | `data.uploadedByName` | string \| null | Who uploaded it, from the audit log. | | `data.uploadSource` | "ui" \| "api" \| "mcp" \| null | How it was uploaded. | | `data.format` | string \| null | File format read from the stored bytes (`PNG`, `MP4 (hevc)`), only when the name has no usable extension; otherwise 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 asset in this workspace (or it is in the recycle bin). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/media/{id} Update a media asset Edit a media asset. Accepts name, altText, tags, folderId, node, play-window fields (startsAt, expiresAt, autoArchiveOnExpiry), audioEnabled, a QR code overlay, and web configuration. Changing the URL of a web-kind asset re-checks it to make sure it is safe to fetch. Send only the fields to change. `state` and `bytes` are set by processing and ignored here. **Notes.** - The response is the stored row, not the GET shape: it has no `usageCount`, `uploadedByName` or `uploadSource`. - An invalid `fit` answers 400 with only `error` (no `message`); every other validation failure is 422 `validation_error`. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `kind` | string | no | | | `url` | string | no | An https URL, a /v1/ path or a data:image URI; for a web link, the page address (private and internal network addresses are refused). | | `active` | boolean | no | False archives the asset. | | `folderId` | string \| null | no | | | `tags` | array of string | no | | | `altText` | string \| null | no | | | `thumbnailUrl` | string \| null | no | | | `width` | integer \| null | no | | | `height` | integer \| null | no | | | `durationSec` | number \| null | no | | | `startsAt` | string \| null | no | | | `expiresAt` | string \| null | no | | | `autoArchiveOnExpiry` | boolean | no | | | `qr` | object \| null | no | | | `webConfig` | object \| null | no | | | `nodeId` | string \| null | no | Move to another location (needs media.edit there). | | `audioEnabled` | boolean | no | | | `fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | no | | | `baseUpdatedAt` | string | no | The `updatedAt` your edit is based on. When set and the row has moved since, the write is refused with 409 and the current row. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/media/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | MediaAssetUpdated | The stored row after a PATCH, without the list-only fields. | | `data.id` | string | Media asset id. | | `data.spaceId` | string | Workspace id. | | `data.name` | string | | | `data.kind` | string | Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value. | | `data.url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data.bytes` | integer | Stored size in bytes (0 for links and apps). | | `data.checksum` | string \| null | | | `data.active` | boolean | False when archived. | | `data.folderId` | string \| null | | | `data.tags` | any | Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON). | | `data.altText` | string \| null | | | `data.thumbnailUrl` | string \| null | | | `data.width` | integer \| null | | | `data.height` | integer \| null | | | `data.durationSec` | number \| null | Video/audio length in seconds. | | `data.pdfPageCount` | integer \| null | | | `data.loopDurationMs` | integer \| null | Animated image loop length. | | `data.fontFamily` | string \| null | | | `data.fontWeights` | any \| null | Font assets: the weights in the file (decoded JSON). | | `data.state` | string | Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, … | | `data.stateReason` | string \| null | | | `data.stateCode` | string \| null | | | `data.stateFault` | "user" \| "platform" \| null | | | `data.stateProgress` | integer \| null | | | `data.codec` | string \| null | | | `data.playableRev` | integer | Bumped whenever the playable bytes change. | | `data.loopState` | "queued" \| "ready" \| "failed" \| null | | | `data.loopCodecs` | string \| null | | | `data.loopRev` | integer \| null | | | `data.loopRotation` | integer \| null | | | `data.loopBytes` | integer \| null | | | `data.seqState` | "queued" \| "ready" \| "failed" \| null | Playlist-sequencer rendition state (video only; minted when the video plays in a run of consecutive videos). | | `data.seqCodecs` | string \| null | | | `data.seqRev` | integer \| null | | | `data.seqRotation` | integer \| null | | | `data.seqBytes` | integer \| null | | | `data.seqConform` | integer \| null | | | `data.masterKey` | string \| null | | | `data.masterBytes` | integer \| null | | | `data.masterProbe` | string \| null | | | `data.rendition4k` | string \| null | | | `data.frameLumaMean` | number \| null | | | `data.frameLumaVariance` | number \| null | | | `data.frameEdgeDensity` | number \| null | | | `data.startsAt` | string \| null | Plays only from this time. | | `data.expiresAt` | string \| null | Stops playing after this time. | | `data.autoArchiveOnExpiry` | boolean | | | `data.qr` | any \| null | QR overlay settings (decoded JSON). | | `data.webConfig` | any \| null | Web link settings — refresh, zoom, header auth, … (decoded JSON). | | `data.replayState` | "healthy" \| "replay_pending" \| "replay_failed" \| null | | | `data.lastReplayAt` | string \| null | | | `data.lastReplaySuccessAt` | string \| null | | | `data.lastFailedStep` | integer \| null | | | `data.lastFailedReason` | string \| null | | | `data.autoCaption` | boolean | | | `data.captionTrackKey` | string \| null | | | `data.captionState` | "pending" \| "ready" \| "failed" \| null | | | `data.showCaptions` | boolean | | | `data.audioEnabled` | boolean | | | `data.focalRegion` | string \| null | Smart-fit focal region, as stored JSON text. | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" | How the asset fills a box. | | `data.autoSmartFit` | boolean | | | `data.rotation` | integer | Clockwise rotation in degrees. | | `data.originalFormat` | string \| null | | | `data.packageEntry` | string \| null | | | `data.packageFiles` | integer \| null | | | `data.packageBytes` | integer \| null | | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.nodeId` | string \| null | Home location; null = workspace library root. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | Response 400: `fit` is not one of contain, cover, fill, blur-fill. Response 401: Missing, expired or revoked bearer token. Response 403: Moving it to a location where you lack media.edit, or attaching an SSO connection without settings.edit. Response 404: No such asset in this workspace. Response 409: `conflict`: `baseUpdatedAt` is stale; the body carries `current`. Response 422: Invalid kind, URL, folder or location. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Media (part 2 of 3) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### DELETE /v1/media/{id} Delete a media asset Move a media asset to the recycle bin. Playlists and screens that reference it show a gap where the asset was until it is restored or replaced. Moves the asset to the recycle bin (restorable for 30 days) and removes it from every playlist. Screens casting it return to their schedule. Auth: Bearer token. Permission: `media.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | | `force` | query | "true" | no | Delete even when it is shared into other places. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/media/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | Shares removed with it. | 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 asset in this workspace. Response 409: `content_shared`: the item is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/captions Get a video's captions Return a video's caption track as WebVTT. Add ?lang= to request a machine-translated version, for example ?lang=es for Spanish. This URL is stable, so it can be referenced directly by a player. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | | `lang` | query | string | no | Two- or three-letter language code: a machine translation of the track (default: the original). | ```bash curl "https://api.brixsignage.com/v1/media/{id}/captions" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 media with this id, or it has no captions. Response 429: More than 60 reads a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/captions Generate captions for a video Automatically generate a caption track for a video from its audio and attach it to the asset. To upload a caption file instead, use the caption upload operation. To show or hide an existing caption track, use the caption visibility operation. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.key` | string | Storage path of the caption track. | | `data.state` | "ready" | | Response 400: `wrong_kind`: not a video. 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 media with this id, or no bytes. Response 413: Over 40 MB: send the audio to /captions/transcribe instead. Response 502: `transcription_failed`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/captions/transcribe Generate captions from a video's audio Convert a short audio clip, extracted from a video as 16 kHz mono WAV, into a caption track. Use this instead of the standard caption-generation operation when the full video file is too large to process directly. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `application/octet-stream` ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/transcribe" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.key` | string | Storage path of the caption track. | | `data.state` | "ready" | | Response 400: `wrong_kind`: not a video. 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 media with this id. Response 413: Over 20 MB. Response 422: Empty body. Response 502: `transcription_failed`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/captions/upload Upload a caption file Attach a caption file to a video. SRT files are converted to WebVTT; WebVTT files are stored as-is. This is the alternative to automatic caption generation. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `text/vtt` ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/upload" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.key` | string | Storage path of the caption track. | | `data.state` | "ready" | | Response 400: `wrong_kind`: not a video. 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 media with this id. Response 413: Over 5 MB. Response 415: Not a .vtt or .srt track. Response 422: Empty body. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/captions/visibility Show or hide a video's captions Turn a video's caption track on or off for playback. Hiding the track keeps it in storage so it can be shown again later. If no caption track exists yet, the response indicates that one must be generated first. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `show` | boolean | no | True shows captions; anything else hides them. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/visibility" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.state` | "hidden" \| "ready" \| "needs_audio" | `needs_audio`: shown, but the video has no caption track yet. | Response 400: `wrong_kind`: not a video. 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 media with this id. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/delta Check for a media delta download Used by playback devices to check whether their cached copy of a file is current. The caller sends the checksum of its cached copy and receives either the data needed to update it, or a flag indicating no partial update is available along with a URL to download the full file. **Notes.** - Reserved: delta downloads are not offered yet, so this always answers `deltaAvailable: false`. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/delta" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.deltaAvailable` | false | | | `data.downloadUrl` | null | | 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/media/{id}/file Download a media file Stream the media asset's file bytes. Supports HTTP Range requests for partial downloads. **Notes.** - HTML, SVG and script files are served as `application/octet-stream` attachments, never inline. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | | `w` | query | string | no | Images: resize to this width (a thumbnail). | | `h` | query | string | no | Images: resize to this height. | | `fit` | query | "cover" \| "contain" \| "scale-down" \| "crop" \| "pad" | no | How a resized copy fits `w` × `h` (default `cover`). | ```bash curl "https://api.brixsignage.com/v1/media/{id}/file" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 media with this id, or the file is not in storage. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/focal-region Detect an image's focal region Detect the main subject of an image and cache its position as a normalized x, y, width, and height. This lets the image be cropped around its subject when shown in a differently shaped area, instead of being cropped from the center. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/focal-region" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.region` | object \| null | Fractions (0–1) of the image. Null when nothing stood out; the stored region is then unchanged. | Response 400: `wrong_kind`: not an image. 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 media with this id, or no bytes. Response 413: Over 32 MB. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/lan-preview Get the preview of an on-network page Read the newest picture a screen took of this on-network web page, and the state of the newest request for one. A web page on a local network cannot be reached from the cloud, so only a screen on that network can take the picture. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/lan-preview" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/lan-preview Ask a screen for a preview of an on-network page Ask an online screen to take a picture of this on-network web page. Screens the page is assigned to are tried first, then its location, then the workspace. A second request within 30 seconds joins the one already running. Answers 422 for a page that is not on-network. Auth: Bearer token. Permission: `screen.command-sent`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/lan-preview" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/lan-preview/file Download the preview of an on-network page Download the newest picture a screen took of this on-network web page. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/lan-preview/file" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/playback-quality Get a video's playback quality Return dropped-frame data reported by screens that have played this video, used to flag videos that are not playing smoothly. A null health value means the asset has not been measured yet, not that it is playing well. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/playback-quality" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.failures` | object \| null | Null when the item failed on no screen in the window. | | `data.health` | object \| null | Null until a screen reports on this video. | | `data.stutterDropPct` | number | Dropped-frame percentage above which a screen counts as struggling. | | `data.minSamplesToWarn` | integer | | | `data.screens` | array of object | | | `data.screens[].screenId` | string | | | `data.screens[].worstDropPct` | number | | | `data.screens[].meanDropPct` | number | | | `data.screens[].samples` | integer | | | `data.screens[].videoWidth` | integer \| null | | | `data.screens[].videoHeight` | integer \| null | | | `data.screens[].lastSeenAt` | string | ISO-8601 timestamp (UTC). | 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/media/{id}/poster Get a media poster image Return the poster image attached to a media asset, used as its thumbnail for videos and PDFs. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | | `w` | query | string | no | Resize to this width. | | `h` | query | string | no | Resize to this height. | | `fit` | query | "cover" \| "contain" \| "scale-down" \| "crop" \| "pad" | no | | ```bash curl "https://api.brixsignage.com/v1/media/{id}/poster" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 media with this id, or it has no poster. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/poster Set or generate a media poster Attach a poster image to a media asset, used as its thumbnail. The file must be an image and no larger than 4 MB. **Notes.** - With `?generate=1` the body is `{ thumbnailUrl, generated }` and no request body is read. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | | `generate` | query | "1" | no | `1`: generate the poster from the media itself (send no body). | Request body: `image/*` ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/poster" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | 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 media with this id. Response 413: Over 4 MB. Response 415: Not a recognised image. Response 422: Empty body. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/render Render a web link now Capture and store a screenshot of a web or link asset. If screenshot rendering is not available for this workspace, the response reports that it is not configured rather than failing. **Notes.** - Usually queued (`queued: true`); the frame is then at GET /v1/media/{id}/render-frame. - A second request while a render of the same link with the same settings is still queued or running returns `queued: true` and adds nothing. After an edit, the request queues a render of the new settings. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/render" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | 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 media with this id. Response 429: More than 60 renders a minute, or the workspace already has 4 web renders queued (`renders_busy`, retry after the Retry-After). Response 502: The render failed. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/render-frame Get a web link's latest render Return the most recent screenshot generated for a web or link asset by the render operation. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/render-frame" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 media with this id, or the link has not been rendered yet (a render is then queued). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/restore Restore a deleted media item Bring back a deleted media asset. Any playlist or screen still referencing it resumes rendering it. Auth: Bearer token. Permission: `media.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{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 media with this id. Response 409: `not_deleted`: it is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/rotate Rotate a photo or video 90, 180, or 270 degrees clockwise. This rewrites the stored file rather than only changing how it is displayed, since playback devices cannot rotate video at display time. Images are rotated immediately; video rotation is queued, and the asset keeps playing its current version until the rotated file is ready. **Notes.** - Photos rotate now (`rotated`); videos are re-encoded in the background (`queued`). Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `degrees` | 90 \| 180 \| 270 | yes | Clockwise. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/rotate" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 400: `degrees` is not 90, 180 or 270, or the item is not a photo or video. 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 media with this id, or its bytes are gone. Response 409: A rotation is already running. Response 502: The image service failed. Response 503: Rotation is not available. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/{id}/suggest Suggest alt text and tags for an image Analyze an image asset and return suggested altText and tags. This only returns suggestions; it does not save them, so use the update-media-asset operation to accept them. Only images are supported. If this feature is temporarily unavailable, the response returns empty values rather than failing. **Notes.** - Suggestions only: nothing is saved. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/{id}/suggest" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.altText` | string \| null | | | `data.tags` | array of string | | Response 400: `wrong_kind`: not an image. 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 media with this id, or no bytes. Response 413: Over 32 MB. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/{id}/usage Show where a media asset is used Return where a media asset is used, across playlists, creatives, and layouts, along with when it was last played. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | ```bash curl "https://api.brixsignage.com/v1/media/{id}/usage" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | MediaUsage | | | `data.containers` | array of object | | | `data.containers[].id` | string | | | `data.containers[].name` | string | | | `data.containers[].kind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "signage" | `signage` = a signage template (board). | | `data.containers[].itemCount` | integer | Playlists only: total items in the playlist. | | `data.screens` | array of object | Active screens showing it now, directly or through one of the containers. | | `data.screens[].id` | string | | | `data.screens[].name` | string | | | `data.screens[].location` | string \| null | | | `data.screens[].status` | string | `online`, `offline` or `pairing`. | | `data.lastPlayedAt` | string \| null | Last completed play reported by a screen; null if never played. | 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 asset in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/media/{id}/web-secrets Set a web link's secrets Store credentials, such as authentication tokens or login passwords, for a web asset. Values are encrypted at rest and write-only: send an object mapping reference names to values, where a null value deletes that reference. Only the reference names, never the values, can be read back later. This merges with any existing secrets rather than replacing them. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media asset id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `secrets` | object | yes | Secret name → value (at most 50, values ≤ 8192 characters). `null` or `""` removes one; names not sent are kept. | | `expect` | object | no | The link's `url` and `webConfig` as you last read them. Send it: the secrets are stored only if the link still sends them to that address and those sign-in steps, else 409. | | `expect.url` | string | yes | | | `expect.webConfig` | any | yes | | ```bash curl -X PUT "https://api.brixsignage.com/v1/media/{id}/web-secrets" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.refs` | array of string | The secret NAMES now stored. Values are never returned. | Response 400: Too many secrets, a name or value too long, or a malformed `expect`. 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 media with this id. Response 409: The link's address or sign-in steps changed (or are not what `expect` says). Nothing was stored. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Media (part 3 of 3) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/media/backfill-avif Convert AVIF images Convert this workspace's existing AVIF image assets to JPEG. Auth: Bearer token. Permission: `media.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | no | | | `after` | string | no | `nextAfter` of the previous run. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/backfill-avif" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.scanned` | integer | | | `data.transcoded` | integer | | | `data.rows` | array of object | | | `data.rows[].id` | string | | | `data.rows[].name` | string \| null | | | `data.rows[].result` | "source_gone" \| "undecodable" \| "service_error" \| "binding_absent" \| "transcoded" \| "already_done" \| "not_avif" | | | `data.nextAfter` | string \| null | Pass as `after` to continue; null when done. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 10 runs a minute. Response 503: `binding_absent`: image conversion is not available. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/backfill-codec-warnings Re-check codec warnings Recompute codec-compatibility warnings for this workspace's video assets under the current compatibility rules, and clear any outdated re-export warnings. Safe to run more than once. Auth: Bearer token. Permission: `media.edit`. ```bash curl -X POST "https://api.brixsignage.com/v1/media/backfill-codec-warnings" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.scanned` | integer | | | `data.cleared` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 10 runs a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/backfill-heic Convert HEIC images Convert this workspace's existing HEIC image assets to JPEG so they display correctly on devices that cannot decode HEIC. Safe to run more than once, and applies only to your own workspace. Returns a 503 error if the conversion feature is temporarily unavailable. Auth: Bearer token. Permission: `media.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | no | | | `after` | string | no | `nextAfter` of the previous run. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/backfill-heic" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.scanned` | integer | | | `data.transcoded` | integer | | | `data.rows` | array of object | | | `data.rows[].id` | string | | | `data.rows[].name` | string \| null | | | `data.rows[].result` | "source_gone" \| "undecodable" \| "service_error" \| "binding_absent" \| "transcoded" \| "already_done" \| "not_heic" | | | `data.nextAfter` | 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 429: More than 10 runs a minute. Response 503: `binding_absent`: HEIC conversion is not available. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/backfill-video-metadata Fill in missing video details Scan this workspace's existing video files to fill in missing width, height, and duration values, and correct codec information that was guessed from the filename. Also updates the codec-compatibility warning where applicable. Auth: Bearer token. Permission: `media.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | no | Most videos to read this run. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/backfill-video-metadata" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.scanned` | integer | | | `data.updated` | integer | | | `data.reclassified` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 429: More than 10 runs a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/bulk-delete Delete media in bulk Move up to 500 media items to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in `ok` and the rest in `failed`, so one failure does not stop the rest. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/media/bulk-delete" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/import-url Import media from a URL Import a file from a remote URL into the media library. The API fetches the file server-side, checking that the URL does not point to a disallowed destination, stores its bytes, and creates the media asset record. This is the same path used by the upload_media_from_url tool. Fetches a public http(s) URL into the library. SVG is refused. **Notes.** - The response is the row as built for insert, not the GET shape: `tags` is a JSON string (not an array), `sourceUrl` is present but not stored, and most columns (state, fit, width, …) are absent. Read GET /v1/media/{id} for the settled asset. Auth: Bearer token. Permission: `media.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | yes | Public http(s) address of the file. | | `name` | string | no | Display name; defaults to the file name in the URL. | | `folderId` | string | no | | | `nodeId` | string | no | Home location; defaults to your own. | | `tags` | array of string | no | | | `autoCaption` | boolean | no | Videos: generate captions. | | `autoSmartFit` | boolean | no | Images: detect a focal region (default true). | ```bash curl -X POST "https://api.brixsignage.com/v1/media/import-url" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ImportedMedia | The row created by an import, before processing settles. | | `data.id` | string | Media asset id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.kind` | string | | | `data.url` | string | `/v1/media//file`. | | `data.bytes` | integer | | | `data.checksum` | string \| null | | | `data.active` | true | | | `data.folderId` | string \| null | | | `data.nodeId` | string \| null | | | `data.tags` | string | JSON-encoded array of strings — NOT decoded here, unlike GET /v1/media. | | `data.sourceUrl` | string | The URL that was imported. Not stored; returned by this route only. | | `data.autoCaption` | boolean | | | `data.captionState` | "pending" \| null | | | `data.autoSmartFit` | boolean | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 413: `too_large`: the file is over the size limit for its kind. Response 415: `unsupported_type`: SVG or an unknown content type. Response 422: Missing or non-http URL, a blocked address (`url_blocked`), or an unknown folder or location. Response 502: `fetch_failed` / `source_status`: the source did not answer with the file. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/moderate Check text for unsafe content Run a safety classifier over a piece of user-submitted text, such as banner copy or a message board post, and return its verdict. This operation only classifies the text; it does not store it. Auth: Bearer token. Permission: `media.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `text` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/media/moderate" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.flagged` | boolean | | | `data.reason` | string | Present when flagged. | | `data.checked` | boolean | False when the check could not run (the text is then not flagged). | Response 400: `text` is missing. 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/media/stats Get media library statistics Return summary counts for the media library in one response: total assets, unused assets, and a count per folder. Use this instead of listing all media when only summary counts are needed. Auth: Bearer token. Permission: `media.view`. ```bash curl "https://api.brixsignage.com/v1/media/stats" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.total` | integer | | | `data.unused` | integer | Items used nowhere. | | `data.folders` | array of object | Items per folder; `folderId` null = not in a folder. | | `data.folders[].folderId` | string \| null | | | `data.folders[].count` | integer | | 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/media/upload Upload a media file Upload a file in a single request using multipart form data. Accepts form fields file (required), and optional name, nodeId, and folderId. This stores the file and creates the media asset record in one step, and is safe to retry with the same Idempotency-Key header. For large files or programmatic clients, minting an upload URL and then uploading with PUT is usually simpler. **Notes.** - Form fields other than `file` are strings, as multipart sends them. - For files over ~100 MB use the multipart upload. Auth: Bearer token. Permission: `media.create`. Request body: `multipart/form-data` | Field | Type | Required | Description | | --- | --- | --- | --- | | `file` | string (binary) | yes | The file. SVG is refused. | | `name` | string | no | Display name; default the file name. | | `nodeId` | string | no | Home location; default the caller's own. | | `folderId` | string | no | | | `alt` | string | no | Alt text. | | `decorative` | "1" | no | `1`: the image is decorative (empty alt text). | | `autoCaption` | "1" | no | Videos: `1` generates captions. | | `autoSmartFit` | "0" \| "1" | no | Images: `0` skips focal-region detection (default on). | | `durationSec` | string | no | Videos: length in seconds, when the client measured it. | | `loopDurationMs` | string | no | Animated images: loop length. | | `width` | string | no | | | `height` | string | no | | | `codec` | string | no | | | `codecString` | string | no | | | `fps` | string | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/media/upload" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | UploadedMedia | The media row an upload creates, before processing settles. | | `data.id` | string | Media asset id. | | `data.spaceId` | string | Workspace id. | | `data.nodeId` | string \| null | Home location; null = workspace library root. | | `data.folderId` | string \| null | | | `data.name` | string | | | `data.kind` | string | Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value. | | `data.url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data.bytes` | integer | Stored size in bytes (0 for links and apps). | | `data.checksum` | string | SHA-256 of the bytes. | | `data.active` | boolean | False when archived. | | `data.altText` | string \| null | | | `data.width` | integer \| null | | | `data.height` | integer \| null | | | `data.durationSec` | number \| null | Video/audio length in seconds. | | `data.loopDurationMs` | integer \| null | Animated image loop length. | | `data.fontFamily` | string \| null | | | `data.fontWeights` | array of integer \| null | Font files: the weights in the file. | | `data.state` | "ready" \| "failed" \| "processing" \| "ready_with_warnings" \| "needs_action" | | | `data.stateReason` | string \| null | | | `data.stateCode` | string \| null | | | `data.stateFault` | "user" \| "platform" \| null | | | `data.codec` | string \| null | | | `data.frameLumaMean` | number \| null | | | `data.frameLumaVariance` | number \| null | | | `data.frameEdgeDensity` | number \| null | | | `data.autoCaption` | boolean | | | `data.captionState` | "pending" \| null | | | `data.autoSmartFit` | boolean | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | 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: The folder or location does not exist. Response 413: The file is over the limit for its kind (images 250 MB, video 2 GB, documents 100 MB, fonts 10 MB). Response 415: SVG, or a type the library does not take. Response 422: `file` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/media/upload/{uploadId} Upload bytes to a minted upload URL Upload the raw file bytes for a previously created upload slot. Send the file as the request body and set the Content-Type header to match the file's type. After uploading, finalize the upload to create the media asset record. **Notes.** - This stores the bytes for a bulk import; the import itself creates the media rows. Auth: Bearer token. Permission: `media.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `uploadId` | path | string | yes | An `upl_…` id from POST /v1/import/upload-urls. | Request body: `application/octet-stream` ```bash curl -X PUT "https://api.brixsignage.com/v1/media/upload/{uploadId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.uploadId` | string | | | `data.bytes` | integer | | 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 mint with this id in this workspace. Response 413: Over 500 MB. Response 415: SVG. Response 422: Empty body or a malformed id. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media/upload/multipart/{id} Get a multipart upload's progress Return the state of an in-progress multipart upload, including the file's name, size, kind, part size, and every part already received, each with its part number, ETag, and size. Use this to resume an interrupted upload from the last completed part instead of starting over. Returns 404 if the upload belongs to another workspace, has already finished, or has expired. Auth: Bearer token. Permission: `media.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The upload's media id, from `POST /v1/media/upload/multipart/create`. | ```bash curl "https://api.brixsignage.com/v1/media/upload/multipart/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.name` | string | | | `data.contentType` | string | | | `data.kind` | string | | | `data.sizeBytes` | integer | | | `data.partSize` | integer | | | `data.masterOf` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.parts` | array of object | Parts already stored: resume from the first missing one. | | `data.parts[].partNumber` | integer | | | `data.parts[].etag` | string | | | `data.parts[].size` | integer | | 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 upload. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/upload/multipart/{id}/abort Cancel a multipart upload Cancel an in-progress multipart upload and discard any parts already received. Safe to call more than once. **Notes.** - Answers `aborted: true` also when there was nothing to cancel. Auth: Bearer token. Permission: `media.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The upload's media id, from `POST /v1/media/upload/multipart/create`. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/upload/multipart/{id}/abort" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.aborted` | true | | 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/media/upload/multipart/{id}/complete Complete a multipart upload Finalize a multipart upload by sending the list of uploaded parts, each with partNumber and etag. If the list is left empty, the server completes the upload using the parts it already has on record, so a client resuming an interrupted upload does not need to know every part's ETag. This creates the media asset record; video files are automatically queued for processing. **Notes.** - For a master upload (`masterOf`) the body is `{ id, masterKey, masterBytes }`; otherwise it is the new media row. Auth: Bearer token. Permission: `media.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The upload's media id, from `POST /v1/media/upload/multipart/create`. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `parts` | array of object | yes | | | `parts[].partNumber` | integer | yes | | | `parts[].etag` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/media/upload/multipart/{id}/complete" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | 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 upload. Response 409: A part is missing or does not match. Response 422: No parts. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/media/upload/multipart/{id}/part/{partNumber} Upload one part of a multipart upload Upload one part of a file for an in-progress multipart upload, identified by its part number. Returns the part's ETag, which is needed to complete the upload. Returns 404 if the upload belongs to another workspace. Auth: Bearer token. Permission: `media.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The upload's media id, from `POST /v1/media/upload/multipart/create`. | | `partNumber` | path | string | yes | 1-based part number. | Request body: `application/octet-stream` ```bash curl -X PUT "https://api.brixsignage.com/v1/media/upload/multipart/{id}/part/{partNumber}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.partNumber` | integer | | | `data.etag` | string | Send it back in `complete`. | 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 upload. Response 413: The part is larger than `partSize`. Response 422: Bad part number or empty part. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/upload/multipart/create Start a multipart upload Begin a multipart upload for large files, such as multi-gigabyte videos, that are too large for a single request. Validates the file kind and checks its size against the limit allowed for that kind. Returns an upload id and the part size to use for subsequent part uploads. Auth: Bearer token. Permission: `media.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `contentType` | string | no | The file's media type; decides the kind. | | `sizeBytes` | integer | yes | | | `folderId` | string \| null | no | | | `nodeId` | string \| null | no | | | `alt` | string \| null | no | | | `decorative` | boolean | no | | | `loopDurationMs` | number \| null | no | | | `durationSec` | number \| null | no | | | `width` | integer \| null | no | | | `height` | integer \| null | no | | | `codec` | string \| null | no | | | `codecString` | string \| null | no | | | `fps` | number \| null | no | | | `masterOf` | string \| null | no | An existing video's id: upload a high-resolution master for it instead of a new asset. | | `importSourceId` | string \| null | no | Your own id for the file. If a live asset already has it, the answer is 200 with `exists: true`. | ```bash curl -X POST "https://api.brixsignage.com/v1/media/upload/multipart/create" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success: `importSourceId` matched a live asset: `{ id, exists: true }`, nothing started. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 413: `sizeBytes` is over the limit for the kind. Response 415: SVG. Response 422: Unknown file type, or `sizeBytes` missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media/upload/package Upload an HTML5 package Upload a zipped HTML5 package as a media asset, using multipart form data with fields file (required), and optional name, nodeId, and folderId. The archive is validated, expanded into storage, and its entry page is identified automatically. Auth: Bearer token. Permission: `media.create`. Request body: `multipart/form-data` | Field | Type | Required | Description | | --- | --- | --- | --- | | `file` | string (binary) | yes | The .zip. It must hold an entry page (`index.html`). | | `name` | string | no | Display name; default the file name. | | `nodeId` | string | no | Home location; default the caller's own. | | `folderId` | string | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/media/upload/package" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Media asset id. | | `data.spaceId` | string | Workspace id. | | `data.nodeId` | string \| null | Home location; null = workspace library root. | | `data.folderId` | string \| null | | | `data.name` | string | | | `data.kind` | "package" | | | `data.url` | string | Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address. | | `data.bytes` | integer | Stored size in bytes (0 for links and apps). | | `data.checksum` | string | SHA-256 of the .zip. | | `data.active` | boolean | False when archived. | | `data.packageEntry` | string | The entry page found in the archive, e.g. `index.html`. | | `data.packageFiles` | integer | Files in the archive. | | `data.packageBytes` | integer | Expanded size of the archive, in bytes. | | `data.state` | "ready" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | 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: The folder or location does not exist. Response 413: The .zip, or its expanded contents, is over the limit. Response 422: `file` is missing, the .zip cannot be read, or a file in it is refused (unsafe path, type not allowed, no entry page). Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Media folders 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/media-folders List media folders Return the media library's folder tree for this workspace, including each folder's id, name, parent folder, and location. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | 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`. | | `usableAt` | query | string | no | Location id: only folders usable at that location. | ```bash curl "https://api.brixsignage.com/v1/media-folders" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of MediaFolder | | | `data[].id` | string | Media folder id. | | `data[].spaceId` | string | | | `data[].parentId` | string \| null | Parent folder; null = top level. | | `data[].name` | string | | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `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/media-folders Create a media folder Create a folder in the media library. Requires name; parentId and nodeId are optional. Omitting parentId places the folder at the root. **Notes.** - The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column. Auth: Bearer token. Permission: `media.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `parentId` | string \| null | no | | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | ```bash curl -X POST "https://api.brixsignage.com/v1/media-folders" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Media folder id. | | `data.spaceId` | string | | | `data.parentId` | string \| null | | | `data.name` | string | | | `data.nodeId` | string \| null | | | `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: The location does not exist. Response 422: `name` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/media-folders/{id} Get a media folder Return one media folder. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media folder id. | ```bash curl "https://api.brixsignage.com/v1/media-folders/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | MediaFolder | A folder in the media library. | | `data.id` | string | Media folder id. | | `data.spaceId` | string | | | `data.parentId` | string \| null | Parent folder; null = top level. | | `data.name` | string | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `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 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/media-folders/{id} Update a media folder Rename a media folder or move it to a different parent folder or location. Accepts optional name, parentId, and nodeId. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media folder id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `parentId` | string \| null | no | | | `nodeId` | string \| null | no | | | `baseUpdatedAt` | string | no | The `updatedAt` your edit is based on; 409 with the current row if it moved. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/media-folders/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | MediaFolder | A folder in the media library. | | `data.id` | string | Media folder id. | | `data.spaceId` | string | | | `data.parentId` | string \| null | Parent folder; null = top level. | | `data.name` | string | | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `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 folder with this id. Response 409: `conflict`: changed since `baseUpdatedAt`; the body carries `current`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/media-folders/{id} Delete a media folder Move a media folder to the recycle bin; it can be restored later. Assets inside the folder are not moved or deleted and keep their existing folder reference. Auth: Bearer token. Permission: `media.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media folder id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/media-folders/{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 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/media-folders/{id}/restore Restore a deleted media folder Bring back a deleted media folder so it reappears in the folder tree. Assets inside it keep whatever delete state they already had. Auth: Bearer token. Permission: `media.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Media folder id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media-folders/{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 folder with this id. Response 409: `not_deleted`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Media sync 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/media-sync List synced folders Return the workspace's synced folders, including the remote path, the destination folder in Brix, the connected account, sync status, the last error, the last check time, and the number of files synced. Only folders connected at locations where the caller holds the integration view permission are returned. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/media-sync" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].provider` | string | `onedrive` or `sharepoint`. | | `data[].remotePath` | string | | | `data[].folderId` | string | The library folder the files land in. | | `data[].folderName` | string \| null | | | `data[].accountLabel` | string \| null | | | `data[].accountConnected` | boolean | False when the connected account was removed: syncing stops until it is connected again. | | `data[].status` | "ok" \| "error" \| "paused" | | | `data[].lastError` | string \| null | | | `data[].lastSyncAt` | string \| null | | | `data[].itemsSynced` | integer | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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. ### DELETE /v1/media-sync/{id} Stop syncing a folder Stop following a remote folder. The sync source is removed, but files already imported are not affected. This action is recorded in the activity log. **Notes.** - The files already synced stay in the library. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Synced folder id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/media-sync/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | 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/media-sync/{id}/sync Sync a folder now Trigger an immediate sync of one connected folder, bounded to a fixed number of files for the run, and return a summary of what happened. This action is recorded in the activity log. **Notes.** - A failed run still answers 200: read `error`. Auth: Bearer token. Permission: `integration.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Synced folder id. | ```bash curl -X POST "https://api.brixsignage.com/v1/media-sync/{id}/sync" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.imported` | integer | | | `data.updated` | integer | | | `data.removed` | integer | | | `data.skipped` | integer | | | `data.failed` | integer | | | `data.caughtUp` | boolean | False when more changes remain for the next run. | | `data.error` | string \| null | Why the run stopped, in words; null when it did not. | 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 synced folder with this id. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Org nodes 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/org-nodes List locations Returns the workspace's location tree, for example districts, regions, sites, and departments, with each location's path and member count. Every location in the workspace tree the caller may see (not paginated). Build the tree from `parentId`. Auth: Bearer token. Permission: `org-unit.view`. ```bash curl "https://api.brixsignage.com/v1/org-nodes" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Location | | | `data[].id` | string | Location (org node) id. | | `data[].name` | string | | | `data[].parentId` | string \| null | Parent location; null for the workspace root. | | `data[].externalId` | string \| null | Your own location code (store number, region code). Unique in the workspace. | | `data[].timezone` | string \| null | IANA zone screens here inherit, e.g. `America/Chicago`. | | `data[].tier` | integer | Depth: 1 = the workspace root. | | `data[].isSpace` | boolean | True for a workspace (Space) boundary: the root, or a franchise child workspace. | | `data[].payment` | "awaiting" \| "live" \| null | A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays. | | `data[].paymentTrial` | "card_added" \| "no_card" \| null | While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial. | | `data[].screenCount` | integer | Screens placed directly at this location (not its children). | | `data[].members` | array of object | People granted a role at this location. | | `data[].members[].userId` | string | | | `data[].members[].userName` | string | | | `data[].members[].roleId` | string | | | `data[].members[].roleName` | string | | | `data[].members[].roleColor` | string \| null | | | `data[].members[].source` | string \| null | `sso:` when an identity provider granted this; null when granted in Brix. | | `data[].featureOverrides` | any | Owner-set feature overrides, as stored (normally an array). | | `data[].approval` | ApprovalPolicy | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `data[].approval.required` | boolean | | | `data[].approval.inheritFromParent` | boolean | | | `data[].approval.escalateUpTiers` | boolean | | | `data[].approval.allowSharedExemptions` | boolean | | | `data[].approval.approvers` | array of string | User ids named as approvers. | | `data[].billing` | any | Owner-set billing metadata as stored, or null. | | `data[].prefs` | LocationPrefs | Inheritable per-location settings (nearest ancestor wins). | | `data[].prefs.location` | object \| null | Physical place screens here inherit (drives weather and other location-aware apps). | | `data[].prefs.language` | string \| null | BCP 47 tag screens here inherit, e.g. `de-DE`. | | `data[].prefs.defaultContent` | object \| null | What screens here play when they have no content of their own. | ```json { "data": [ { "id": "on_4d5e6f7a8b9c0d1e", "name": "Chicago Loop", "parentId": "space_1a2b3c4d5e6f7a8b", "externalId": "STORE-0142", "timezone": "America/Chicago", "tier": 2, "isSpace": false, "payment": null, "paymentTrial": null, "screenCount": 6, "members": [ { "userId": "usr_5e6f7a8b9c0d1e2f", "userName": "Sam Rivera", "roleId": "role_0a1b2c3d4e5f6a7b", "roleName": "Store manager", "roleColor": null, "source": null } ], "featureOverrides": [], "approval": { "required": false, "inheritFromParent": true, "escalateUpTiers": false, "allowSharedExemptions": false, "approvers": [] }, "billing": null, "prefs": { "location": { "label": "Chicago Loop", "lat": 41.8837, "lng": -87.6289 }, "language": null, "defaultContent": null } } ] } ``` 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/org-nodes Create a location Creates a new location under a parent location. Provide `name`, `parentId`, and an optional `kind`. To create many locations at once, use the bulk-create operation instead. Auth: Bearer token. Permission: `org-unit.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Location name. | | `parentId` | string | no | Parent location; omit to place it directly under the workspace root. | | `externalId` | string | no | Your own location code; must be unique in the workspace. | | `timezone` | string | no | IANA zone, e.g. `Europe/London`. | | `approval` | ApprovalPolicy | no | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `approval.required` | boolean | no | | | `approval.inheritFromParent` | boolean | no | | | `approval.escalateUpTiers` | boolean | no | | | `approval.allowSharedExemptions` | boolean | no | | | `approval.approvers` | array of string | no | User ids named as approvers. | | `isSpace` | boolean | no | Owner-only: create a child workspace (franchise). | | `billingOwnerNodeId` | string | no | With `isSpace`: the ancestor workspace that pays. | | `screenLimit` | integer | no | Owner-only, advisory. | | `tier` | integer | no | Owner-only. Defaults to 2. | | `billing` | any | no | Owner-only. | | `featureOverrides` | any | no | Owner-only. | | `paysForItself` | boolean | no | The location pays for its own screens and stays on the hold card until it adds a card. Defaults to the account setting `newLocationsPayFirst`. Choosing against that default needs `billing.edit` at the workspace root. Brix billing only (409 otherwise). | ```bash curl -X POST "https://api.brixsignage.com/v1/org-nodes" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Chicago Loop","parentId":"on_0a1b2c3d4e5f6a7b","externalId":"STORE-0142","timezone":"America/Chicago"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Location | A location in the workspace tree (an org node). | | `data.id` | string | Location (org node) id. | | `data.name` | string | | | `data.parentId` | string \| null | Parent location; null for the workspace root. | | `data.externalId` | string \| null | Your own location code (store number, region code). Unique in the workspace. | | `data.timezone` | string \| null | IANA zone screens here inherit, e.g. `America/Chicago`. | | `data.tier` | integer | Depth: 1 = the workspace root. | | `data.isSpace` | boolean | True for a workspace (Space) boundary: the root, or a franchise child workspace. | | `data.payment` | "awaiting" \| "live" \| null | A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays. | | `data.paymentTrial` | "card_added" \| "no_card" \| null | While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial. | | `data.screenCount` | integer | Screens placed directly at this location (not its children). | | `data.members` | array of object | People granted a role at this location. | | `data.members[].userId` | string | | | `data.members[].userName` | string | | | `data.members[].roleId` | string | | | `data.members[].roleName` | string | | | `data.members[].roleColor` | string \| null | | | `data.members[].source` | string \| null | `sso:` when an identity provider granted this; null when granted in Brix. | | `data.featureOverrides` | any | Owner-set feature overrides, as stored (normally an array). | | `data.approval` | ApprovalPolicy | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `data.approval.required` | boolean | | | `data.approval.inheritFromParent` | boolean | | | `data.approval.escalateUpTiers` | boolean | | | `data.approval.allowSharedExemptions` | boolean | | | `data.approval.approvers` | array of string | User ids named as approvers. | | `data.billing` | any | Owner-set billing metadata as stored, or null. | | `data.prefs` | LocationPrefs | Inheritable per-location settings (nearest ancestor wins). | | `data.prefs.location` | object \| null | Physical place screens here inherit (drives weather and other location-aware apps). | | `data.prefs.language` | string \| null | BCP 47 tag screens here inherit, e.g. `de-DE`. | | `data.prefs.defaultContent` | object \| null | What screens here play when they have no content of their own. | Response 401: Missing, expired or revoked bearer token. Response 403: An owner-only field was set (`isSpace`, `billing`, `featureOverrides`, `tier`, `screenLimit`, or a non-inheriting approval policy). Response 409: `location_id_taken`: another location already uses this `externalId`. Response 422: `name` missing, invalid `externalId`, or `parentId` not found. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/org-nodes/{id} Get a location Returns one location, including its path, parent, and settings. Auth: Bearer token. Permission: `org-unit.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | ```bash curl "https://api.brixsignage.com/v1/org-nodes/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Location | A location in the workspace tree (an org node). | | `data.id` | string | Location (org node) id. | | `data.name` | string | | | `data.parentId` | string \| null | Parent location; null for the workspace root. | | `data.externalId` | string \| null | Your own location code (store number, region code). Unique in the workspace. | | `data.timezone` | string \| null | IANA zone screens here inherit, e.g. `America/Chicago`. | | `data.tier` | integer | Depth: 1 = the workspace root. | | `data.isSpace` | boolean | True for a workspace (Space) boundary: the root, or a franchise child workspace. | | `data.payment` | "awaiting" \| "live" \| null | A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays. | | `data.paymentTrial` | "card_added" \| "no_card" \| null | While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial. | | `data.screenCount` | integer | Screens placed directly at this location (not its children). | | `data.members` | array of object | People granted a role at this location. | | `data.members[].userId` | string | | | `data.members[].userName` | string | | | `data.members[].roleId` | string | | | `data.members[].roleName` | string | | | `data.members[].roleColor` | string \| null | | | `data.members[].source` | string \| null | `sso:` when an identity provider granted this; null when granted in Brix. | | `data.featureOverrides` | any | Owner-set feature overrides, as stored (normally an array). | | `data.approval` | ApprovalPolicy | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `data.approval.required` | boolean | | | `data.approval.inheritFromParent` | boolean | | | `data.approval.escalateUpTiers` | boolean | | | `data.approval.allowSharedExemptions` | boolean | | | `data.approval.approvers` | array of string | User ids named as approvers. | | `data.billing` | any | Owner-set billing metadata as stored, or null. | | `data.prefs` | LocationPrefs | Inheritable per-location settings (nearest ancestor wins). | | `data.prefs.location` | object \| null | Physical place screens here inherit (drives weather and other location-aware apps). | | `data.prefs.language` | string \| null | BCP 47 tag screens here inherit, e.g. `de-DE`. | | `data.prefs.defaultContent` | object \| null | What screens here play when they have no content of their own. | 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 location in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/org-nodes/{id} Update a location Updates a location's name, parent location, approval configuration, or preferences. Moving a location to a new parent updates the path of every location beneath it. Rename, re-code, move, or change inheritable settings. Only the fields sent change. Auth: Bearer token. Permission: `org-unit.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `paysForItself` | boolean | no | On: the location pays for its own screens and waits on the hold card until it adds a card. Off: the account pays for them and the location's payer is closed. Needs `billing.edit` at the workspace root. | | `name` | string | no | | | `parentId` | string \| null | no | Move under another location (null = the workspace root). | | `externalId` | string \| null | no | | | `timezone` | string \| null | no | IANA zone, or null/empty to inherit. | | `tier` | integer | no | | | `prefs` | object | no | Per-key: a value sets it, null clears it back to inherit, absent keeps it. | | `prefs.location` | object \| null | no | | | `prefs.language` | string \| null | no | BCP 47 tag, or null to inherit. | | `prefs.defaultContent` | object \| null | no | | | `approval` | ApprovalPolicy | no | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `approval.required` | boolean | no | | | `approval.inheritFromParent` | boolean | no | | | `approval.escalateUpTiers` | boolean | no | | | `approval.allowSharedExemptions` | boolean | no | | | `approval.approvers` | array of string | no | User ids named as approvers. | | `approvalBase` | ApprovalPolicy | no | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `approvalBase.required` | boolean | no | | | `approvalBase.inheritFromParent` | boolean | no | | | `approvalBase.escalateUpTiers` | boolean | no | | | `approvalBase.allowSharedExemptions` | boolean | no | | | `approvalBase.approvers` | array of string | no | User ids named as approvers. | | `billing` | any | no | Owner-only. | | `featureOverrides` | any | no | Owner-only. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/org-nodes/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Location | A location in the workspace tree (an org node). | | `data.id` | string | Location (org node) id. | | `data.name` | string | | | `data.parentId` | string \| null | Parent location; null for the workspace root. | | `data.externalId` | string \| null | Your own location code (store number, region code). Unique in the workspace. | | `data.timezone` | string \| null | IANA zone screens here inherit, e.g. `America/Chicago`. | | `data.tier` | integer | Depth: 1 = the workspace root. | | `data.isSpace` | boolean | True for a workspace (Space) boundary: the root, or a franchise child workspace. | | `data.payment` | "awaiting" \| "live" \| null | A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays. | | `data.paymentTrial` | "card_added" \| "no_card" \| null | While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial. | | `data.screenCount` | integer | Screens placed directly at this location (not its children). | | `data.members` | array of object | People granted a role at this location. | | `data.members[].userId` | string | | | `data.members[].userName` | string | | | `data.members[].roleId` | string | | | `data.members[].roleName` | string | | | `data.members[].roleColor` | string \| null | | | `data.members[].source` | string \| null | `sso:` when an identity provider granted this; null when granted in Brix. | | `data.featureOverrides` | any | Owner-set feature overrides, as stored (normally an array). | | `data.approval` | ApprovalPolicy | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `data.approval.required` | boolean | | | `data.approval.inheritFromParent` | boolean | | | `data.approval.escalateUpTiers` | boolean | | | `data.approval.allowSharedExemptions` | boolean | | | `data.approval.approvers` | array of string | User ids named as approvers. | | `data.billing` | any | Owner-set billing metadata as stored, or null. | | `data.prefs` | LocationPrefs | Inheritable per-location settings (nearest ancestor wins). | | `data.prefs.location` | object \| null | Physical place screens here inherit (drives weather and other location-aware apps). | | `data.prefs.language` | string \| null | BCP 47 tag screens here inherit, e.g. `de-DE`. | | `data.prefs.defaultContent` | object \| null | What screens here play when they have no content of their own. | Response 401: Missing, expired or revoked bearer token. Response 403: Owner-only field, or a move you lack permission for at the destination. Response 404: No such location in this workspace. Response 409: `externalId` already used, or `approvalBase` no longer matches. Response 422: Invalid field (a malformed `prefs`, moving a location under itself, unplayable default content). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/org-nodes/{id} Delete location Soft-deletes a location. Everything at that location, including screens, content, folders and the people assigned there, moves to its parent location first, so nothing is left orphaned. Each person keeps their role, now at the parent location; if they already have that access there, the duplicate is dropped. Because a role at the parent applies to everything under it, you can only delete a location when you could give each of those roles at the parent yourself, and only an account owner can move an owner. People never move into another workspace: deleting a franchise workspace's top location removes the role assignments there. The root location and any location with active child locations cannot be deleted, and a deleted location cannot be restored. **Notes.** - Screens, content and people move to the parent location. Each person keeps their role, now at the parent, so it applies to everything under the parent. If they already have that access at the parent or above, the moved role assignment is dropped; otherwise they keep both. - Because the move widens where a role applies, you need to be able to give each moved role at the parent yourself. That includes your own role. - People never move into another workspace. Deleting a franchise workspace's top location removes the role assignments there. - A deleted location cannot be restored. The activity log records where each person was moved from. Auth: Bearer token. Permission: `org-unit.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/org-nodes/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.transferredTo` | string | The parent location that received this location's screens, content and people. | | `data.membersMoved` | integer | Role assignments moved up to the parent, including ones merged into an assignment the person already had there. 0 when the location is a franchise workspace's own top location. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `org-unit.delete` there; `owner_required`: an owner placed here would move up and you are not an owner at the parent (an API key never is); or `outranked`: a person placed here holds a permission you do not hold at the parent. Response 404: No such location in this workspace. Response 409: `protected` (the workspace root), `has_children` (move or delete the child locations first), or `last_owner` (deleting a franchise workspace's top location would remove the last owner). Response 502: A franchise workspace's own subscription could not be ended; nothing was deleted. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/org-nodes/{id}/members List location members Returns the people directly assigned a role at this specific location, including the id of each role assignment. This id is needed to remove a membership, and is not included in the general roster listing. **Notes.** - Only the roles granted at this location, not those inherited from a parent. Auth: Bearer token. Permission: `user.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | ```bash curl "https://api.brixsignage.com/v1/org-nodes/{id}/members" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | Membership id. | | `data[].userId` | string | | | `data[].userName` | string \| null | | | `data[].roleId` | string | | | `data[].roleName` | string \| null | | | `data[].roleColor` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `user.view` at this location. Response 404: No such location in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/org-nodes/{id}/members Assign role at location Grants a person a role at this location. Provide `userId` and `roleId`. You cannot grant a role carrying permissions you do not hold yourself at that location. **Notes.** - The 201 body is the membership row as written. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `userId` | string | yes | | | `roleId` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/members" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Membership id. | | `data.spaceId` | string | | | `data.nodeId` | string | | | `data.userId` | string | | | `data.roleId` | string | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: The role holds permissions you do not hold, or you cannot grant them at this location. Response 404: No such location, person or role in this workspace. Response 422: `userId` or `roleId` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/org-nodes/{id}/members/{memberId} Change role assignment Changes the role of one person's role assignment at this location. Provide `roleId`. The location stays the same. You must be allowed to remove the old role and to grant the new one at this location: only an account owner can change an owner, and you cannot give or take away a permission you do not hold here. Refuses the request if it would leave the workspace without any account owner. **Notes.** - The location of the assignment does not change. To give access at another location, add a role assignment there. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | | `memberId` | path | string | yes | Membership id (from the member list or the people roster). | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `roleId` | string | yes | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/org-nodes/{id}/members/{memberId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Membership id. | | `data.spaceId` | string | | | `data.nodeId` | string | | | `data.userId` | string | | | `data.source` | string \| null | How the person got this role: for example set by hand, or from a sign-in provider's group. | | `data.roleId` | string | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `user.edit` here, the person outranks you (`owner_required`, `outranked`), or the new role holds permissions you cannot grant at this location. Response 404: No such location, membership or role. Response 409: `last_owner`: this is the last owner of the workspace. `duplicate`: the person already has this role here. Response 422: `roleId` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/org-nodes/{id}/members/{memberId} Remove role assignment Removes one person's role assignment at this location. Only an account owner can remove the assignment of a person who is an owner at this location, and you cannot remove an assignment that carries a permission you do not hold here. An API key is never an owner. Refuses the request if it would leave the workspace without any account owner. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Location (org node) id. | | `memberId` | path | string | yes | Membership id (from the member list). | ```bash curl -X DELETE "https://api.brixsignage.com/v1/org-nodes/{id}/members/{memberId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.removed` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `user.edit` here, or the person outranks you (`owner_required`, `outranked`). Response 404: No such location or membership. Response 409: `last_owner`: this is the last owner of the workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/org-nodes/{id}/payment/checkout Open the card page for a location awaiting payment Get the link to the card page for a location that pays for its own screens and has not paid yet. Requires `billing.edit` at that location, so the location’s owner can pay without access to the rest of the account; invoices go to the caller’s email. Returns 409 `already_live` when the location is already live. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/payment/checkout" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/org-nodes/{id}/payment/send Email a location its card page Email a location that is awaiting payment the link to its card page. Optionally send `{ email }` to set where the link and future invoices go. Requires `billing.edit` on the whole account; an API key also needs the `location-payment.edit` scope. Returns the link and who it was sent to, or 409 `already_live` when the location is already live. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Identifier for id. | ```bash curl -X POST "https://api.brixsignage.com/v1/org-nodes/{id}/payment/send" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/org-nodes/bulk Bulk-create locations Creates up to 200 locations in a single call, for example to paste in a full location list at fleet setup. Send `parentId` and either a list of `names` or a list of `units`, each with a name and an optional time zone, town, Location ID and parent Location ID, so one list can hold regions and the stores under them. Empty or repeated names, and Location IDs already in use, are skipped, so the same list can safely be submitted again. Requires the create-location permission at the parent location. **Notes.** - Idempotent: sending the same list again creates nothing new and lists every row in `skipped`. Auth: Bearer token. Permission: `org-unit.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `parentId` | string | yes | The location the new ones go under (unless a row names its own parent). | | `names` | array of string | no | Location names. Use this or `units`. | | `paysForItself` | boolean | no | Every new location pays for itself before it goes live. Defaults to the account setting `newLocationsPayFirst`; choosing against it needs `billing.edit` at the workspace root. | | `units` | array of object | no | One row per location (up to 200). Use this or `names`. | | `units[].name` | string | yes | | | `units[].timezone` | string \| null | no | IANA zone. | | `units[].location` | object \| null | no | A town or city (with coordinates, or looked up from `label`). | | `units[].externalId` | string | no | Your own location code. | | `units[].parentExternalId` | string | no | The location code of this row's parent: an earlier row, or an existing location. | ```bash curl -X POST "https://api.brixsignage.com/v1/org-nodes/bulk" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"parentId":"on_0a1b2c3d4e5f6a7b","units":[{"name":"Chicago Loop","timezone":"America/Chicago","externalId":"STORE-0142"}]}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.created` | array of Location | | | `data.created[].id` | string | Location (org node) id. | | `data.created[].name` | string | | | `data.created[].parentId` | string \| null | Parent location; null for the workspace root. | | `data.created[].externalId` | string \| null | Your own location code (store number, region code). Unique in the workspace. | | `data.created[].timezone` | string \| null | IANA zone screens here inherit, e.g. `America/Chicago`. | | `data.created[].tier` | integer | Depth: 1 = the workspace root. | | `data.created[].isSpace` | boolean | True for a workspace (Space) boundary: the root, or a franchise child workspace. | | `data.created[].payment` | "awaiting" \| "live" \| null | A location that pays for itself: `awaiting` (its screens wait on the hold card for its card), `live` (its own payer pays). Null when the account pays. | | `data.created[].paymentTrial` | "card_added" \| "no_card" \| null | While the account is in its free trial the location plays like any trial location: `card_added` (its year starts when the trial ends) or `no_card` (it waits on the hold card from then). Null outside the trial. | | `data.created[].screenCount` | integer | Screens placed directly at this location (not its children). | | `data.created[].members` | array of object | People granted a role at this location. | | `data.created[].members[].userId` | string | | | `data.created[].members[].userName` | string | | | `data.created[].members[].roleId` | string | | | `data.created[].members[].roleName` | string | | | `data.created[].members[].roleColor` | string \| null | | | `data.created[].members[].source` | string \| null | `sso:` when an identity provider granted this; null when granted in Brix. | | `data.created[].featureOverrides` | any | Owner-set feature overrides, as stored (normally an array). | | `data.created[].approval` | ApprovalPolicy | The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`. | | `data.created[].approval.required` | boolean | | | `data.created[].approval.inheritFromParent` | boolean | | | `data.created[].approval.escalateUpTiers` | boolean | | | `data.created[].approval.allowSharedExemptions` | boolean | | | `data.created[].approval.approvers` | array of string | User ids named as approvers. | | `data.created[].billing` | any | Owner-set billing metadata as stored, or null. | | `data.created[].prefs` | LocationPrefs | Inheritable per-location settings (nearest ancestor wins). | | `data.created[].prefs.location` | object \| null | Physical place screens here inherit (drives weather and other location-aware apps). | | `data.created[].prefs.language` | string \| null | BCP 47 tag screens here inherit, e.g. `de-DE`. | | `data.created[].prefs.defaultContent` | object \| null | What screens here play when they have no content of their own. | | `data.skipped` | array of string | Names skipped: empty, repeated, or already a location there (or a Location ID already in use). | | `data.locationsSkipped` | array of string | Names created without a town or city, because the one given could not be found. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `org-unit.create` at the parent location. Response 422: `parentId` missing or not found, no rows, more than 200 rows, an invalid Location ID or time zone, or a parent that is a separate workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Playlists (part 1 of 2) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/playlists List playlists List every playlist in the workspace, including its items and a summary of its dayparting rules. Every playlist you can see, each with its items. Not paginated. Auth: Bearer token. Permission: `playlist.view`. ```bash curl "https://api.brixsignage.com/v1/playlists" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Playlist | | | `data[].id` | string | Playlist id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].description` | string | | | `data[].shuffle` | boolean | | | `data[].fullscreen` | boolean | | | `data[].transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data[].transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data[].startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data[].expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data[].approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | | | `data[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data[].approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data[].importSourceId` | string \| null | | | `data[].copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data[].folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data[].recalledAt` | string \| null | | | `data[].recalledBy` | string \| null | | | `data[].usedByScreenCount` | integer | | | `data[].usedByScreens` | array of object | Up to 12 screens playing it. | | `data[].usedByScreens[].id` | string | | | `data[].usedByScreens[].name` | string | | | `data[].allocations` | array of PlaylistAllocation | | | `data[].allocations[].id` | string | | | `data[].allocations[].label` | string | | | `data[].allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data[].allocations[].ownerId` | string | | | `data[].allocations[].ownerName` | string | | | `data[].allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data[].allocations[].value` | integer | | | `data[].allocations[].endValue` | integer | Absent (not null) when unset. | | `data[].allocations[].colorClass` | string | | | `data[].allocations[].fillSpaceId` | string \| null | | | `data[].allocations[].fillPlaylistId` | string \| null | | | `data[].allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data[].allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data[].allocations[].fillerRefId` | string \| null | | | `data[].allocations[].requiresApproval` | boolean | | | `data[].items` | array of PlaylistItem | | | `data[].items[].id` | string | Playlist item id. | | `data[].items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data[].items[].refId` | string | The media / app instance / layout / playlist id. | | `data[].items[].name` | string | | | `data[].items[].thumbnailUrl` | string | Empty string when there is none. | | `data[].items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data[].items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data[].items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data[].items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data[].items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data[].items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data[].items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data[].items[].loopCount` | integer | | | `data[].items[].loopDurationMs` | integer \| null | | | `data[].items[].mediaDurationSec` | number \| null | | | `data[].items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data[].items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data[].items[].assetStartsAt` | string \| null | | | `data[].items[].assetExpiresAt` | string \| null | | | `data[].items[].assetActive` | boolean \| null | | | `data[].items[].fullscreen` | boolean | | | `data[].items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data[].items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data[].items[].allocationId` | string \| null | | | `data[].items[].position` | integer | | | `data[].sharedIn` | true | Present when the playlist is outside your locations and was shared in. | 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/playlists Create a playlist with a `name` and an optional `nodeId` and other fields. Safe to retry with an idempotency key, to protect against duplicate creation from a double-click. Creates an empty playlist. Add items with POST /v1/playlists/{id}/items. Send an `Idempotency-Key` header to make a retry safe. **Notes.** - The create response is the new row plus empty `items` and `allocations`; it omits `fit`, `usedByScreenCount`, `usedByScreens` and the other columns that GET returns. Auth: Bearer token. Permission: `playlist.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `description` | string | no | | | `shuffle` | boolean | no | | | `fullscreen` | boolean | no | | | `transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" | no | Change between items. Any kind but `none` needs playlist transitions in the workspace (else 403 feature_disabled). | | `transitionMs` | integer | no | How long the transition runs, in ms (200–1500). Ignored without a transition. | | `startsAt` | string | no | YYYY-MM-DD or ISO-8601. | | `expiresAt` | string | no | YYYY-MM-DD or ISO-8601. | | `nodeId` | string | no | Home location; defaults to your own. | ```bash curl -X POST "https://api.brixsignage.com/v1/playlists" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Lunch menu","description":"Weekday 11:00-14:00","shuffle":false}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | PlaylistCreated | A new, empty playlist. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | ```json { "data": { "id": "pl_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Lunch menu", "description": "Weekday 11:00-14:00", "shuffle": false, "fullscreen": false, "startsAt": null, "expiresAt": null, "approvalState": "approved", "nodeId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "items": [], "allocations": [] } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: Missing name, an unparsable date, or an unknown location. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/playlists/{id} Get a playlist Retrieve one playlist with its ordered items, including each item's reference kind and id, duration, and rules. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | ```bash curl "https://api.brixsignage.com/v1/playlists/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | PlaylistDetail | | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | | `data.requiresApproval` | boolean | Approval is required before content airs: the home location requires it, or this playlist fills a share whose owner checks it. | | `data.fillsShare` | object \| null | When this playlist fills a location's share of another playlist: that share. Its items take turns inside it. | | `data.approvalFor` | object \| null | When this playlist fills a share that needs approval: the owner's playlist. Its owner decides. | | `data.resolvedItemCount` | integer | Item count with nested playlists expanded. | | `data.resolvedDurationSec` | number | Runtime in seconds with nested playlists expanded. | 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 playlist in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/playlists/{id} Update a playlist Edit a playlist's own fields, such as name, node, shuffle, and transition settings. Items are managed through the separate /items routes. Send only the fields to change. A playback change to an approved playlist returns it to `draft` where approval is required. **Notes.** - Fields of the wrong type are ignored rather than refused (for example `name: 5`). Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `description` | string | no | | | `shuffle` | boolean | no | | | `fullscreen` | boolean | no | | | `fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | no | | | `transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | no | Change between items: `fade`, `slide-left`, `slide-right`, `slide-up`, `slide-down` or `zoom`; `none` or null cuts (and clears the speed). Choosing one needs playlist transitions in the workspace (else 403 feature_disabled). | | `transitionMs` | integer \| null | no | How long the transition runs, in ms (200–1500); null = the default 450. Needs a transition (else 422). | | `startsAt` | string \| null | no | | | `expiresAt` | string \| null | no | | | `nodeId` | string \| null | no | Move to another location (needs playlist.edit there). | | `baseUpdatedAt` | string | no | The `updatedAt` your edit is based on; a stale value answers 409 with `current`. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/playlists/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | Response 401: Missing, expired or revoked bearer token. Response 403: Moving it to a location where you lack playlist.edit. Response 404: No such playlist in this workspace. Response 409: `conflict`: `baseUpdatedAt` is stale; the body carries `current`. Response 422: An unparsable date or an unknown location. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/playlists/{id} Delete a playlist to the recycle bin. Screens assigned to it fall back to their default content. Fails with 409 if the playlist is shared into other spaces, unless the deletion is forced. Moves the playlist to the recycle bin (restorable for 30 days). Auth: Bearer token. Permission: `playlist.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | | `force` | query | "true" | no | Delete even when it is shared into other places. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/playlists/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | | 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 playlist in this workspace. Response 409: `content_shared`: the item is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/playlists/{id}/allocations Set playlist allocations Set a playlist's allocations: shares of its airtime given to a person, a group or a location (a percent, every nth play, or a time of day). This replaces the whole set; allocations you leave out are removed. **Notes.** - An out-of-range `value` is 400 `validation_error`; every other validation failure is 422. - Rows with an unknown `ownerKind` or `kind` are dropped without an error. - A missing or malformed body is treated as an empty list, which removes every allocation. - The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `allocations` | array of object | yes | The whole set, at most 200. Allocations left out are removed. | | `allocations[].id` | string | no | Keep this id: one of the playlist's current allocations, or a new id of 6-64 URL-safe characters. Otherwise a new id is made. | | `allocations[].label` | string | no | | | `allocations[].ownerKind` | "user" \| "group" \| "org-unit" | yes | Who gets the share. `org-unit` = a location (`ownerId` is its node id). | | `allocations[].ownerId` | string | yes | | | `allocations[].ownerName` | string | no | | | `allocations[].kind` | "percent" \| "every-nth" \| "daypart" | yes | | | `allocations[].value` | integer | yes | `percent` 0-100, `every-nth` 1-100, `daypart` 0-1439 (the minute of the day it opens). | | `allocations[].endValue` | number | no | `daypart`: the minute of the day it closes. | | `allocations[].colorClass` | string | no | | | `allocations[].fillSpaceId` | string \| null | no | A child workspace that fills the share; null = this workspace. | | `allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | no | What plays while the share is not filled. Default `collapse`. | | `allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | no | With `filler`: the kind of the filler content. | | `allocations[].fillerRefId` | string | no | | | `allocations[].requiresApproval` | boolean | no | What the recipient puts in the share must be approved first. | ```bash curl -X PUT "https://api.brixsignage.com/v1/playlists/{id}/allocations" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | Response 400: `validation_error`: a `value` outside its kind's range or not a whole number. 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 playlist in this workspace. Response 422: More than 200 allocations, a location that is not in this workspace (`invalid_node`), or percent shares that would give away more than 99% on some screen. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Playlists (part 2 of 2) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### POST /v1/playlists/{id}/duplicate Duplicate a playlist Create a deep copy of a playlist, including its settings, share-of-voice allocations (fill assignments reset), and ordered items, named " copy" and unique within the space. The copy starts as a draft with no assignment. Requires permission to create playlists at the source playlist's home node. Auth: Bearer token. Permission: `playlist.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | ```bash curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/duplicate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | 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 playlist in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/playlists/{id}/items Add an item to a playlist Append one item to a playlist with `refKind`, `refId`, and an optional `durationSec` and other fields. Rejects references from another space, and rejects any nesting that would create a loop, such as a playlist referencing a layout zone that contains the same playlist, with a clear error rather than failing silently. Appends one item. A video or audio file defaults to playing its full length, an animated image to one loop, anything else to 10 seconds. Returns the whole playlist. **Notes.** - `position` is accepted and ignored. - The returned `approvalState` is the value from before the edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | yes | | | `refId` | string | yes | | | `durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | no | | | `durationSeconds` | integer | no | | | `loopCount` | number | no | | | `fit` | string | no | contain, cover, fill or blur-fill; anything else means inherit. | | `fullscreen` | boolean | no | | | `playOnlyWhenTapped` | boolean | no | Skip it in the rotation; show it only from a `show-design` tap. Default false. | | `position` | number | no | Accepted but ignored: the item is always appended. Reorder with PUT /v1/playlists/{id}/items. | | `allocationId` | string | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/items" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not available at the playlist's location. Response 404: No such playlist, or the referenced content is not in this workspace. Response 422: Invalid body, a playlist loop, a layout with unbound zones, or an unknown allocation. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/playlists/{id}/items Reorder a playlist's items Replace a playlist's entire item list in one call. Send the full array of items in the order you want; the same reference and loop validation applies as when adding a single item. Sets the order of the items: `itemIds[0]` plays first. Unknown ids are skipped. It does not add or remove items. Returns the whole playlist. **Notes.** - Items left out of `itemIds` keep their old position number, so two items can share a position. Send every item id. - A missing or malformed body is treated as an empty list, not refused. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `itemIds` | array of string | yes | Item ids in the new order. | ```bash curl -X PUT "https://api.brixsignage.com/v1/playlists/{id}/items" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"itemIds":["pli_7a8b9c0d1e2f3a4b","pli_1e2f3a4b5c6d7e8f"]}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | 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 playlist in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/playlists/{id}/items/{itemId} Update a playlist item Edit one playlist item's duration, loop count, fit, full-screen setting, screen tag rules or allocation. `refKind` and `refId` cannot be changed on an existing item; delete it and add a new item to point at different content. **Notes.** - An unknown `itemId` is not refused: nothing changes and the answer is 200 with the playlist. - `targetTags` and `excludeTags` are stored but not returned on the items. - Fields of the wrong type are ignored rather than refused. - The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | | `itemId` | path | string | yes | Playlist item id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | no | | | `durationSeconds` | number | no | Dwell for `fixed`, rounded and clamped to 1 second through 24 hours. | | `loopCount` | number | no | Plays per turn for `loop`; rounded. | | `fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | no | The item's own fit; `null` = follow the file's fit. | | `fullscreen` | boolean | no | Take over the whole screen, over any layout. | | `playOnlyWhenTapped` | boolean | no | Skip it in the rotation; show it only from a `show-design` tap. | | `targetTags` | array of string \| null | no | Play only on screens with one of these tags. `null` or `[]` clears the rule. | | `excludeTags` | array of string \| null | no | Never play on screens with one of these tags. `null` or `[]` clears the rule. | | `allocationId` | string \| null | no | Put the item in one of this playlist's allocations; `null` = the base rotation. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/playlists/{id}/items/{itemId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | 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 playlist in this workspace. Response 422: `allocationId` is not one of this playlist's allocations, or nothing to update. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/playlists/{id}/items/{itemId} Remove a playlist item Remove one item from a playlist. The remaining items keep their existing order. Removes the item and closes the gap in the positions. Returns the whole playlist. **Notes.** - An unknown `itemId` is not refused: nothing is removed and the answer is 200 with the playlist. - The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | | `itemId` | path | string | yes | Playlist item id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/playlists/{id}/items/{itemId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Playlist | A playlist with its ordered items. | | `data.id` | string | Playlist id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string | | | `data.shuffle` | boolean | | | `data.fullscreen` | boolean | | | `data.transition` | "none" \| "fade" \| "slide-left" \| "slide-right" \| "slide-up" \| "slide-down" \| "zoom" \| null | Change between items: `fade` crossfades, `slide-*` pushes the next item in from that side, `zoom` fades it in from slightly larger; null cuts (the default). | | `data.transitionMs` | integer \| null | How long the transition runs, in ms; null = the default 450. | | `data.startsAt` | string \| null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. | | `data.expiresAt` | string \| null | Stops after this date (YYYY-MM-DD) or time, stored as sent. | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Only `approved` content airs where the location requires approval. | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.approvedSnapshot` | string \| null | Internal: the approved version, as stored JSON text. | | `data.importSourceId` | string \| null | | | `data.copySourceId` | string \| null | The partner library item this was copied from (Copy to client workspace), or null. | | `data.folderId` | string \| null | Content folder (GET /v1/content-folders); null = the list's top level. | | `data.recalledAt` | string \| null | | | `data.recalledBy` | string \| null | | | `data.usedByScreenCount` | integer | | | `data.usedByScreens` | array of object | Up to 12 screens playing it. | | `data.usedByScreens[].id` | string | | | `data.usedByScreens[].name` | string | | | `data.allocations` | array of PlaylistAllocation | | | `data.allocations[].id` | string | | | `data.allocations[].label` | string | | | `data.allocations[].ownerKind` | "user" \| "group" \| "org-unit" | | | `data.allocations[].ownerId` | string | | | `data.allocations[].ownerName` | string | | | `data.allocations[].kind` | "percent" \| "every-nth" \| "daypart" | | | `data.allocations[].value` | integer | | | `data.allocations[].endValue` | integer | Absent (not null) when unset. | | `data.allocations[].colorClass` | string | | | `data.allocations[].fillSpaceId` | string \| null | | | `data.allocations[].fillPlaylistId` | string \| null | | | `data.allocations[].unfilledBehavior` | "collapse" \| "filler" \| "holding" | | | `data.allocations[].fillerRefKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" \| null | | | `data.allocations[].fillerRefId` | string \| null | | | `data.allocations[].requiresApproval` | boolean | | | `data.items` | array of PlaylistItem | | | `data.items[].id` | string | Playlist item id. | | `data.items[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "ad-slot" \| "creative" | | | `data.items[].refId` | string | The media / app instance / layout / playlist id. | | `data.items[].name` | string | | | `data.items[].thumbnailUrl` | string | Empty string when there is none. | | `data.items[].kind` | string | The media kind for media items; `app`, `layout` or `playlist` otherwise. | | `data.items[].nestedItemCount` | integer \| null | Nested playlists only: its top-level item count. | | `data.items[].nestedShuffle` | boolean \| null | Nested playlists only: whether that playlist plays its items in shuffled order. | | `data.items[].sharedFrom` | string \| null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. | | `data.items[].repeatLoop` | object \| null | A design that repeats for each row: what it really plays. `durationSeconds` does not apply to it. Null otherwise. | | `data.items[].durationMode` | "fixed" \| "full" \| "live" \| "loop" \| "manual" | | | `data.items[].durationSeconds` | integer | Dwell in seconds for `fixed`. | | `data.items[].loopCount` | integer | | | `data.items[].loopDurationMs` | integer \| null | | | `data.items[].mediaDurationSec` | number \| null | | | `data.items[].fit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | The item's own fit; null = inherit. | | `data.items[].assetFit` | "contain" \| "cover" \| "fill" \| "blur-fill" \| null | | | `data.items[].assetStartsAt` | string \| null | | | `data.items[].assetExpiresAt` | string \| null | | | `data.items[].assetActive` | boolean \| null | | | `data.items[].fullscreen` | boolean | | | `data.items[].playOnlyWhenTapped` | boolean | The rotation skips this item; a design's `show-design` tap action shows it. | | `data.items[].withheld` | "expired" \| "archived" \| "not-yet" \| null | Why a media item is not airing now, or null. | | `data.items[].allocationId` | string \| null | | | `data.items[].position` | integer | | | `data.sharedIn` | true | Present when the playlist is outside your locations and was shared in. | 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 playlist in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/playlists/{id}/restore Restore a deleted playlist so its items and ordering return to the playlist library. Auth: Bearer token. Permission: `playlist.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | ```bash curl -X POST "https://api.brixsignage.com/v1/playlists/{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 playlist in this workspace, or it was purged. Response 409: `not_deleted`: the playlist is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/playlists/{id}/share-readiness Get playlist share readiness For a playlist's airtime reserved for other teams, list who at each location can fill their share, and the narrowest role that would let them do so. **Notes.** - `requiredPermissions` is absent when `locations` is empty. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Playlist id. | ```bash curl "https://api.brixsignage.com/v1/playlists/{id}/share-readiness" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.locations` | array of object | One per location that holds a percent share of this playlist. | | `data.locations[].nodeId` | string | | | `data.locations[].nodeName` | string | | | `data.locations[].canFill` | boolean | Somebody at the location can fill the share now. | | `data.locations[].fillerCount` | integer | | | `data.locations[].candidates` | array of object | People at the location who cannot fill it yet. | | `data.locations[].candidates[].userId` | string | | | `data.locations[].candidates[].name` | string | | | `data.locations[].candidates[].email` | string | | | `data.locations[].roleId` | string \| null | The narrowest existing role that would let them fill it. | | `data.locations[].roleName` | string \| null | | | `data.locations[].mayGrant` | boolean | The caller may give that role at that location. | | `data.locations[].fillApprovalState` | "draft" \| "pending" \| "approved" \| "rejected" \| null | Where the location's own content stands in review; null when nothing is added yet. | | `data.locations[].requiresApproval` | boolean | The owner checks this location's content before it airs. | | `data.requiredPermissions` | array of string | The permissions filling a share needs. Absent when no location holds a share. | 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 playlist in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/playlists/bulk-delete Delete playlists in bulk Move up to 500 playlists to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in `ok` and the rest in `failed`, so one failure does not stop the rest. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/playlists/bulk-delete" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Power policies 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/power-policies List power policies List the power policies configured for your workspace. Each policy defines an open and close window for the screens using it. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/power-policies" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of PowerPolicy | | | `data[].id` | string | Power policy id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].description` | string \| null | | | `data[].windows` | WeeklyWindows | Open window per weekday (`mon` … `sun`). A day that is absent is closed. | | `data[].windows.mon` | OpenWindow | | | `data[].windows.mon.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.mon.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.mon.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.mon.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.mon.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.tue` | OpenWindow | | | `data[].windows.tue.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.tue.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.tue.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.tue.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.tue.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.wed` | OpenWindow | | | `data[].windows.wed.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.wed.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.wed.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.wed.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.wed.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.thu` | OpenWindow | | | `data[].windows.thu.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.thu.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.thu.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.thu.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.thu.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.fri` | OpenWindow | | | `data[].windows.fri.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.fri.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.fri.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.fri.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.fri.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.sat` | OpenWindow | | | `data[].windows.sat.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.sat.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.sat.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.sat.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.sat.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].windows.sun` | OpenWindow | | | `data[].windows.sun.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data[].windows.sun.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data[].windows.sun.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.sun.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data[].windows.sun.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data[].rebootHourLocal` | integer \| null | Hour (0–23, local time) the device restarts each day; null = no scheduled restart. | | `data[].timezone` | string \| null | IANA time zone the windows use; null = each screen's own time zone. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | Always null on these reads. | | `data[].screenCount` | integer | Screens that use this policy. | ```json { "data": [ { "id": "ppol_1a2b3c4d5e6f7a8b", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Store hours", "description": "Open 8 to 22", "windows": { "mon": { "start": "08:00", "end": "22:00" }, "tue": { "start": "08:00", "end": "22:00", "volume": 40 } }, "rebootHourLocal": 4, "timezone": "Europe/London", "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "screenCount": 12 } ] } ``` 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/power-policies Create a power policy Create a named power policy that defines when screens using it should power on and off. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `screen.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default on create: `Untitled policy`. | | `description` | string \| null | no | | | `windows` | object | no | Open window per weekday. `null` or an absent day is closed. A malformed day is dropped (closed), not refused. | | `windows.mon` | OpenWindow \| null | no | | | `windows.tue` | OpenWindow \| null | no | | | `windows.wed` | OpenWindow \| null | no | | | `windows.thu` | OpenWindow \| null | no | | | `windows.fri` | OpenWindow \| null | no | | | `windows.sat` | OpenWindow \| null | no | | | `windows.sun` | OpenWindow \| null | no | | | `rebootHourLocal` | number \| null | no | 0–23; rounded and clamped. Null (or a value that is not a number) turns the restart off. | | `timezone` | string \| null | no | IANA time zone (`Europe/London`). An unknown zone is refused with 422. | ```bash curl -X POST "https://api.brixsignage.com/v1/power-policies" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | PowerPolicy | | | `data.id` | string | Power policy id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string \| null | | | `data.windows` | WeeklyWindows | Open window per weekday (`mon` … `sun`). A day that is absent is closed. | | `data.windows.mon` | OpenWindow | | | `data.windows.mon.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.mon.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.mon.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.tue` | OpenWindow | | | `data.windows.tue.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.tue.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.tue.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.wed` | OpenWindow | | | `data.windows.wed.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.wed.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.wed.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.thu` | OpenWindow | | | `data.windows.thu.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.thu.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.thu.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.fri` | OpenWindow | | | `data.windows.fri.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.fri.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.fri.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sat` | OpenWindow | | | `data.windows.sat.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sat.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sat.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sun` | OpenWindow | | | `data.windows.sun.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sun.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sun.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.rebootHourLocal` | integer \| null | Hour (0–23, local time) the device restarts each day; null = no scheduled restart. | | `data.timezone` | string \| null | IANA time zone the windows use; null = each screen's own time zone. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads. | | `data.screenCount` | integer | Screens that use this policy. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: Unknown `timezone`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/power-policies/{id} Get a power policy Get one power policy by its ID. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Power policy id. | ```bash curl "https://api.brixsignage.com/v1/power-policies/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | PowerPolicy | | | `data.id` | string | Power policy id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string \| null | | | `data.windows` | WeeklyWindows | Open window per weekday (`mon` … `sun`). A day that is absent is closed. | | `data.windows.mon` | OpenWindow | | | `data.windows.mon.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.mon.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.mon.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.tue` | OpenWindow | | | `data.windows.tue.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.tue.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.tue.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.wed` | OpenWindow | | | `data.windows.wed.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.wed.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.wed.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.thu` | OpenWindow | | | `data.windows.thu.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.thu.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.thu.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.fri` | OpenWindow | | | `data.windows.fri.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.fri.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.fri.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sat` | OpenWindow | | | `data.windows.sat.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sat.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sat.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sun` | OpenWindow | | | `data.windows.sun.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sun.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sun.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.rebootHourLocal` | integer \| null | Hour (0–23, local time) the device restarts each day; null = no scheduled restart. | | `data.timezone` | string \| null | IANA time zone the windows use; null = each screen's own time zone. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads. | | `data.screenCount` | integer | Screens that use this policy. | 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 power policy in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/power-policies/{id} Update a power policy's open and close windows, reboot hour, time zone, or name. **Notes.** - `screenCount` in this response is always 0; read the policy to get the real count. - An empty `name` keeps the current name. - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Power policy id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default on create: `Untitled policy`. | | `description` | string \| null | no | | | `windows` | object | no | Open window per weekday. `null` or an absent day is closed. A malformed day is dropped (closed), not refused. | | `windows.mon` | OpenWindow \| null | no | | | `windows.tue` | OpenWindow \| null | no | | | `windows.wed` | OpenWindow \| null | no | | | `windows.thu` | OpenWindow \| null | no | | | `windows.fri` | OpenWindow \| null | no | | | `windows.sat` | OpenWindow \| null | no | | | `windows.sun` | OpenWindow \| null | no | | | `rebootHourLocal` | number \| null | no | 0–23; rounded and clamped. Null (or a value that is not a number) turns the restart off. | | `timezone` | string \| null | no | IANA time zone (`Europe/London`). An unknown zone is refused with 422. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/power-policies/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | PowerPolicy | | | `data.id` | string | Power policy id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.description` | string \| null | | | `data.windows` | WeeklyWindows | Open window per weekday (`mon` … `sun`). A day that is absent is closed. | | `data.windows.mon` | OpenWindow | | | `data.windows.mon.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.mon.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.mon.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.mon.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.tue` | OpenWindow | | | `data.windows.tue.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.tue.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.tue.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.tue.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.wed` | OpenWindow | | | `data.windows.wed.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.wed.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.wed.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.wed.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.thu` | OpenWindow | | | `data.windows.thu.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.thu.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.thu.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.thu.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.fri` | OpenWindow | | | `data.windows.fri.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.fri.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.fri.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.fri.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sat` | OpenWindow | | | `data.windows.sat.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sat.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sat.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sat.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.windows.sun` | OpenWindow | | | `data.windows.sun.start` | string | Opening time, `HH:MM` 24-hour, local time. | | `data.windows.sun.end` | string | Closing time, `HH:MM`. An `end` at or before `start` runs past midnight. | | `data.windows.sun.volume` | integer \| null | Volume 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.brightness` | integer \| null | Backlight 0–100 while open; absent or null keeps the screen's own. | | `data.windows.sun.muted` | boolean \| null | Mute (true) or unmute (false) while open; absent or null keeps the screen's own. | | `data.rebootHourLocal` | integer \| null | Hour (0–23, local time) the device restarts each day; null = no scheduled restart. | | `data.timezone` | string \| null | IANA time zone the windows use; null = each screen's own time zone. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads. | | `data.screenCount` | integer | Screens that use this policy. | 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 power policy in this workspace. Response 422: Unknown `timezone`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/power-policies/{id}/delete Delete a power policy. Screens that use it go back to their own operating hours. A deleted policy cannot be restored. **Notes.** - A POST to `/delete`, not `DELETE`. Screens that use the policy keep the link and use their own operating hours until they get another policy. There is no restore route. - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Power policy id. | ```bash curl -X POST "https://api.brixsignage.com/v1/power-policies/{id}/delete" \ -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 power policy in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Proof 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/proof Get a proof-of-play report Get proof-of-play totals for a date range, broken down by content item and by screen, including digital-out-of-home verification fields. Use the `from` and `to` query parameters to set the date range. Counts what played, where and for how long, over a time window. Only screens the caller can see are counted. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | Window start (ISO-8601). Default: the start of the retention window. | | `to` | query | string | no | Window end (ISO-8601). Default: now. | | `screenId` | query | string | no | Only this screen. | | `screenIds` | query | string | no | Only these screens: ids separated by commas. | | `contentIds` | query | string | no | Only this content: ids separated by commas. Totals count only this content. | | `detail` | query | "screens" | no | `screens` adds `byScreen`: one row per content and screen. | ```bash curl "https://api.brixsignage.com/v1/proof" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ProofOfPlayReport | | | `data.totals` | object | | | `data.totals.plays` | integer | Successful plays (neither skipped nor failed). | | `data.totals.skipped` | integer | | | `data.totals.failed` | integer | | | `data.totals.events` | integer | Every playback-end event: plays + skipped + failed. | | `data.totals.uniqueContent` | integer | | | `data.totals.screensReporting` | integer | | | `data.byContent` | array of object | Per content, most successful plays first. | | `data.byContent[].contentId` | string | `unknown` when the player did not report one. | | `data.byContent[].contentName` | string | Falls back to the id when no name was reported. | | `data.byContent[].contentKind` | string | `media`, `app`, `creative`, …; `media` for days read from the daily rollup. | | `data.byContent[].screenName` | string \| null | Set only when exactly one screen played it. | | `data.byContent[].played` | integer | | | `data.byContent[].skipped` | integer | | | `data.byContent[].failed` | integer | | | `data.byContent[].screenCount` | integer | | | `data.byContent[].totalDurationSec` | integer | | | `data.byContent[].firstAt` | string | ISO-8601 timestamp (UTC). | | `data.byContent[].lastAt` | string | ISO-8601 timestamp (UTC). | | `data.screens` | array of object | Screens that reported in the window, by name. | | `data.screens[].id` | string | | | `data.screens[].name` | string | | | `data.from` | string | ISO-8601 timestamp (UTC). | | `data.to` | string | ISO-8601 timestamp (UTC). | | `data.retentionDays` | integer | How far back raw play events exist; older days come from the daily rollup. | | `data.truncated` | boolean | Always false: the whole window is counted. | | `data.fromRollup` | boolean | Part of the window was read from the daily rollup. | | `data.byScreen` | array of object | With `detail=screens`: one row per content and screen, by content name then screen name. | | `data.byScreen[].contentId` | string | | | `data.byScreen[].contentName` | string | | | `data.byScreen[].screenId` | string | | | `data.byScreen[].screenName` | string | The screen id when the screen no longer exists. | | `data.byScreen[].played` | integer | | | `data.byScreen[].skipped` | integer | | | `data.byScreen[].failed` | integer | | | `data.byScreen[].totalDurationSec` | integer | | | `data.byScreen[].playedDurationSec` | integer | The part of `totalDurationSec` from finished plays (not skipped or failed). A day whose daily total has no split counts its total. | | `data.byScreen[].firstAt` | string | ISO-8601 timestamp (UTC). | | `data.byScreen[].lastAt` | string | ISO-8601 timestamp (UTC). | 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/proof/advertisers Get proof of play per advertiser and venue Get proof-of-play totals for a date range, one row per advertiser and venue. An advertiser is a tag on files and designs. A venue is the location that a screen is in; a screen with no location counts at the workspace. Content with two advertiser tags counts for each tag. Use `advertisers` or `advertiser` to filter, and `format=csv` to download a file. Only finished plays count in the played time. An advertiser is a tag on files and designs. A venue is the location (org-tree node) a screen sits in; a screen with no location counts at the workspace. Content with two advertiser tags counts for each. With no `advertisers` filter, content with no tag is reported under an empty name. Only screens the caller can see are counted. `format=csv` returns a file with one row per advertiser and venue. Its `finished_min` and `finished_sec` columns and `playedDurationSec` count finished plays only; a skipped or failed play is not in them. For dates whose daily totals predate this change, they may include plays that did not finish. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | Window start (ISO-8601). Default: the start of the retention window. | | `to` | query | string | no | Window end (ISO-8601). Default: now. | | `advertisers` | query | string | no | Only these advertisers: tags separated by commas. Case does not matter. | | `advertiser` | query | string | no | Only this one advertiser (a tag). Use it to get one advertiser's CSV. | | `screenIds` | query | string | no | Only these screens: ids separated by commas. | | `contentIds` | query | string | no | Only this content: ids separated by commas. | | `format` | query | "json" \| "csv" | no | | ```bash curl "https://api.brixsignage.com/v1/proof/advertisers" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ProofOfPlayByAdvertiser | | | `data.from` | string | ISO-8601 timestamp (UTC). | | `data.to` | string | ISO-8601 timestamp (UTC). | | `data.retentionDays` | integer | | | `data.fromRollup` | boolean | Part of the window was read from the daily rollup. | | `data.advertisers` | array of object | By advertiser name; content with no tag comes last. | | `data.advertisers[].advertiser` | string | The tag, as most of its files spell it. Empty for content with no tag. | | `data.advertisers[].played` | integer | | | `data.advertisers[].skipped` | integer | | | `data.advertisers[].failed` | integer | | | `data.advertisers[].totalDurationSec` | integer | All plays, with skipped and failed plays. | | `data.advertisers[].playedDurationSec` | integer | Finished plays only: the report's minutes. A day whose daily total has no split counts its total. | | `data.advertisers[].screens` | integer | Distinct screens, each counted once. | | `data.advertisers[].venues` | integer | | | `data.advertisers[].ads` | integer | Distinct files and designs. | | `data.advertisers[].firstAt` | string | ISO-8601 timestamp (UTC). | | `data.advertisers[].lastAt` | string | ISO-8601 timestamp (UTC). | | `data.advertisers[].byVenue` | array of object | | | `data.advertisers[].byVenue[].venueId` | string | The location's id. Empty when the screen no longer exists. | | `data.advertisers[].byVenue[].venueName` | string | | | `data.advertisers[].byVenue[].screens` | integer | | | `data.advertisers[].byVenue[].played` | integer | | | `data.advertisers[].byVenue[].skipped` | integer | | | `data.advertisers[].byVenue[].failed` | integer | | | `data.advertisers[].byVenue[].totalDurationSec` | integer | | | `data.advertisers[].byVenue[].playedDurationSec` | integer | | | `data.advertisers[].byVenue[].firstAt` | string | ISO-8601 timestamp (UTC). | | `data.advertisers[].byVenue[].lastAt` | string | ISO-8601 timestamp (UTC). | | `data.advertisers[].byVenue[].ads` | array of object | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: A bad format, or an advertiser name longer than 120 characters. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/proof/events List proof-of-play events List individual playback events, one per play, for a date range. The number of events returned is capped. For totals rolled up by content item and screen, use GET /v1/proof instead. **Notes.** - `rollup` sits beside `data`, outside the usual envelope. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | ISO-8601 start (default: the start of the report window). | | `to` | query | string | no | ISO-8601 end (default: now). | | `screenId` | query | string | no | | ```bash curl "https://api.brixsignage.com/v1/proof/events" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | One row per play, newest first (at most 2000), from screens the caller can see. | | `data[].id` | string | | | `data[].screenId` | string | | | `data[].screenName` | string | The screen id when the screen no longer exists. | | `data[].contentKind` | string | `media` when not reported. | | `data[].contentId` | string | `unknown` when not reported. | | `data[].contentName` | string | `Unknown content` when not reported. | | `data[].startedAt` | string | ISO-8601 timestamp (UTC). | | `data[].durationSec` | integer | | | `data[].result` | "played" \| "skipped" \| "failed" | | | `data[].reason` | string \| null | | | `rollup` | array of object | Daily totals for the part of the range older than the raw-event window; empty when `from` is inside it. | | `rollup[].day` | string | `YYYY-MM-DD`. | | `rollup[].screenId` | string | | | `rollup[].contentId` | string | | | `rollup[].plays` | integer | | | `rollup[].totalDurationMs` | integer | | | `rollup[].played` | integer | | | `rollup[].skipped` | integer | | | `rollup[].failed` | integer | | 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/proof/export Export verified proof of play Downloads the plays in a date range with the signature and chain status of each play, a summary of counts, a SHA-256 hash of the bundle and a detached server signature. Use `from`, `to` and `screenId` to filter and `format=json` or `format=csv`. The newest 5,000 plays are included. Available only to workspaces with digital-out-of-home enabled; other workspaces get 404. Auth: Bearer token. Permission: `playback-log.view`. ```bash curl "https://api.brixsignage.com/v1/proof/export" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/proof/keys List a screen's signing keys Lists the proof-of-play signing keys that one screen has registered. `screenId` is required. Each key shows its key id, when it was first seen, the key it replaced and when it was revoked. Key material is never returned. Available only to workspaces with digital-out-of-home enabled. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/proof/keys" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/proof/keys/{keyId}/revoke Revoke a screen's signing key Marks one of a screen's signing keys as bad. Send the `screenId` in the body. From that time, plays signed with the key show as revoked, and the next new key from the screen registers as a replacement. Calling it again has no further effect. The change is recorded in the activity log. Auth: Bearer token. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `keyId` | path | string | yes | Identifier for keyId. | ```bash curl -X POST "https://api.brixsignage.com/v1/proof/keys/{keyId}/revoke" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/proof/schedules List your scheduled proof-of-play reports List the proof-of-play reports that you scheduled. Each one is sent by email every week or every month. You see only your own schedules. Auth: Bearer token. Permission: `playback-log.view`. ```bash curl "https://api.brixsignage.com/v1/proof/schedules" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of ProofReportSchedule | | | `data[].id` | string | | | `data[].name` | string | | | `data[].cadence` | "weekly" \| "monthly" | | | `data[].filters` | object | | | `data[].filters.screenIds` | array of string | | | `data[].filters.groupIds` | array of string | Groups on the org tree; each covers the groups below it. | | `data[].filters.contentIds` | array of string | | | `data[].filters.tags` | array of string | Files and designs with any of these tags, on the day the report runs. | | `data[].recipientUserIds` | array of string | | | `data[].nextRunAt` | string | ISO-8601 timestamp (UTC). | | `data[].lastRunAt` | string \| null | | | `data[].lastStatus` | 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 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/proof/schedules Email a proof-of-play report on a schedule Send a proof-of-play report by email every week or every month. Send a `name`, a `cadence` (`weekly` or `monthly`), optional `filters` and optional `recipientUserIds` (active people in this workspace; the default is you). The report shows only the screens that you can see. Only a signed-in person can schedule a report. The report runs with your access at send time and goes only to active people in this workspace. The first one goes within the hour. A signed-in person only; an API key is refused. Auth: Bearer token. Permission: `playback-log.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | At most 80 characters. | | `cadence` | "weekly" \| "monthly" | yes | | | `filters` | object | no | | | `filters.screenIds` | array of string | no | | | `filters.groupIds` | array of string | no | Groups on the org tree; each covers the groups below it. | | `filters.contentIds` | array of string | no | | | `filters.tags` | array of string | no | Files and designs with any of these tags, on the day the report runs. | | `recipientUserIds` | array of string | no | 1 to 10 people in this workspace. Default: you. | ```bash curl -X POST "https://api.brixsignage.com/v1/proof/schedules" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ProofReportSchedule | | | `data.id` | string | | | `data.name` | string | | | `data.cadence` | "weekly" \| "monthly" | | | `data.filters` | object | | | `data.filters.screenIds` | array of string | | | `data.filters.groupIds` | array of string | Groups on the org tree; each covers the groups below it. | | `data.filters.contentIds` | array of string | | | `data.filters.tags` | array of string | Files and designs with any of these tags, on the day the report runs. | | `data.recipientUserIds` | array of string | | | `data.nextRunAt` | string | ISO-8601 timestamp (UTC). | | `data.lastRunAt` | string \| null | | | `data.lastStatus` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: An API key cannot own a report. Response 422: A bad name, cadence or filter, or a recipient who is not an active person in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/proof/schedules/{id} Stop a scheduled proof-of-play report Stop a proof-of-play report that you scheduled. You can stop only your own schedules. Auth: Bearer token. Permission: `playback-log.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/proof/schedules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | boolean | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: You have no such schedule. Only its owner can stop it. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/proof/verify-bundle Verify a proof-of-play export Checks a downloaded proof-of-play export against the published signing keys: the bundle hash, the server signature, and the device signature and chain of each play. No credential is needed. Requests are rate limited, and a bundle can be at most 8 MB and 5,000 plays. Auth: none. ```bash curl -X POST "https://api.brixsignage.com/v1/proof/verify-bundle" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Recall 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/recall List recalled content Return everything currently held off screens, including its kind, name, when it was recalled, and who recalled it. Since a recall is reversible, this list is the record of what is being withheld and why, so nothing stays off screens indefinitely without anyone knowing. An item is listed only where the caller can view that kind of content at its location. Who recalled it is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example `user` or `staff`. **Notes.** - Newest first, not paginated. An item is listed only where the caller holds that kind's view permission (`media.view`, `playlist.view`, …) at its location; a `screen.view`-only key gets an empty list. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/recall" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data[].id` | string | | | `data[].name` | string \| null | | | `data[].recalledAt` | string | ISO-8601 timestamp (UTC). | | `data[].recalledBy` | string \| null | An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. Without `user.view` at the item's location, only the kind (`user`, `staff`, …). | 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/recall/creative/{id} Recall a creative from all screens Immediately remove a creative from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched. **Notes.** - A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once. Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The creative's id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/creative/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | string | ISO-8601 timestamp (UTC). | | `data.recalledBy` | string | Who recalled it. An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `creative.edit` where the creative lives. Response 404: No such creative in this workspace. Response 409: `already_recalled`: it is already recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/creative/{id}/restore Restore a recalled creative Put a recalled creative back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before. Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The creative's id. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/creative/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `creative.edit` where the creative lives. Response 404: No such creative in this workspace. Response 409: `not_recalled`: it is not recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/media/{id} Recall a media file from all screens Immediately remove a media file from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched. **Notes.** - A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The media's id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/media/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | string | ISO-8601 timestamp (UTC). | | `data.recalledBy` | string | Who recalled it. An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `media.edit` where the media lives. Response 404: No such media in this workspace. Response 409: `already_recalled`: it is already recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/media/{id}/restore Restore a recalled media file Put a recalled media file back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The media's id. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/media/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `media.edit` where the media lives. Response 404: No such media in this workspace. Response 409: `not_recalled`: it is not recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/playlist/{id} Recall a playlist from all screens Immediately remove a playlist from every screen it appears on, without deleting it or changing any other playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched. **Notes.** - A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The playlist's id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/playlist/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | string | ISO-8601 timestamp (UTC). | | `data.recalledBy` | string | Who recalled it. An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `playlist.edit` where the playlist lives. Response 404: No such playlist in this workspace. Response 409: `already_recalled`: it is already recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/playlist/{id}/restore Restore a recalled playlist Put a recalled playlist back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before. Auth: Bearer token. Permission: `playlist.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The playlist's id. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/playlist/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `playlist.edit` where the playlist lives. Response 404: No such playlist in this workspace. Response 409: `not_recalled`: it is not recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/schedule/{id} Recall a schedule from all screens Immediately remove a schedule from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched. **Notes.** - A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once. Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The schedule's id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/schedule/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | string | ISO-8601 timestamp (UTC). | | `data.recalledBy` | string | Who recalled it. An actor reference: `user:`, `apikey:`, `staff:`, `partner:` or `system…`. | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `schedule.edit` where the schedule lives. Response 404: No such schedule in this workspace. Response 409: `already_recalled`: it is already recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/recall/schedule/{id}/restore Restore a recalled schedule Put a recalled schedule back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before. Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The schedule's id. | ```bash curl -X POST "https://api.brixsignage.com/v1/recall/schedule/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" | | | `data.recalledAt` | null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `schedule.edit` where the schedule lives. Response 404: No such schedule in this workspace. Response 409: `not_recalled`: it is not recalled. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Recycle bin 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/recycle-bin List the recycle bin List every deleted item across your workspace, including media, playlists, schedules, layouts, creatives, apps, and data sources. Each entry includes the deletion time and size, so items can be restored or permanently erased within the 30-day recovery window. Deleted screens are not included; screens have their own recovery endpoints. **Notes.** - Items deleted in the last 30 days, newest first. Each kind is listed only if the caller holds its view permission (`playlist.view`, `media.view`, …) where the item lives; a `screen.view`-only key sees only screens. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/recycle-bin" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].kind` | string | | | `data[].id` | string | | | `data[].name` | string | | | `data[].deletedAt` | string | ISO-8601 timestamp (UTC). | | `data[].nodeId` | string \| null | | | `data[].sizeBytes` | integer | Stored bytes (media); 0 for other kinds. | | `data[].usageBeforeDelete` | integer | How many places used it when it was deleted. | | `data[].thumbnailUrl` | string \| null | For media: its stored address (may be an internal `r2://` reference, not a public URL). | 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/recycle-bin/{kind}/{id}/purge Permanently delete from the recycle bin Permanently erase one deleted item before the 30-day recovery window would otherwise remove it. For media, this also deletes the stored file. This action cannot be undone. **Notes.** - Irreversible. Besides the `screen.view` gate, the caller needs the kind's delete permission (`media.delete`, `integration.delete` for a banner, …). Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `kind` | path | string | yes | `screen`, `playlist`, `schedule`, `layout`, `creative`, `app`, `media`, `signage`, `data-source`, `banner` or `media-folder`. | | `id` | path | string | yes | The deleted item's id. | ```bash curl -X POST "https://api.brixsignage.com/v1/recycle-bin/{kind}/{id}/purge" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | string | | | `data.purged` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You lack the kind's delete permission (`playlist.delete`, …) where the item lives. Response 404: No such item in the recycle bin. Response 422: Unknown `kind`. Response 502: A stored file could not be removed; nothing was deleted. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Roles 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/roles List roles Returns the workspace's roles, both built-in and custom, with the permissions each one carries. **Notes.** - Not paginated. Auth: Bearer token. Permission: `permission-group.view`. ```bash curl "https://api.brixsignage.com/v1/roles" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Role | | | `data[].id` | string | | | `data[].name` | string | | | `data[].color` | string \| null | Display style for the role chip. | | `data[].description` | string | Empty string when not set. | | `data[].builtIn` | boolean | A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited. | | `data[].permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data[].features` | "all" \| array of string | Feature keys the role unlocks, or `"all"`. | | `data[].scope` | object \| object | Where the role applies: the whole workspace, or only the listed locations. | | `data[].character` | string \| null | A decorative label. Not used for access. | | `data[].viewTier` | "simple" \| "team" \| "enterprise" \| null | The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access. | | `data[].contentScope` | "all" \| "shared" \| null | What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations' content). `null` = the workspace default (`shared` unless the workspace chose `all`). A person's own setting replaces it. | | `data[].memberCount` | integer | Role assignments that use this role (one per person per location). | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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/roles Create role Creates a custom role. Provide `name` and `permissions`, a list of `resource.action` strings or `"all"`. You cannot create a role that holds permissions you do not hold yourself. **Notes.** - `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written. - `builtIn` in the body is ignored. Auth: Bearer token. Permission: `permission-group.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Required on create. | | `color` | string | no | | | `description` | string | no | | | `permissions` | "all" \| array of string | no | You must hold every permission you grant, workspace-wide. Default `[]`. | | `features` | "all" \| array of string | no | Default `[]`. | | `scope` | object \| object | no | Default `{ "kind": "workspace" }`. | | `character` | string \| null | no | | | `viewTier` | "simple" \| "team" \| "enterprise" \| null | no | The default console view for people with this role. `null` = the workspace default. Any other value is a 422. | | `contentScope` | "all" \| "shared" \| null | no | What content people with this role see (`all` / `shared`); `null` = the workspace default. Changing it needs the role's permissions workspace-wide (403). Ignored on the built-in Owner. | ```bash curl -X POST "https://api.brixsignage.com/v1/roles" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Store manager","permissions":["screen.view","screen.cast","media.view","media.create"]}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Role | A named set of permissions assigned to people at locations. | | `data.id` | string | | | `data.name` | string | | | `data.color` | string \| null | Display style for the role chip. | | `data.description` | string | Empty string when not set. | | `data.builtIn` | boolean | A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.features` | "all" \| array of string | Feature keys the role unlocks, or `"all"`. | | `data.scope` | object \| object | Where the role applies: the whole workspace, or only the listed locations. | | `data.character` | string \| null | A decorative label. Not used for access. | | `data.viewTier` | "simple" \| "team" \| "enterprise" \| null | The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access. | | `data.contentScope` | "all" \| "shared" \| null | What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations' content). `null` = the workspace default (`shared` unless the workspace chose `all`). A person's own setting replaces it. | | `data.memberCount` | integer | Role assignments that use this role (one per person per location). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: `permissions` holds a permission you do not hold workspace-wide. Response 422: `name` missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/roles/{id} Get role Returns one role with its full list of permissions. Auth: Bearer token. Permission: `permission-group.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Role id. | ```bash curl "https://api.brixsignage.com/v1/roles/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Role | A named set of permissions assigned to people at locations. | | `data.id` | string | | | `data.name` | string | | | `data.color` | string \| null | Display style for the role chip. | | `data.description` | string | Empty string when not set. | | `data.builtIn` | boolean | A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.features` | "all" \| array of string | Feature keys the role unlocks, or `"all"`. | | `data.scope` | object \| object | Where the role applies: the whole workspace, or only the listed locations. | | `data.character` | string \| null | A decorative label. Not used for access. | | `data.viewTier` | "simple" \| "team" \| "enterprise" \| null | The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access. | | `data.contentScope` | "all" \| "shared" \| null | What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations' content). `null` = the workspace default (`shared` unless the workspace chose `all`). A person's own setting replaces it. | | `data.memberCount` | integer | Role assignments that use this role (one per person per location). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | 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 role in this workspace (or it is deleted). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/roles/{id} Update role Updates a role. The same rule as creating a role applies: you cannot add or remove a permission you do not hold yourself. Only a signed-in account owner can take full ownership away from a role that people hold; an API key cannot. On a built-in role, only the name, color and description change; its permissions, features and scope stay fixed. **Notes.** - `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written. - `builtIn` in the body is ignored. - On the built-in Owner role, `permissions`, `features` and `scope` are ignored without an error; only `name`, `color`, `description`, `character` and `viewTier` change. The other built-in roles edit like custom roles, except that `permissions` cannot be `"all"` (422). Auth: Bearer token. Permission: `permission-group.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Role id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Required on create. | | `color` | string | no | | | `description` | string | no | | | `permissions` | "all" \| array of string | no | You must hold every permission you grant, workspace-wide. Default `[]`. | | `features` | "all" \| array of string | no | Default `[]`. | | `scope` | object \| object | no | Default `{ "kind": "workspace" }`. | | `character` | string \| null | no | | | `viewTier` | "simple" \| "team" \| "enterprise" \| null | no | The default console view for people with this role. `null` = the workspace default. Any other value is a 422. | | `contentScope` | "all" \| "shared" \| null | no | What content people with this role see (`all` / `shared`); `null` = the workspace default. Changing it needs the role's permissions workspace-wide (403). Ignored on the built-in Owner. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/roles/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Role | A named set of permissions assigned to people at locations. | | `data.id` | string | | | `data.name` | string | | | `data.color` | string \| null | Display style for the role chip. | | `data.description` | string | Empty string when not set. | | `data.builtIn` | boolean | A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.features` | "all" \| array of string | Feature keys the role unlocks, or `"all"`. | | `data.scope` | object \| object | Where the role applies: the whole workspace, or only the listed locations. | | `data.character` | string \| null | A decorative label. Not used for access. | | `data.viewTier` | "simple" \| "team" \| "enterprise" \| null | The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access. | | `data.contentScope` | "all" \| "shared" \| null | What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations' content). `null` = the workspace default (`shared` unless the workspace chose `all`). A person's own setting replaces it. | | `data.memberCount` | integer | Role assignments that use this role (one per person per location). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You would add or remove a permission you do not hold workspace-wide, or change `scope` of a role whose permissions you do not hold workspace-wide; `owner_required`: the change takes full ownership away from a role people hold, and the caller is not a signed-in owner (an API key never is). Response 404: No such role in this workspace. Response 409: `last_owner_role`: this is the only role with full ownership. Response 422: `permissions: "all"` on a built-in role other than Owner. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/roles/{id} Delete role Soft-deletes a custom role. The role can later be restored. Refuses the request while anyone is still assigned to the role. Auth: Bearer token. Permission: `permission-group.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Role id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/roles/{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 role in this workspace. Response 409: `protected` (a built-in role), `last_owner_role`, or `in_use` (people still hold the role). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/roles/{id}/restore Restore deleted role Restores a previously deleted custom role. Requires the same permission needed to delete a role. **Notes.** - Answers the whole restored role, not the `{ id, restored }` acknowledgement other restores use. Auth: Bearer token. Permission: `permission-group.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Role id. | ```bash curl -X POST "https://api.brixsignage.com/v1/roles/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Role | A named set of permissions assigned to people at locations. | | `data.id` | string | | | `data.name` | string | | | `data.color` | string \| null | Display style for the role chip. | | `data.description` | string | Empty string when not set. | | `data.builtIn` | boolean | A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited. | | `data.permissions` | "all" \| array of string | `resource.action` permissions, or `"all"` (every permission, now and later). | | `data.features` | "all" \| array of string | Feature keys the role unlocks, or `"all"`. | | `data.scope` | object \| object | Where the role applies: the whole workspace, or only the listed locations. | | `data.character` | string \| null | A decorative label. Not used for access. | | `data.viewTier` | "simple" \| "team" \| "enterprise" \| null | The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access. | | `data.contentScope` | "all" \| "shared" \| null | What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations' content). `null` = the workspace default (`shared` unless the workspace chose `all`). A person's own setting replaces it. | | `data.memberCount` | integer | Role assignments that use this role (one per person per location). | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | 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 role in this workspace. Response 409: `not_deleted`: the role is not deleted. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Schedules 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/schedules List schedules List the workspace's schedules, including their dayparting blocks. Auth: Bearer token. Permission: `schedule.view`. ```bash curl "https://api.brixsignage.com/v1/schedules" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Schedule | | | `data[].id` | string | Schedule id. | | `data[].spaceId` | string | | | `data[].nodeId` | string \| null | Home location (null = workspace root). | | `data[].name` | string | | | `data[].fallbackName` | string | Label of the content played between blocks. | | `data[].fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data[].fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data[].fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data[].fallbackContentId` | string \| null | | | `data[].playsSolely` | boolean | | | `data[].timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data[].startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data[].expiresAt` | string \| null | | | `data[].approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | | | `data[].recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data[].recalledBy` | string \| null | | | `data[].approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data[].importSourceId` | string \| null | | | `data[].usedByScreenCount` | integer | Screens assigned this schedule. | | `data[].fallbackContentRef` | object \| null | | | `data[].fallbackThumbnailUrl` | string \| null | | | `data[].blocks` | array of ScheduleBlock | | | `data[].blocks[].id` | string | Schedule block id. | | `data[].blocks[].label` | string | | | `data[].blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data[].blocks[].startTime` | string | 24-hour `HH:MM`. | | `data[].blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data[].blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data[].blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data[].blocks[].endDate` | string \| null | | | `data[].blocks[].repeatEveryWeeks` | integer | 1–52. | | `data[].blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data[].blocks[].refId` | string | | | `data[].blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data[].blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data[].blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data[].blocks[].thumbnailUrl` | string \| null | | | `data[].blocks[].position` | integer | | 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/schedules Create a schedule with a `name` and an optional `nodeId` and other fields. Safe to retry with an idempotency key. Creates an empty schedule. Add its dayparts with POST /v1/schedules/{id}/blocks, then assign it to screens. **Notes.** - Create returns the stored row plus `blocks: []`, not the composed schedule the other schedule routes return: no `usedByScreenCount`, `fallbackContentRef`, `fallbackThumbnailUrl`, `recalledAt`, `approvedSnapshot` or `importSourceId`. Auth: Bearer token. Permission: `schedule.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Required. | | `nodeId` | string | no | Home location. Default: the caller's own location. | | `fallbackName` | string | no | | | `fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | no | | | `fallbackContentId` | string | no | | | `fallbackMode` | "content" \| "off" | no | | | `playsSolely` | boolean | no | | | `timeBasis` | "device" \| "cms" | no | | | `startsAt` | string \| null | no | `YYYY-MM-DD` or ISO-8601. | | `expiresAt` | string \| null | no | `YYYY-MM-DD` or ISO-8601. | ```bash curl -X POST "https://api.brixsignage.com/v1/schedules" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Weekday dayparts","fallbackContentKind":"playlist","fallbackContentId":"pl_2a3b4c5d6e7f8a9b","startsAt":"2026-10-01"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.blocks` | array of ScheduleBlock | Always empty on create. | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | ```json { "data": { "id": "sch_6f7a8b9c0d1e2f3a", "spaceId": "space_1a2b3c4d5e6f7a8b", "nodeId": null, "name": "Weekday dayparts", "fallbackName": "Default Loop", "fallbackContentKind": "playlist", "fallbackContentId": "pl_2a3b4c5d6e7f8a9b", "fallbackMode": "content", "playsSolely": false, "timeBasis": "device", "startsAt": "2026-10-01", "expiresAt": null, "approvalState": "draft", "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "blocks": [] } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the fallback content is not shared to the schedule's location. Response 404: The fallback content or location does not exist in this workspace. Response 422: `name` missing, or an unparseable `startsAt` / `expiresAt`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/schedules/{id} Get a schedule Retrieve one schedule, including its ordered blocks, with each block's time window, recurrence, content reference, and priority. Auth: Bearer token. Permission: `schedule.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | ```bash curl "https://api.brixsignage.com/v1/schedules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data.recalledBy` | string \| null | | | `data.approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data.importSourceId` | string \| null | | | `data.usedByScreenCount` | integer | Screens assigned this schedule. | | `data.fallbackContentRef` | object \| null | | | `data.fallbackThumbnailUrl` | string \| null | | | `data.blocks` | array of ScheduleBlock | | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | | `data.requiresApproval` | boolean | The schedule's location requires approval before edits air. | 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 schedule in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/schedules/{id} Update a schedule Edit a schedule's own fields, such as name, node, timezone, and default behaviour. Blocks are managed through the separate /blocks routes. Partial update of schedule-level fields. A playback change to an approved schedule returns it to `draft`. Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Required. | | `nodeId` | string \| null | no | Move to another location (needs schedule.edit there too). | | `fallbackName` | string | no | | | `fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | no | | | `fallbackContentId` | string \| null | no | | | `fallbackMode` | "content" \| "off" | no | | | `playsSolely` | boolean | no | | | `timeBasis` | "device" \| "cms" | no | | | `startsAt` | string \| null | no | `YYYY-MM-DD` or ISO-8601. | | `expiresAt` | string \| null | no | `YYYY-MM-DD` or ISO-8601. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/schedules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Schedule | A schedule with its timed blocks. | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data.recalledBy` | string \| null | | | `data.approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data.importSourceId` | string \| null | | | `data.usedByScreenCount` | integer | Screens assigned this schedule. | | `data.fallbackContentRef` | object \| null | | | `data.fallbackThumbnailUrl` | string \| null | | | `data.blocks` | array of ScheduleBlock | | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: Moving to a location you cannot edit, or fallback content not shared there. Response 404: No such schedule, fallback content or location. Response 422: Unparseable `startsAt` / `expiresAt`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/schedules/{id} Delete a schedule to the recycle bin. Screens using it fall back to their assigned content. Soft-deletes into the recycle bin. Screens on it fall back to their other content. Auth: Bearer token. Permission: `schedule.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | | `force` | query | "true" | no | Delete even when shared; the shares are removed too. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/schedules/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | | 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 schedule. Response 409: `content_shared`: the schedule is shared; the body carries `shareCount`. Retry with `?force=true`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/schedules/{id}/blocks Add a block to a schedule Add one dayparting block to a schedule with `refKind`, `refId`, `days`, `startTime`, `endTime`, and an optional `priority` and other fields. **Notes.** - The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current). Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | yes | Required on create. | | `refId` | string | yes | Required on create. | | `label` | string | no | Default "Block". | | `daysOfWeek` | array of integer | no | 0 = Sunday. Default: every day. | | `startTime` | string | no | 24-hour `HH:MM`. Default `09:00`. | | `endTime` | string | no | 24-hour `HH:MM`; `24:00` is accepted as midnight. Default `17:00`. | | `priority` | integer | no | Clamped to 0–1000. | | `startDate` | string \| null | no | `YYYY-MM-DD`. Any other value is stored as null. | | `endDate` | string \| null | no | | | `repeatEveryWeeks` | integer | no | Clamped to 1–52. | | `screensOff` | boolean | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/schedules/{id}/blocks" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Schedule | A schedule with its timed blocks. | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data.recalledBy` | string \| null | | | `data.approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data.importSourceId` | string \| null | | | `data.usedByScreenCount` | integer | Screens assigned this schedule. | | `data.fallbackContentRef` | object \| null | | | `data.fallbackThumbnailUrl` | string \| null | | | `data.blocks` | array of ScheduleBlock | | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not shared to the schedule's location. Response 404: No such schedule, or the content does not exist in this workspace. Response 422: Missing `refKind`/`refId`, or a malformed time. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/schedules/{id}/blocks/{blockId} Update a schedule block Edit one dayparting block's time window, days, priority, or content reference. Partial: omitted fields keep their stored value. **Notes.** - The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current). Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | | `blockId` | path | string | yes | Block id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | no | Required on create. | | `refId` | string | no | Required on create. | | `label` | string | no | Default "Block". | | `daysOfWeek` | array of integer | no | 0 = Sunday. Default: every day. | | `startTime` | string | no | 24-hour `HH:MM`. Default `09:00`. | | `endTime` | string | no | 24-hour `HH:MM`; `24:00` is accepted as midnight. Default `17:00`. | | `priority` | integer | no | Clamped to 0–1000. | | `startDate` | string \| null | no | `YYYY-MM-DD`. Any other value is stored as null. | | `endDate` | string \| null | no | | | `repeatEveryWeeks` | integer | no | Clamped to 1–52. | | `screensOff` | boolean | no | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/schedules/{id}/blocks/{blockId}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Schedule | A schedule with its timed blocks. | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data.recalledBy` | string \| null | | | `data.approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data.importSourceId` | string \| null | | | `data.usedByScreenCount` | integer | Screens assigned this schedule. | | `data.fallbackContentRef` | object \| null | | | `data.fallbackThumbnailUrl` | string \| null | | | `data.blocks` | array of ScheduleBlock | | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not shared to the schedule's location. Response 404: No such schedule or block. Response 422: A malformed time. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/schedules/{id}/blocks/{blockId} Remove a schedule block Remove one dayparting block from a schedule. Removes the block (a hard delete of the child row) and re-packs positions. **Notes.** - The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current). - An unknown `blockId` is not an error: the route answers 200 with the unchanged schedule. Auth: Bearer token. Permission: `schedule.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | | `blockId` | path | string | yes | Block id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/schedules/{id}/blocks/{blockId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Schedule | A schedule with its timed blocks. | | `data.id` | string | Schedule id. | | `data.spaceId` | string | | | `data.nodeId` | string \| null | Home location (null = workspace root). | | `data.name` | string | | | `data.fallbackName` | string | Label of the content played between blocks. | | `data.fallbackSharedFrom` | string \| null | The workspace that shares the content played between blocks in, when it is not this workspace's own. Null for this workspace's own content. | | `data.fallbackMode` | "content" \| "off" | Between blocks: play the fallback content, or turn the screens off. | | `data.fallbackContentKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" \| null | | | `data.fallbackContentId` | string \| null | | | `data.playsSolely` | boolean | | | `data.timeBasis` | "device" \| "cms" | Whose clock the block times use: each screen's local time, or the workspace's. | | `data.startsAt` | string \| null | `YYYY-MM-DD` or ISO-8601; null = no start bound. | | `data.expiresAt` | string \| null | | | `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.recalledAt` | string \| null | Set while the schedule is recalled (withheld from every screen). | | `data.recalledBy` | string \| null | | | `data.approvedSnapshot` | string \| null | JSON of the blocks as last approved (approval workflow). | | `data.importSourceId` | string \| null | | | `data.usedByScreenCount` | integer | Screens assigned this schedule. | | `data.fallbackContentRef` | object \| null | | | `data.fallbackThumbnailUrl` | string \| null | | | `data.blocks` | array of ScheduleBlock | | | `data.blocks[].id` | string | Schedule block id. | | `data.blocks[].label` | string | | | `data.blocks[].daysOfWeek` | array of integer | 0 = Sunday … 6 = Saturday. Empty = every day. | | `data.blocks[].startTime` | string | 24-hour `HH:MM`. | | `data.blocks[].endTime` | string | 24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight. | | `data.blocks[].priority` | integer | 0–1000; higher wins where blocks overlap. | | `data.blocks[].startDate` | string \| null | `YYYY-MM-DD`, or null for no start bound. | | `data.blocks[].endDate` | string \| null | | | `data.blocks[].repeatEveryWeeks` | integer | 1–52. | | `data.blocks[].refKind` | "media" \| "playlist" \| "app" \| "layout" \| "creative" \| "signage" | | | `data.blocks[].refId` | string | | | `data.blocks[].screensOff` | boolean | The block turns the screens off instead of playing `ref`. | | `data.blocks[].contentName` | string | Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves. | | `data.blocks[].sharedFrom` | string \| null | The workspace that shares this block's content in, when it is not this workspace's own. Null for this workspace's own content. | | `data.blocks[].thumbnailUrl` | string \| null | | | `data.blocks[].position` | integer | | 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 schedule. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/schedules/{id}/restore Restore a deleted schedule so its block layout returns to the schedule library. **Notes.** - Also restores the cross-workspace shares that were removed when the schedule was deleted. Auth: Bearer token. Permission: `schedule.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Schedule id. | ```bash curl -X POST "https://api.brixsignage.com/v1/schedules/{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 schedule in this workspace. Response 409: `not_deleted`: the schedule is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/schedules/bulk-delete Delete schedules in bulk Move up to 500 schedules to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in `ok` and the rest in `failed`, so one failure does not stop the rest. Auth: Bearer token. ```bash curl -X POST "https://api.brixsignage.com/v1/schedules/bulk-delete" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Screen groups 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/screen-groups List screen groups List the screen groups in your workspace. Each group includes the number of screens in it and the IDs of the screens you have access to see. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/screen-groups" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of ScreenGroup | | | `data[].id` | string | Screen group id. | | `data[].name` | string | | | `data[].description` | string \| null | | | `data[].screenCount` | integer | Members the caller can see. | | `data[].screenIds` | array of string | Member screen ids the caller can see, oldest membership first. | | `data[].arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `data[].positions` | array of string | Position names in wall order: left to right, then top to bottom. Empty when the set has none. | | `data[].positionOf` | object | Screen id → index into `positions`, for the members that have a position. | | `data[].rules` | array of object | | | `data[].rules[].name` | string | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `data[].rules[].ending` | string | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `data[].rules[].tag` | string | The screen has this tag. | | `data[].rules[].nodeId` | string | The screen is in this location, or in one inside it. | | `data[].rules[].position` | integer \| null | The position a matching screen takes: an index into `positions`. | | `data[].autoAdd` | boolean | A new, renamed, re-tagged or moved screen that matches a rule joins by itself. A rule never takes a screen out. | | `data[].layout` | object \| null | How the positions sit on the wall. Null = one row. | | `data[].positionContent` | array of object \| null | What each position plays (`arrangement: each`), one entry per position. Empty when the set has none. | | `data[].health` | object | How many of the members the caller can see are on. | | `data[].health.online` | integer | | | `data[].health.offline` | integer | | | `data[].health.other` | integer | Members that are neither: not paired yet, or turned off for the account. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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/screen-groups Create a screen group Create a named group of screens. Optionally pass `screenIds` to add screens to the group at creation time. Auth: Bearer token. Permission: `screen.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Unique in the workspace (case-insensitive). Trimmed; longer names are cut at 120. | | `description` | string | no | Trimmed; cut at 500 characters. | | `screenIds` | array of string | no | Seed members, with no position. Ids you cannot edit are skipped. | | `placeScreens` | array of object | no | Seed members IN positions, one entry per position. Send `positions` in the same call. A screen is named in one position only. Without positions a group cannot use content per position or play different items side by side. | | `placeScreens[].position` | integer | yes | Index into `positions`, 0 = the first (left). | | `placeScreens[].screenIds` | array of string | yes | | | `arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | no | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `positions` | array of string | no | Replaces the position names. Wall order: left to right, then top to bottom. | | `layout` | object \| null | no | | | `rules` | array of object | no | Replaces the rules. An empty rule is dropped: it never selects every screen. | | `rules[].name` | string | no | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `rules[].ending` | string | no | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `rules[].tag` | string | no | The screen has this tag. | | `rules[].nodeId` | string | no | The screen is in this location, or in one inside it. | | `rules[].position` | integer \| null | no | The position a matching screen takes: an index into `positions`. | | `autoAdd` | boolean | no | | | `applyRules` | boolean | no | True adds every screen the rules select now. Screens you cannot edit are skipped. A member that has a position keeps it; a member with no position takes the one its rule names. | | `positionContent` | array of object \| null \| null | no | Content per position. Sets `arrangement` to `each`; null (or all nulls) clears the list and returns the set to `none`, and the screens keep what they play. Needs `screen.edit` and `screen.cast` for the whole workspace. Not behind the playback switch. The response's `assigned` lists, per position, `updated`, `notShared`, `needsApproval` and the screen ids that changed. | ```bash curl -X POST "https://api.brixsignage.com/v1/screen-groups" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Screen group id. | | `data.name` | string | | | `data.description` | string \| null | | | `data.screenCount` | integer | Members the caller can see. | | `data.screenIds` | array of string | Member screen ids the caller can see, oldest membership first. | | `data.arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `data.positions` | array of string | Position names in wall order: left to right, then top to bottom. Empty when the set has none. | | `data.positionOf` | object | Screen id → index into `positions`, for the members that have a position. | | `data.rules` | array of object | | | `data.rules[].name` | string | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `data.rules[].ending` | string | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `data.rules[].tag` | string | The screen has this tag. | | `data.rules[].nodeId` | string | The screen is in this location, or in one inside it. | | `data.rules[].position` | integer \| null | The position a matching screen takes: an index into `positions`. | | `data.autoAdd` | boolean | A new, renamed, re-tagged or moved screen that matches a rule joins by itself. A rule never takes a screen out. | | `data.layout` | object \| null | How the positions sit on the wall. Null = one row. | | `data.positionContent` | array of object \| null | What each position plays (`arrangement: each`), one entry per position. Empty when the set has none. | | `data.health` | object | How many of the members the caller can see are on. | | `data.health.online` | integer | | | `data.health.offline` | integer | | | `data.health.other` | integer | Members that are neither: not paired yet, or turned off for the account. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.matched` | integer | Screens that joined because of `applyRules`. | | `data.assigned` | array of object | With content per position: what the save assigned, per position. | | `data.assigned[].position` | integer | | | `data.assigned[].updated` | integer | | | `data.assigned[].notShared` | integer | | | `data.assigned[].needsApproval` | integer | | | `data.assigned[].refused` | string | | | `data.assigned[].screenIds` | array of string | | Response 401: Missing, expired or revoked bearer token. Response 403: A set-wide setting from a caller without `screen.edit` for the whole workspace; `positionContent` from a caller without `screen.cast` for the whole workspace; or `feature_disabled`: `stagger`, `mirror`, `chase` or `wipe` where the workspace does not have it yet. Response 409: `name_taken`: a group with this name exists. Response 422: `name` missing, `screenIds` empty / over 5000, or a set-wide setting with the wrong shape. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screen-groups/{id} Get a screen group Get one screen group and the screens in it. Requesting a group that belongs to a different workspace returns a not-found error. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | ```bash curl "https://api.brixsignage.com/v1/screen-groups/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ScreenGroup | A named, saved set of screens — the unit for bulk content, commands and settings. It can also arrange its screens: positions, rules that add screens, and a way to play one playlist together. | | `data.id` | string | Screen group id. | | `data.name` | string | | | `data.description` | string \| null | | | `data.screenCount` | integer | Members the caller can see. | | `data.screenIds` | array of string | Member screen ids the caller can see, oldest membership first. | | `data.arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `data.positions` | array of string | Position names in wall order: left to right, then top to bottom. Empty when the set has none. | | `data.positionOf` | object | Screen id → index into `positions`, for the members that have a position. | | `data.rules` | array of object | | | `data.rules[].name` | string | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `data.rules[].ending` | string | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `data.rules[].tag` | string | The screen has this tag. | | `data.rules[].nodeId` | string | The screen is in this location, or in one inside it. | | `data.rules[].position` | integer \| null | The position a matching screen takes: an index into `positions`. | | `data.autoAdd` | boolean | A new, renamed, re-tagged or moved screen that matches a rule joins by itself. A rule never takes a screen out. | | `data.layout` | object \| null | How the positions sit on the wall. Null = one row. | | `data.positionContent` | array of object \| null | What each position plays (`arrangement: each`), one entry per position. Empty when the set has none. | | `data.health` | object | How many of the members the caller can see are on. | | `data.health.online` | integer | | | `data.health.offline` | integer | | | `data.health.other` | integer | Members that are neither: not paired yet, or turned off for the account. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | 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 group in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/screen-groups/{id} Change a screen group Update a screen group's name or description. A name already used by another group in your workspace is refused with a `name_taken` conflict error. Renames a group, and changes its set-wide settings: its positions, its physical layout, the rules that add screens to it, and how its screens play one playlist together. The set-wide settings (`arrangement`, `positions`, `layout`, `rules`, `autoAdd`, `applyRules`) need `screen.edit` for the whole workspace, not for one location: a rule selects screens anywhere and a way of playing changes what every member shows. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `description` | string \| null | no | | | `arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | no | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `positions` | array of string | no | Replaces the position names. Wall order: left to right, then top to bottom. | | `layout` | object \| null | no | | | `rules` | array of object | no | Replaces the rules. An empty rule is dropped: it never selects every screen. | | `rules[].name` | string | no | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `rules[].ending` | string | no | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `rules[].tag` | string | no | The screen has this tag. | | `rules[].nodeId` | string | no | The screen is in this location, or in one inside it. | | `rules[].position` | integer \| null | no | The position a matching screen takes: an index into `positions`. | | `autoAdd` | boolean | no | | | `applyRules` | boolean | no | True adds every screen the rules select now. Screens you cannot edit are skipped. A member that has a position keeps it; a member with no position takes the one its rule names. | | `positionContent` | array of object \| null \| null | no | Content per position. Sets `arrangement` to `each`; null (or all nulls) clears the list and returns the set to `none`, and the screens keep what they play. Needs `screen.edit` and `screen.cast` for the whole workspace. Not behind the playback switch. The response's `assigned` lists, per position, `updated`, `notShared`, `needsApproval` and the screen ids that changed. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/screen-groups/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Screen group id. | | `data.name` | string | | | `data.description` | string \| null | | | `data.screenCount` | integer | Members the caller can see. | | `data.screenIds` | array of string | Member screen ids the caller can see, oldest membership first. | | `data.arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `data.positions` | array of string | Position names in wall order: left to right, then top to bottom. Empty when the set has none. | | `data.positionOf` | object | Screen id → index into `positions`, for the members that have a position. | | `data.rules` | array of object | | | `data.rules[].name` | string | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `data.rules[].ending` | string | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `data.rules[].tag` | string | The screen has this tag. | | `data.rules[].nodeId` | string | The screen is in this location, or in one inside it. | | `data.rules[].position` | integer \| null | The position a matching screen takes: an index into `positions`. | | `data.autoAdd` | boolean | A new, renamed, re-tagged or moved screen that matches a rule joins by itself. A rule never takes a screen out. | | `data.layout` | object \| null | How the positions sit on the wall. Null = one row. | | `data.positionContent` | array of object \| null | What each position plays (`arrangement: each`), one entry per position. Empty when the set has none. | | `data.health` | object | How many of the members the caller can see are on. | | `data.health.online` | integer | | | `data.health.offline` | integer | | | `data.health.other` | integer | Members that are neither: not paired yet, or turned off for the account. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.matched` | integer | Screens that joined because of `applyRules`. | | `data.placed` | integer | Members that had no position and took the one their rule names, because of `applyRules`. | | `data.assigned` | array of object | With content per position: what the save assigned, per position. | | `data.assigned[].position` | integer | | | `data.assigned[].updated` | integer | | | `data.assigned[].notShared` | integer | | | `data.assigned[].needsApproval` | integer | | | `data.assigned[].refused` | string | | | `data.assigned[].screenIds` | array of string | | Response 401: Missing, expired or revoked bearer token. Response 403: A set-wide setting from a caller without `screen.edit` for the whole workspace; `positionContent` from a caller without `screen.cast` for the whole workspace; or `feature_disabled`: `stagger`, `mirror`, `chase` or `wipe` where the workspace does not have it yet. Response 404: No screen group with this id. Response 409: `name_taken`. Response 422: `name` is empty, a set-wide setting has the wrong shape, or `stagger` / `chase` / `wipe` with fewer than two positions. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/screen-groups/{id} Delete a screen group. The screens in the group are not affected, and the group's membership is kept so it can be fully restored with POST /v1/screen-groups/:id/restore. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/screen-groups/{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 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screen-groups/{id}/restore Restore a deleted screen group along with its original screen membership. A group that is not currently deleted is refused with a conflict error. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screen-groups/{id}/restore" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ScreenGroup | A named, saved set of screens — the unit for bulk content, commands and settings. It can also arrange its screens: positions, rules that add screens, and a way to play one playlist together. | | `data.id` | string | Screen group id. | | `data.name` | string | | | `data.description` | string \| null | | | `data.screenCount` | integer | Members the caller can see. | | `data.screenIds` | array of string | Member screen ids the caller can see, oldest membership first. | | `data.arrangement` | "none" \| "stagger" \| "mirror" \| "chase" \| "wipe" \| "each" | How the set's screens play. `none`: each screen on its own. One playlist together: `stagger`: every screen changes at the same moment and shows a different item. The order is the group's own: the items are shuffled once for the group, each screen plays every item once per lap, and no item moves to the screen beside it on the next change when the playlist is long enough. The playlist needs at least as many items as the group has positions (with fewer, positions that many apart show the same item); `mirror`: the same item on every screen at the same moment; `chase`: the same item, each screen a moment after the one on its left; `wipe`: the same item, and the change is one edge that travels across the wall, from screen to screen, by where each position hangs (`layout.cells`, `layout.bezelMm`, `layout.wipe`). The wipe moves stills and apps; a video changes with a cut when the edge reaches its screen. `stagger`, `chase` and `wipe` need at least two positions. `each`: every position has its own content (`positionContent`); the screens share no clock. | | `data.positions` | array of string | Position names in wall order: left to right, then top to bottom. Empty when the set has none. | | `data.positionOf` | object | Screen id → index into `positions`, for the members that have a position. | | `data.rules` | array of object | | | `data.rules[].name` | string | Name pattern. `*` = any text, `?` = one character, case does not count: `*-GUN-L`. With no wildcard it matches anywhere in the name. | | `data.rules[].ending` | string | The last part of the name (after its last space, `-`, `_` or `.`) is exactly this, case does not count: `L` matches `114-GUN-L`, not `114-GUN-FULL`. | | `data.rules[].tag` | string | The screen has this tag. | | `data.rules[].nodeId` | string | The screen is in this location, or in one inside it. | | `data.rules[].position` | integer \| null | The position a matching screen takes: an index into `positions`. | | `data.autoAdd` | boolean | A new, renamed, re-tagged or moved screen that matches a rule joins by itself. A rule never takes a screen out. | | `data.layout` | object \| null | How the positions sit on the wall. Null = one row. | | `data.positionContent` | array of object \| null | What each position plays (`arrangement: each`), one entry per position. Empty when the set has none. | | `data.health` | object | How many of the members the caller can see are on. | | `data.health.online` | integer | | | `data.health.offline` | integer | | | `data.health.other` | integer | Members that are neither: not paired yet, or turned off for the account. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | 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 screen group with this id. Response 409: `not_deleted`, or a live group has the same name. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screen-groups/{id}/screens Add screens to a group. Adding a screen already in the group has no additional effect. A screen from another workspace, a deleted screen, or a screen outside your organization scope is skipped and counted in the response, but not identified individually. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | yes | Screen ids (1–5000). Ids you cannot edit, or that do not exist, are skipped. | | `position` | integer \| null | no | Index into the set's `positions` (null = no position), written to EVERY screen in the call, members already in the set included: this is how a screen moves from Left to Right. Leave it out and nothing that is already placed moves. | ```bash curl -X POST "https://api.brixsignage.com/v1/screen-groups/{id}/screens" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.added` | integer | Screens newly added (existing members are not counted). | | `data.positioned` | integer | Members whose position this call changed. | | `data.skipped` | integer | Requested ids that do not exist or that the caller cannot edit. | | `data.screenIds` | array of string | The screens newly added. | 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 group. Response 422: `screenIds` empty or over 5000, or `position` past the set's positions. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/screen-groups/{id}/screens/{screenId} Remove a screen from a group Remove one screen from a group. Returns a not-found error if the screen is not currently in the group. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | | `screenId` | path | string | yes | Screen id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/screen-groups/{id}/screens/{screenId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.removed` | integer | 1 when the screen was a member, else 0. | | `data.screenIds` | array of string | The remaining members the caller can see. | 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/screen-groups/{id}/screens/remove Remove screens from a group Remove one or more screens from a group. This only removes the screens from the group; the screens themselves are not affected. Removing a screen that is not in the group has no effect. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen group id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | yes | Screen ids (1–5000). Ids you cannot edit, or that do not exist, are skipped. | ```bash curl -X POST "https://api.brixsignage.com/v1/screen-groups/{id}/screens/remove" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.removed` | integer | | | `data.skipped` | integer | Requested ids that do not exist or that the caller cannot edit. | | `data.screenIds` | array of string | The screens removed. | 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 group. Response 422: `screenIds` empty or over 5000. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Screens (part 1 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/screens List screens List the screens in your workspace, including each screen's organization node, assigned content, online status, and player settings. Pass `limit` (and optionally `cursor`) to page through results; without `limit`, the full list is returned. Results are limited to the organization nodes you can see. **Notes.** - The `state` object is a lean subset here (connection, currentContent, cache, proof, sync, telemetry.identity/display); GET /v1/screens/{id} returns the full snapshot. - `nextCursor` is a screen id (keyset by id), not the base64 cursor the shared resource routes use. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | integer | no | Page size (max 500). Omit to get every screen. | | `cursor` | query | string | no | The `nextCursor` of the previous page (a screen id). | | `q` | query | string | no | Only screens whose name contains this text (not case-sensitive). `%` and `_` match themselves. | | `nodeId` | query | string | no | Only screens at or under this location. An unknown location is 404. | ```bash curl "https://api.brixsignage.com/v1/screens" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of Screen | | | `data[].id` | string | Screen id. | | `data[].spaceId` | string | Workspace id. | | `data[].nodeId` | string \| null | Location (org node) the screen belongs to; null = workspace root. | | `data[].name` | string | | | `data[].status` | "online" \| "offline" \| "pairing" | `pairing` = no device has checked in yet. | | `data[].lastSeenAt` | string \| null | Last heartbeat or socket ping reply, whichever is later. | | `data[].coreUpdateOfferedAt` | string \| null | | | `data[].contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | What is assigned. Null = nothing assigned. | | `data[].contentId` | string \| null | | | `data[].contentFit` | null | Retired; always null. Fit is set on the content. | | `data[].deactivatedAt` | string \| null | Set while an operator has deactivated the screen. | | `data[].awaitingPaymentAt` | string \| null | Set while the screen waits for payment: it was paired past the screens on the plan. It starts to play when the plan has room. | | `data[].tags` | array of string | | | `data[].rotation` | integer | 0, 90, 180 or 270 degrees. | | `data[].rotationCommandedAt` | string \| null | | | `data[].timezone` | string \| null | IANA time zone; null = inherited. | | `data[].timezoneSource` | "operator" \| "device" \| null | | | `data[].operatingHours` | string | `default`, or a JSON-encoded weekly window. | | `data[].lastPanelCommand` | string \| null | | | `data[].scheduleScreensOff` | boolean | | | `data[].displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | | | `data[].playbackMode` | "sync" \| "unsync" \| "device-time" | | | `data[].locationLabel` | string \| null | | | `data[].locationLat` | number \| null | | | `data[].locationLng` | number \| null | | | `data[].ipCity` | string \| null | | | `data[].ipRegion` | string \| null | | | `data[].ipCountry` | string \| null | | | `data[].ipLat` | number \| null | | | `data[].ipLng` | number \| null | | | `data[].ipTimezone` | string \| null | | | `data[].ipGeoAt` | string \| null | | | `data[].playerSettings` | string \| null | Player settings as a JSON-ENCODED string (not an object). | | `data[].kioskEnabled` | boolean | | | `data[].kioskPinMode` | "workspace" \| "custom" | | | `data[].kioskGraceSeconds` | integer | | | `data[].activeEmergencyId` | string \| null | The live emergency overriding this screen, if any. | | `data[].activeCastId` | string \| null | The live cast overriding this screen, if any. | | `data[].playerVersionHold` | string \| null | | | `data[].sealed` | boolean | | | `data[].sealedAt` | string \| null | | | `data[].powerPolicyId` | string \| null | | | `data[].importSourceId` | string \| null | | | `data[].billingGroupId` | string \| null | | | `data[].customFields` | string \| null | Custom fields as a JSON-ENCODED string. | | `data[].lanSecretAt` | string \| null | When the local-trigger key was last set or rotated. The key itself is never returned. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | | | `data[].location` | object \| null | | | `data[].deviceClaimed` | boolean | Status is `pairing` but a device has claimed it and not yet checked in. | | `data[].nodeName` | string \| null | | | `data[].groupIds` | array of string | Screen groups this screen is in. | | `data[].contentName` | string \| null | | | `data[].contentSharedFrom` | string \| null | Name of the workspace that shared the assigned content in; null when it is this workspace's own. | | `data[].thumbnailUrl` | string \| null | Preview of the assigned content. | | `data[].contentAppKey` | string \| null | | | `data[].contentMediaKind` | string \| null | | | `data[].contentState` | object \| null | Assigned media that is not playable yet (processing, failed, needs_action); null otherwise. | | `data[].contentOrientation` | "portrait" \| "landscape" \| "adaptive" \| null | | | `data[].liveThumbnailAt` | string \| null | Capture time of the latest live frame (GET /v1/screens/{id}/live-thumbnail). | | `data[].liveThumbnailFreshAt` | string \| null | | | `data[].currentContentKind` | "image" \| "video" \| "stream" \| null | | | `data[].currentContentPosterUrl` | string \| null | | | `data[].emergencyHeadline` | string \| null | | | `data[].castHeadline` | string \| null | | | `data[].castStartedAt` | string \| null | | | `data[].castExpiresAt` | string \| null | | | `data[].castContentKind` | string \| null | | | `data[].castContentId` | string \| null | | | `data[].kioskHasCustomPin` | boolean | | | `data[].kioskHasRecovery` | boolean | | | `data[].obscuredSince` | string \| null | A system dialog is covering the screen since this time. | | `data[].pixelHealth` | "ok" \| "frozen" \| "blank" \| null | | | `data[].displayOffSince` | string \| null | | | `data[].displayOffReason` | "standby" \| "wrong-input" \| "disconnected" \| "input-unconfirmed" \| null | | | `data[].expectedDark` | object | | | `data[].expectedDark.dark` | boolean | True when the rules say the panel should be off now. | | `data[].expectedDark.reason` | "schedule-block" \| "power-policy" \| "operating-hours" \| null | | | `data[].expectedDark.nextOpen` | object \| null | | | `data[].expectedDark.minutesSinceOpen` | number \| null | | | `data[].expectedDark.minutesSinceClose` | number \| null | | | `data[].accountHold` | object \| null | | | `data[].outageSummary30d` | object \| null | | | `data[].linkFlaps10m` | integer | Socket link flips in the last ten minutes; present only when > 0 (list and get). | | `data[].state` | object \| null | The device's last reported state (`updatedAt` plus the heartbeat snapshot). The list returns a lean subset; get and PATCH return it all. Null before the first heartbeat. | | `nextCursor` | string \| null | Present only when `limit` was passed; null on the last page. | ```json { "data": [ { "id": "scr_1a2b3c4d5e6f7a8b", "spaceId": "space_1a2b3c4d5e6f7a8b", "nodeId": "node_4c5d6e7f8a9b0c1d", "name": "Lobby", "status": "online", "lastSeenAt": "2026-09-28T11:58:00.000Z", "coreUpdateOfferedAt": null, "contentKind": "playlist", "contentId": "pl_9a8b7c6d5e4f3a2b", "contentFit": null, "deactivatedAt": null, "awaitingPaymentAt": null, "tags": [ "lobby" ], "rotation": 0, "rotationCommandedAt": null, "timezone": "Europe/London", "timezoneSource": "operator", "operatingHours": "default", "lastPanelCommand": null, "scheduleScreensOff": false, "displayPowerMode": "always-on", "playbackMode": "unsync", "locationLabel": null, "locationLat": null, "locationLng": null, "ipCity": "London", "ipRegion": "England", "ipCountry": "GB", "ipLat": 51.5, "ipLng": -0.12, "ipTimezone": "Europe/London", "ipGeoAt": "2026-09-01T09:00:00.000Z", "playerSettings": null, "kioskEnabled": false, "kioskPinMode": "workspace", "kioskGraceSeconds": 30, "activeEmergencyId": null, "activeCastId": null, "playerVersionHold": null, "sealed": false, "sealedAt": null, "powerPolicyId": null, "importSourceId": null, "billingGroupId": null, "customFields": null, "lanSecretAt": null, "createdAt": "2026-09-01T09:00:00.000Z", "updatedAt": "2026-09-28T11:58:00.000Z", "deletedAt": null, "location": null, "deviceClaimed": false, "nodeName": "Head office", "groupIds": [], "contentName": "Lobby loop", "contentSharedFrom": null, "thumbnailUrl": null, "contentAppKey": null, "contentMediaKind": null, "contentState": null, "contentOrientation": "landscape", "liveThumbnailAt": "2026-09-28T11:45:00.000Z", "liveThumbnailFreshAt": "2026-09-28T11:57:00.000Z", "currentContentKind": "image", "currentContentPosterUrl": null, "emergencyHeadline": null, "castHeadline": null, "castStartedAt": null, "castExpiresAt": null, "castContentKind": null, "castContentId": null, "kioskHasCustomPin": false, "kioskHasRecovery": false, "obscuredSince": null, "pixelHealth": "ok", "displayOffSince": null, "displayOffReason": null, "expectedDark": { "dark": false, "reason": null, "nextOpen": null, "minutesSinceOpen": null, "minutesSinceClose": null }, "accountHold": null, "outageSummary30d": null, "state": { "updatedAt": "2026-09-28T11:58:00.000Z", "connection": "online", "currentContent": { "kind": "playlist", "id": "pl_9a8b7c6d5e4f3a2b" } } } ] } ``` 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/screens Create a screen. `name` is required; `nodeId`, `location`, and `tags` are optional. This operation is safe to retry with an idempotency key. Each screen created increases your billed screen count, so this request is refused if your account is suspended or cancelled. **Notes.** - Returns the stored row, not the composed Screen that GET /v1/screens/{id} returns: `tags` is the JSON-encoded string, and the composed fields (`contentName`, `state`, …) are absent. - The screen waits in `pairing` status until a device claims it (POST /v1/screens/{id}/claim-replacement) — or use POST /v1/screens/claim or /v1/screens/enroll, which create and pair in one step. Auth: Bearer token. Permission: `screen.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `nodeId` | string | no | Location to create it in; default: the API key's own location, else the workspace root. | | `billingGroupId` | string \| null | no | Billing group that pays for the screen. | | `payment` | "later" | no | Answer to `plan_full`: create the screen waiting for payment. It starts to play when the plan has room. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ScreenRow | A screen as stored, before composition. | | `data.id` | string | Screen id. | | `data.spaceId` | string | Workspace id. | | `data.nodeId` | string \| null | Location (org node) the screen belongs to; null = workspace root. | | `data.name` | string | | | `data.status` | "online" \| "offline" \| "pairing" | `pairing` = no device has checked in yet. | | `data.lastSeenAt` | string \| null | Last heartbeat or socket ping reply, whichever is later. | | `data.coreUpdateOfferedAt` | string \| null | | | `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | What is assigned. Null = nothing assigned. | | `data.contentId` | string \| null | | | `data.contentFit` | null | Retired; always null. Fit is set on the content. | | `data.deactivatedAt` | string \| null | Set while an operator has deactivated the screen. | | `data.awaitingPaymentAt` | string \| null | Set while the screen waits for payment: it was paired past the screens on the plan. It starts to play when the plan has room. | | `data.rotation` | integer | 0, 90, 180 or 270 degrees. | | `data.rotationCommandedAt` | string \| null | | | `data.timezone` | string \| null | IANA time zone; null = inherited. | | `data.timezoneSource` | "operator" \| "device" \| null | | | `data.operatingHours` | string | `default`, or a JSON-encoded weekly window. | | `data.lastPanelCommand` | string \| null | | | `data.scheduleScreensOff` | boolean | | | `data.displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | | | `data.playbackMode` | "sync" \| "unsync" \| "device-time" | | | `data.locationLabel` | string \| null | | | `data.locationLat` | number \| null | | | `data.locationLng` | number \| null | | | `data.ipCity` | string \| null | | | `data.ipRegion` | string \| null | | | `data.ipCountry` | string \| null | | | `data.ipLat` | number \| null | | | `data.ipLng` | number \| null | | | `data.ipTimezone` | string \| null | | | `data.ipGeoAt` | string \| null | | | `data.playerSettings` | string \| null | Player settings as a JSON-ENCODED string (not an object). | | `data.kioskEnabled` | boolean | | | `data.kioskPinMode` | "workspace" \| "custom" | | | `data.kioskGraceSeconds` | integer | | | `data.activeEmergencyId` | string \| null | The live emergency overriding this screen, if any. | | `data.activeCastId` | string \| null | The live cast overriding this screen, if any. | | `data.playerVersionHold` | string \| null | | | `data.sealed` | boolean | | | `data.sealedAt` | string \| null | | | `data.powerPolicyId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.billingGroupId` | string \| null | | | `data.customFields` | string \| null | Custom fields as a JSON-ENCODED string. | | `data.lanSecretAt` | string \| null | When the local-trigger key was last set or rotated. The key itself is never returned. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.tags` | string | Tags as a JSON-ENCODED array string (the stored column), not an array. | Response 401: Missing, expired or revoked bearer token. Response 402: `plan_full`: every screen on the plan is in use. The body has `data.plan` with the price of one more screen today. Add screens to the plan, or send `payment: "later"`. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: The location does not exist. Response 409: The account is suspended or cancelled. Response 422: `name` is missing. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id} Get a screen Get one screen, with the same detail included in the screen list. A screen outside your organization scope returns a not-found error rather than a permission error. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Screen | A screen, composed with its content, live state and health facts. | | `data.id` | string | Screen id. | | `data.spaceId` | string | Workspace id. | | `data.nodeId` | string \| null | Location (org node) the screen belongs to; null = workspace root. | | `data.name` | string | | | `data.status` | "online" \| "offline" \| "pairing" | `pairing` = no device has checked in yet. | | `data.lastSeenAt` | string \| null | Last heartbeat or socket ping reply, whichever is later. | | `data.coreUpdateOfferedAt` | string \| null | | | `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | What is assigned. Null = nothing assigned. | | `data.contentId` | string \| null | | | `data.contentFit` | null | Retired; always null. Fit is set on the content. | | `data.deactivatedAt` | string \| null | Set while an operator has deactivated the screen. | | `data.awaitingPaymentAt` | string \| null | Set while the screen waits for payment: it was paired past the screens on the plan. It starts to play when the plan has room. | | `data.tags` | array of string | | | `data.rotation` | integer | 0, 90, 180 or 270 degrees. | | `data.rotationCommandedAt` | string \| null | | | `data.timezone` | string \| null | IANA time zone; null = inherited. | | `data.timezoneSource` | "operator" \| "device" \| null | | | `data.operatingHours` | string | `default`, or a JSON-encoded weekly window. | | `data.lastPanelCommand` | string \| null | | | `data.scheduleScreensOff` | boolean | | | `data.displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | | | `data.playbackMode` | "sync" \| "unsync" \| "device-time" | | | `data.locationLabel` | string \| null | | | `data.locationLat` | number \| null | | | `data.locationLng` | number \| null | | | `data.ipCity` | string \| null | | | `data.ipRegion` | string \| null | | | `data.ipCountry` | string \| null | | | `data.ipLat` | number \| null | | | `data.ipLng` | number \| null | | | `data.ipTimezone` | string \| null | | | `data.ipGeoAt` | string \| null | | | `data.playerSettings` | string \| null | Player settings as a JSON-ENCODED string (not an object). | | `data.kioskEnabled` | boolean | | | `data.kioskPinMode` | "workspace" \| "custom" | | | `data.kioskGraceSeconds` | integer | | | `data.activeEmergencyId` | string \| null | The live emergency overriding this screen, if any. | | `data.activeCastId` | string \| null | The live cast overriding this screen, if any. | | `data.playerVersionHold` | string \| null | | | `data.sealed` | boolean | | | `data.sealedAt` | string \| null | | | `data.powerPolicyId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.billingGroupId` | string \| null | | | `data.customFields` | string \| null | Custom fields as a JSON-ENCODED string. | | `data.lanSecretAt` | string \| null | When the local-trigger key was last set or rotated. The key itself is never returned. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.location` | object \| null | | | `data.deviceClaimed` | boolean | Status is `pairing` but a device has claimed it and not yet checked in. | | `data.nodeName` | string \| null | | | `data.groupIds` | array of string | Screen groups this screen is in. | | `data.contentName` | string \| null | | | `data.contentSharedFrom` | string \| null | Name of the workspace that shared the assigned content in; null when it is this workspace's own. | | `data.thumbnailUrl` | string \| null | Preview of the assigned content. | | `data.contentAppKey` | string \| null | | | `data.contentMediaKind` | string \| null | | | `data.contentState` | object \| null | Assigned media that is not playable yet (processing, failed, needs_action); null otherwise. | | `data.contentOrientation` | "portrait" \| "landscape" \| "adaptive" \| null | | | `data.liveThumbnailAt` | string \| null | Capture time of the latest live frame (GET /v1/screens/{id}/live-thumbnail). | | `data.liveThumbnailFreshAt` | string \| null | | | `data.currentContentKind` | "image" \| "video" \| "stream" \| null | | | `data.currentContentPosterUrl` | string \| null | | | `data.emergencyHeadline` | string \| null | | | `data.castHeadline` | string \| null | | | `data.castStartedAt` | string \| null | | | `data.castExpiresAt` | string \| null | | | `data.castContentKind` | string \| null | | | `data.castContentId` | string \| null | | | `data.kioskHasCustomPin` | boolean | | | `data.kioskHasRecovery` | boolean | | | `data.obscuredSince` | string \| null | A system dialog is covering the screen since this time. | | `data.pixelHealth` | "ok" \| "frozen" \| "blank" \| null | | | `data.displayOffSince` | string \| null | | | `data.displayOffReason` | "standby" \| "wrong-input" \| "disconnected" \| "input-unconfirmed" \| null | | | `data.expectedDark` | object | | | `data.expectedDark.dark` | boolean | True when the rules say the panel should be off now. | | `data.expectedDark.reason` | "schedule-block" \| "power-policy" \| "operating-hours" \| null | | | `data.expectedDark.nextOpen` | object \| null | | | `data.expectedDark.minutesSinceOpen` | number \| null | | | `data.expectedDark.minutesSinceClose` | number \| null | | | `data.accountHold` | object \| null | | | `data.outageSummary30d` | object \| null | | | `data.linkFlaps10m` | integer | Socket link flips in the last ten minutes; present only when > 0 (list and get). | | `data.state` | object \| null | The device's last reported state (`updatedAt` plus the heartbeat snapshot). The list returns a lean subset; get and PATCH return it all. Null before the first heartbeat. | 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 screen in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/screens/{id} Update a screen's settings Update a screen's own fields, including name, location, tags, orientation, organization node, and player settings. This endpoint does not assign content; use POST /v1/screens/:id/assign to change what a screen plays. Partial update. To change what a screen plays use POST /v1/screens/{id}/assign — this route refuses `contentKind`/`contentId` with a 400. **Notes.** - The PATCH response does not merge the live socket facts (`linkFlaps10m`, a socket-fresh `lastSeenAt`) that GET adds. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `nodeId` | string \| null | no | Move to another location (you need screen.edit there too). | | `billingGroupId` | string \| null | no | Needs billing.edit. | | `status` | "online" \| "offline" \| "pairing" | no | | | `tags` | array of string | no | | | `rotation` | 0 \| 90 \| 180 \| 270 | no | | | `timezone` | string \| null | no | IANA time zone; null to inherit. | | `operatingHours` | string | no | | | `displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | no | | | `powerPolicyId` | string \| null | no | | | `playbackMode` | "sync" \| "unsync" \| "device-time" | no | | | `location` | object \| null | no | | | `deactivated` | boolean | no | True deactivates the screen (nothing plays); false reactivates it. | | `playerVersionHold` | boolean \| string \| null | no | | | `playerSettings` | object \| null | no | Merged into the current settings; null resets them. | | `customFields` | object \| null | no | | | `kioskPinMode` | "workspace" \| "custom" | no | | | `kioskGraceSeconds` | number | no | | | `kioskPin` | string \| null | no | 4-8 digits; null clears the custom PIN. | | `kioskEnabled` | boolean | no | | ```bash curl -X PATCH "https://api.brixsignage.com/v1/screens/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | Screen | A screen, composed with its content, live state and health facts. | | `data.id` | string | Screen id. | | `data.spaceId` | string | Workspace id. | | `data.nodeId` | string \| null | Location (org node) the screen belongs to; null = workspace root. | | `data.name` | string | | | `data.status` | "online" \| "offline" \| "pairing" | `pairing` = no device has checked in yet. | | `data.lastSeenAt` | string \| null | Last heartbeat or socket ping reply, whichever is later. | | `data.coreUpdateOfferedAt` | string \| null | | | `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | What is assigned. Null = nothing assigned. | | `data.contentId` | string \| null | | | `data.contentFit` | null | Retired; always null. Fit is set on the content. | | `data.deactivatedAt` | string \| null | Set while an operator has deactivated the screen. | | `data.awaitingPaymentAt` | string \| null | Set while the screen waits for payment: it was paired past the screens on the plan. It starts to play when the plan has room. | | `data.tags` | array of string | | | `data.rotation` | integer | 0, 90, 180 or 270 degrees. | | `data.rotationCommandedAt` | string \| null | | | `data.timezone` | string \| null | IANA time zone; null = inherited. | | `data.timezoneSource` | "operator" \| "device" \| null | | | `data.operatingHours` | string | `default`, or a JSON-encoded weekly window. | | `data.lastPanelCommand` | string \| null | | | `data.scheduleScreensOff` | boolean | | | `data.displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | | | `data.playbackMode` | "sync" \| "unsync" \| "device-time" | | | `data.locationLabel` | string \| null | | | `data.locationLat` | number \| null | | | `data.locationLng` | number \| null | | | `data.ipCity` | string \| null | | | `data.ipRegion` | string \| null | | | `data.ipCountry` | string \| null | | | `data.ipLat` | number \| null | | | `data.ipLng` | number \| null | | | `data.ipTimezone` | string \| null | | | `data.ipGeoAt` | string \| null | | | `data.playerSettings` | string \| null | Player settings as a JSON-ENCODED string (not an object). | | `data.kioskEnabled` | boolean | | | `data.kioskPinMode` | "workspace" \| "custom" | | | `data.kioskGraceSeconds` | integer | | | `data.activeEmergencyId` | string \| null | The live emergency overriding this screen, if any. | | `data.activeCastId` | string \| null | The live cast overriding this screen, if any. | | `data.playerVersionHold` | string \| null | | | `data.sealed` | boolean | | | `data.sealedAt` | string \| null | | | `data.powerPolicyId` | string \| null | | | `data.importSourceId` | string \| null | | | `data.billingGroupId` | string \| null | | | `data.customFields` | string \| null | Custom fields as a JSON-ENCODED string. | | `data.lanSecretAt` | string \| null | When the local-trigger key was last set or rotated. The key itself is never returned. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | | | `data.location` | object \| null | | | `data.deviceClaimed` | boolean | Status is `pairing` but a device has claimed it and not yet checked in. | | `data.nodeName` | string \| null | | | `data.groupIds` | array of string | Screen groups this screen is in. | | `data.contentName` | string \| null | | | `data.contentSharedFrom` | string \| null | Name of the workspace that shared the assigned content in; null when it is this workspace's own. | | `data.thumbnailUrl` | string \| null | Preview of the assigned content. | | `data.contentAppKey` | string \| null | | | `data.contentMediaKind` | string \| null | | | `data.contentState` | object \| null | Assigned media that is not playable yet (processing, failed, needs_action); null otherwise. | | `data.contentOrientation` | "portrait" \| "landscape" \| "adaptive" \| null | | | `data.liveThumbnailAt` | string \| null | Capture time of the latest live frame (GET /v1/screens/{id}/live-thumbnail). | | `data.liveThumbnailFreshAt` | string \| null | | | `data.currentContentKind` | "image" \| "video" \| "stream" \| null | | | `data.currentContentPosterUrl` | string \| null | | | `data.emergencyHeadline` | string \| null | | | `data.castHeadline` | string \| null | | | `data.castStartedAt` | string \| null | | | `data.castExpiresAt` | string \| null | | | `data.castContentKind` | string \| null | | | `data.castContentId` | string \| null | | | `data.kioskHasCustomPin` | boolean | | | `data.kioskHasRecovery` | boolean | | | `data.obscuredSince` | string \| null | A system dialog is covering the screen since this time. | | `data.pixelHealth` | "ok" \| "frozen" \| "blank" \| null | | | `data.displayOffSince` | string \| null | | | `data.displayOffReason` | "standby" \| "wrong-input" \| "disconnected" \| "input-unconfirmed" \| null | | | `data.expectedDark` | object | | | `data.expectedDark.dark` | boolean | True when the rules say the panel should be off now. | | `data.expectedDark.reason` | "schedule-block" \| "power-policy" \| "operating-hours" \| null | | | `data.expectedDark.nextOpen` | object \| null | | | `data.expectedDark.minutesSinceOpen` | number \| null | | | `data.expectedDark.minutesSinceClose` | number \| null | | | `data.accountHold` | object \| null | | | `data.outageSummary30d` | object \| null | | | `data.linkFlaps10m` | integer | Socket link flips in the last ten minutes; present only when > 0 (list and get). | | `data.state` | object \| null | The device's last reported state (`updatedAt` plus the heartbeat snapshot). The list returns a lean subset; get and PATCH return it all. Null before the first heartbeat. | Response 400: The body tried to set content (use POST /v1/screens/{id}/assign). 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 screen (or destination location/billing group) in this workspace. Response 422: Invalid status, rotation, time zone or PIN. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Screens (part 2 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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. | ### DELETE /v1/screens/{id} Delete a screen. It moves to the 30-day recovery window, and its paired device is unpaired so the player shows its pairing screen. An optional `reason` field is recorded in the activity log. Soft-deletes the screen to the recycle bin (restorable for 30 days) and releases its device, which returns to the pairing screen. Auth: Bearer token. Permission: `screen.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/screens/{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 screen in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/assign Set what a screen plays Assign content to a screen using `contentKind` and `contentId`. Pass `null` to clear the current assignment. The content is validated to confirm it exists, can be used at the screen's organization node, and has no unfilled layout zones, before the screen is updated to play it. Assigns content to one screen (null clears it). The screen is told to reload immediately. Auth: Bearer token. Permission: `screen.cast`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | yes | What to assign; null clears the assignment. | | `contentId` | string | no | Required unless `contentKind` is null. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/assign" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contentKind":"playlist","contentId":"pl_9a8b7c6d5e4f3a2b"}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" \| null | | | `data.contentId` | string \| null | | ```json { "data": { "id": "scr_1a2b3c4d5e6f7a8b", "contentKind": "playlist", "contentId": "pl_9a8b7c6d5e4f3a2b" } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: `not_shared`: the content is not shared to this screen's location. Response 404: No such screen or content in this workspace. Response 422: Invalid kind, a layout with unbound zones, or content that cannot play (empty playlist, unprocessed media). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/claim-replacement Replace a screen's device Bind a new device, identified by the 6-digit pairing code it is displaying, to an existing screen. The screen keeps its identity, assigned content, and history. This endpoint is rate-limited because the pairing code is a small, guessable value. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | string | yes | The 6-digit code the new device shows. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/claim-replacement" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.paired` | 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 screen with this id, or no device shows that code. Response 409: `ambiguous_code` (two devices show it) or `already_claimed`. Response 410: The code has expired. Response 422: `code` is missing. Response 429: Too many wrong codes; wait and try again. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/commands Send a command to a screen Queue a command for a screen's device, such as reboot, turning the display on or off, taking a screenshot, or clearing the cache. The device runs the command the next time it checks in. Queues a device command (reboot, refresh, screenshot, volume, …). Poll GET /v1/screens/{id}/commands/{commandId} for the device's answer. **Notes.** - A `screenshot` that coalesces onto an older pending one answers 200 (not 201) with `coalesced: true`. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | | | `payload` | object | no | Per-kind payload: `set-volume` {level 0-100}, `set-brightness` {level}, `set-mute` {muted}, `set-input` {input}, … Most kinds take none. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/commands" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Command id. | | `data.kind` | string | | | `data.status` | "pending" | | | `data.coalesced` | boolean | True when a stale pending screenshot command was reused instead. | 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 screen in this workspace. Response 409: `wifi_already_saved`: an `add-wifi` or `set-fallback-wifi` names a network the screen already has saved. A wrong password for a saved network takes the screen offline, so only new networks are sent. Response 422: Unknown kind or invalid payload. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/commands/{commandId} Get a command's status Get the outcome of one previously queued device command, including its status (acknowledged, failed, or pending) and any note reported by the device. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `commandId` | path | string | yes | Command id from POST /v1/screens/{id}/commands. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/commands/{commandId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.kind` | string | The command kind (see POST /v1/screens/{id}/commands). | | `data.status` | "pending" \| "delivered" \| "acked" \| "failed" \| "unconfirmed" \| "held" | | | `data.result` | string \| null | | | `data.issuedAt` | string | ISO-8601 timestamp (UTC). | | `data.deliveredAt` | string \| null | | | `data.ackedAt` | 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 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/diagnose Diagnose a screen issue Get a likely-cause troubleshooting verdict for a screen, based on signals such as online or offline status, what is actually rendering, resource pressure, and early hardware warnings. The response also includes a guided checklist for checking the TV, input, and cable, which the screen itself cannot detect. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/diagnose" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ScreenDiagnosis | Why a screen is (or is not) showing what it should. | | `data.layer` | "offline" \| "deactivated" \| "unassigned" \| "stick" \| "resource" \| "display" \| "downstream" \| "healthy" | The first layer that explains the problem, checked from the device outward. | | `data.severity` | "none" \| "info" \| "warning" \| "critical" | | | `data.likelyCause` | string | One sentence an operator can act on. | | `data.detail` | string \| null | | | `data.fault` | "platform" \| "user" \| "environment" \| null | Whose problem it is; null when healthy. | | `data.guided` | boolean | True when `checklist` is a guided fix. | | `data.checklist` | array of object | | | `data.checklist[].code` | string | | | `data.checklist[].label` | string | | | `data.checklist[].detail` | string | | | `data.remedies` | array of object | One-click fixes, when one applies. | | `data.remedies[].kind` | "reboot" \| "wake-screen" \| "restart-app" | The command to send with POST /v1/screens/{id}/commands. | | `data.remedies[].label` | string | | | `data.remedies[].cost` | string | What the remedy interrupts, in words. | | `data.remedies[].confirm` | boolean | | | `data.prominent` | boolean | True when the console shows this as a banner. | 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/screens/{id}/diagnostic-bundles List a screen's diagnostic bundles List the detailed diagnostic bundles a screen has uploaded, such as system logs, thread dumps, and exit reasons, newest first. This returns only the index; download an individual bundle separately. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/diagnostic-bundles" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].reason` | string | | | `data[].sections` | array of string | | | `data[].bytes` | integer | | | `data[].downloadable` | boolean | False when the bundle was recorded but not stored. | | `data[].viewable` | boolean | True when `?view=1` on the download route answers for this workspace (the in-CMS reader is on). | | `data[].playerVersion` | string \| null | | | `data[].platform` | string \| null | | | `data[].clockSkewMs` | number \| null | | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/diagnostic-bundles/{bundleId} Download a diagnostic bundle Download one detailed diagnostic bundle as JSON, exactly as it was uploaded by the device. **Notes.** - The body is the stored bundle (v2: `summary`, `gaps` = missing parts with the reason, `parts`), served as an attachment. Bundles are kept 30 days. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `bundleId` | path | string | yes | Bundle id. | | `view` | query | string | no | `1` returns the bundle inside the `{ data }` envelope instead of as a file (only where `viewable` is true). | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/diagnostic-bundles/{bundleId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 bundle, or it was not stored. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/diagnostics Get consolidated screen diagnostics Get a consolidated diagnostic report for a screen: the likely-cause verdict from GET /v1/screens/:id/diagnose plus the underlying signals, including open alerts, recent health trends, crashes and self-heals, a recent log tail, and the latest reported state. Pass `format=text` for a plain-text report, or omit it for structured JSON. **Notes.** - `?format=text` returns the same report as plain text (text/plain) instead of JSON. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/diagnostics" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.screen` | object | | | `data.screen.id` | string | | | `data.screen.name` | string | | | `data.screen.status` | "online" \| "offline" \| "pairing" | | | `data.screen.lastSeenAt` | string \| null | | | `data.diagnosis` | ScreenDiagnosis | Why a screen is (or is not) showing what it should. | | `data.diagnosis.layer` | "offline" \| "deactivated" \| "unassigned" \| "stick" \| "resource" \| "display" \| "downstream" \| "healthy" | The first layer that explains the problem, checked from the device outward. | | `data.diagnosis.severity` | "none" \| "info" \| "warning" \| "critical" | | | `data.diagnosis.likelyCause` | string | One sentence an operator can act on. | | `data.diagnosis.detail` | string \| null | | | `data.diagnosis.fault` | "platform" \| "user" \| "environment" \| null | Whose problem it is; null when healthy. | | `data.diagnosis.guided` | boolean | True when `checklist` is a guided fix. | | `data.diagnosis.checklist` | array of object | | | `data.diagnosis.checklist[].code` | string | | | `data.diagnosis.checklist[].label` | string | | | `data.diagnosis.checklist[].detail` | string | | | `data.diagnosis.remedies` | array of object | One-click fixes, when one applies. | | `data.diagnosis.remedies[].kind` | "reboot" \| "wake-screen" \| "restart-app" | The command to send with POST /v1/screens/{id}/commands. | | `data.diagnosis.remedies[].label` | string | | | `data.diagnosis.remedies[].cost` | string | What the remedy interrupts, in words. | | `data.diagnosis.remedies[].confirm` | boolean | | | `data.diagnosis.prominent` | boolean | True when the console shows this as a banner. | | `data.alerts` | array of object | Open alerts on this screen. | | `data.alerts[].code` | string | | | `data.alerts[].severity` | string | | | `data.alerts[].message` | string | | | `data.alerts[].openedAt` | string | ISO-8601 timestamp (UTC). | | `data.vitals` | array of object | Recent device vitals, newest first. | | `data.vitals[].id` | string | | | `data.vitals[].spaceId` | string | | | `data.vitals[].screenId` | string | | | `data.vitals[].storageFreeMb` | number \| null | | | `data.vitals[].storageTotalMb` | number \| null | | | `data.vitals[].memoryFreeMb` | number \| null | | | `data.vitals[].memoryTotalMb` | number \| null | | | `data.vitals[].heapUsedMb` | number \| null | | | `data.vitals[].heapLimitMb` | number \| null | | | `data.vitals[].networkLossRatio` | number \| null | | | `data.vitals[].networkRttMs` | number \| null | | | `data.vitals[].thermalStatus` | string \| null | | | `data.vitals[].reloadCount` | integer \| null | | | `data.vitals[].rebootCount` | integer \| null | | | `data.vitals[].uptimeSec` | number \| null | | | `data.vitals[].fps` | number \| null | | | `data.vitals[].videoDropPct` | number \| null | | | `data.vitals[].webViewKillCount` | integer \| null | | | `data.vitals[].renderFreezeCount` | integer \| null | | | `data.vitals[].maxRenderFreezeMs` | number \| null | | | `data.vitals[].childFreezeCount` | integer \| null | | | `data.vitals[].cpuTempC` | number \| null | | | `data.vitals[].gpuTempC` | number \| null | | | `data.vitals[].maxTempC` | number \| null | Hottest reading since the previous heartbeat (°C). | | `data.vitals[].starvedAdvanceCount` | integer \| null | | | `data.vitals[].longTasks` | integer \| null | | | `data.vitals[].videoSeamWorstMs` | number \| null | | | `data.vitals[].videoHoleMaxMs` | number \| null | | | `data.vitals[].videoStartMaxMs` | number \| null | Slowest video start since the previous heartbeat: play() to the first moving frame (ms). | | `data.vitals[].videoCallbackStallMs` | number \| null | Longest late frame callback while frames were still shown (ms) — a busy player, not a blank screen. | | `data.vitals[].videoMidStallMaxMs` | number \| null | Longest run since the previous heartbeat in which a playing clip's picture stood still (≥300 ms, ms; migration 0306). | | `data.vitals[].decodeErrors` | integer \| null | | | `data.vitals[].zonesSuppressed` | integer \| null | | | `data.vitals[].videoBudgetHits` | integer \| null | | | `data.vitals[].hdmiConnected` | integer \| null | 1 = an HDMI sink answers, 0 = none, null = unknown. | | `data.vitals[].frameGapCount` | integer \| null | | | `data.vitals[].frameGapMaxMs` | number \| null | | | `data.vitals[].anrCount` | integer \| null | | | `data.vitals[].memoryDegradeStep` | integer \| null | | | `data.vitals[].decoderInitFailures` | integer \| null | | | `data.vitals[].cacheWipeCount` | integer \| null | | | `data.vitals[].liveVideoEls` | integer \| null | | | `data.vitals[].liveIframes` | integer \| null | | | `data.vitals[].maxLiveVideoEls` | integer \| null | | | `data.vitals[].liveDecoders` | integer \| null | Videos holding a hardware decoder at heartbeat time (migration 0306). | | `data.vitals[].decoderBudget` | integer \| null | Video decoders the player allowed itself at heartbeat time (RAM band, memory ladder, heat, override). Null = no limit or an older player (migration 0325). | | `data.vitals[].decoderBudgetAgeSec` | integer \| null | Seconds that decoder budget had been in force (migration 0325). | | `data.vitals[].decoderOverrideFellBackFrom` | integer \| null | The videoDecoderMax override the screen gave up because its extra decoder would not start (migration 0325). | | `data.vitals[].launchReason` | string \| null | | | `data.vitals[].launchAt` | number \| null | When this player run started (epoch ms). | | `data.vitals[].coreVersion` | string \| null | The player core version that sent this sample (migration 0305). | | `data.vitals[].occurredAt` | string | ISO-8601 timestamp (UTC). | | `data.crashes` | array of object | | | `data.crashes[].reason` | string | | | `data.crashes[].reportedAt` | string | ISO-8601 timestamp (UTC). | | `data.logs` | array of object | | | `data.logs[].entries` | any | The uploaded log lines (decoded JSON). | | `data.logs[].reason` | string | | | `data.logs[].errorCount` | integer | | | `data.logs[].warnCount` | integer | | | `data.logs[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data.state` | object \| null | The last heartbeat snapshot; null before the first heartbeat. | | `data.generatedAt` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/display-history Get a screen's display history Get the history of what the physical display itself did, such as being switched off, switched to another HDMI input, losing its HDMI connection, or coming back, separate from whether the player software was online. Entries are newest first, each showing how long the previous state lasted, along with the current state. This data is only available for displays that support CEC, and history is limited to the last 14 days. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `days` | query | string | no | Window in days; default and maximum: the telemetry retention. | | `limit` | query | string | no | Most changes to list (default 50, max 500). | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/display-history" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.screenId` | string | | | `data.windowDays` | integer | | | `data.retentionDays` | integer | | | `data.current` | object \| null | What the panel is doing now; null when the device cannot read the panel. | | `data.changes` | array of object | | | `data.changes[].id` | string | | | `data.changes[].at` | string | ISO-8601 timestamp (UTC). | | `data.changes[].from` | "standby" \| "wrong-input" \| "disconnected" \| "input-unconfirmed" \| "lit" | | | `data.changes[].to` | "standby" \| "wrong-input" \| "disconnected" \| "input-unconfirmed" \| "lit" | | | `data.changes[].forSec` | number \| null | | | `data.changes[].basis` | "probe" \| "seen-switch" \| "stored-guess" | What the TV input reading stood on: a probe the player ran, an input change it saw, or its last stored value. | | `data.changes[].basisLabel` | string | `basis` in plain words. | | `data.truncated` | boolean | | | `data.dailySummaries` | array of string | The device's daily TV input summaries in the window, newest first, one line each. | 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/screens/{id}/frames Get a screen's frame history Get a log of visual fingerprints captured from a screen over a time range, using the `since` and `until` query parameters. This log is a visual audit trail and is kept even after the screen is deleted. **Notes.** - The newest 500 frames in the window. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `since` | query | string | no | ISO timestamp; only frames at or after it. | | `until` | query | string | no | ISO timestamp; only frames at or before it. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/frames" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].hash` | string | Perceptual hash of the frame on the glass. | | `data[].contentKind` | string \| null | | | `data[].contentId` | string \| null | | | `data[].capturedAt` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/kiosk-recovery/reveal Reveal a screen's recovery code Reveal the offline recovery code for a screen with Screen Lock enabled. This action is recorded in the activity log. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/kiosk-recovery/reveal" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.code` | string | The Screen Lock recovery code. Each reveal is recorded in the audit log. | 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 screen with this id, or it has no recovery code. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/kiosk-recovery/rotate Rotate a screen's recovery code Generate a new offline recovery code for a screen with Screen Lock enabled. The previous code stops working immediately. This action is recorded in the activity log. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/kiosk-recovery/rotate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.code` | string | The new Screen Lock recovery code. | 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/screens/{id}/lan-secret/rotate Rotate a screen's local network key Replace the key used to authenticate local-network requests to this screen. The new key is not returned in the response; only the device receives it. Any third-party integration that signs its own requests to the screen must be updated with the new key. **Notes.** - The key itself is never returned; the device collects it. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/lan-secret/rotate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.rotatedAt` | string | ISO-8601 timestamp (UTC). | 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 screen with this id, or Local trigger is off for it. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/live-thumbnail Get a screen's live thumbnail Get the most recently captured still image for a screen, returned as image bytes. This accepts standard API authentication, including an API key, or a short-lived `asset` query parameter token so the image can be loaded directly in an image tag. A screen outside your access scope returns a not-found error rather than a permission error. **Notes.** - The response header `x-captured-at` carries the capture time. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `at` | query | string | no | `capturedAt` of a specific capture; default the newest. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/live-thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 screen with this id, or it has no capture yet (`no_screenshot`). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/logs Get a screen's activity log Get a combined, newest-first feed of a screen's recent activity from the last 24 hours, including telemetry events, crash reports, command acknowledgements, and screenshot uploads. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/logs" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.lines` | array of object | Newest first, at most 200. | | `data.lines[].at` | string | ISO-8601 timestamp (UTC). | | `data.lines[].level` | "error" \| "info" \| "warn" | | | `data.lines[].text` | string | | | `data.windowHours` | integer | | 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/screens/{id}/mirror Start a screen mirror session Start a live mirroring session for a screen. The response includes a signaling URL that a viewer connects to over WebRTC; the screen's device connects when it receives the corresponding command. End the session with POST /v1/mirror/:sessionId/end. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/mirror" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.sessionId` | string | | | `data.signalingUrl` | string | | | `data.signalingToken` | string | Viewer token for `signalingUrl`; valid for 5 minutes, for this session only. | | `data.turnHint` | string | | 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. ## Screens (part 3 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/screens/{id}/outages Get a screen's outage history Get the outage history for a screen over the last N days (default 30, capped at the retention window). Each outage includes when it happened, how long it lasted, a plain-language cause such as a Wi-Fi drop or a power cut, and supporting evidence, along with a summary sentence such as "went down 6 times in the last 30 days, all Wi-Fi drops". Planned downtime is listed but excluded from the outage count. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `days` | query | string | no | Window in days (default 30), capped at the workspace's retention. | | `limit` | query | string | no | Most outages to list (default 50). | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/outages" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.screenId` | string | | | `data.windowDays` | integer | | | `data.retentionDays` | integer | | | `data.summary` | OutageSummary | Outages in a window, by cause. | | `data.summary.windowDays` | integer | | | `data.summary.count` | integer | Unplanned outages in the window. | | `data.summary.byCause` | object | Outage count per cause; a cause with none is absent. | | `data.summary.byCause.power-loss` | integer | | | `data.summary.byCause.powered-off` | integer | | | `data.summary.byCause.os-reboot` | integer | | | `data.summary.byCause.app-crash` | integer | | | `data.summary.byCause.app-killed-low-memory` | integer | | | `data.summary.byCause.app-anr` | integer | | | `data.summary.byCause.app-restart` | integer | | | `data.summary.byCause.wifi-dropped` | integer | | | `data.summary.byCause.wifi-weak` | integer | | | `data.summary.byCause.wifi-no-internet` | integer | | | `data.summary.byCause.ethernet-dropped` | integer | | | `data.summary.byCause.brix-unreachable` | integer | | | `data.summary.byCause.display-off` | integer | | | `data.summary.byCause.sleep` | integer | | | `data.summary.byCause.scheduled-off` | integer | | | `data.summary.byCause.unknown` | integer | | | `data.summary.byCause.power-cycle` | integer | | | `data.summary.byCause.network-only` | integer | | | `data.summary.byBucket` | object | | | `data.summary.byBucket.app` | integer | | | `data.summary.byBucket.display` | integer | | | `data.summary.byBucket.unknown` | integer | | | `data.summary.byBucket.network` | integer | | | `data.summary.byBucket.power` | integer | | | `data.summary.byBucket.brix` | integer | | | `data.summary.byBucket.planned` | integer | | | `data.summary.topCause` | string \| null | | | `data.summary.topCauseShare` | number | | | `data.summary.hedgedShare` | number | | | `data.summary.lastCause` | object \| null | | | `data.summary.lastAt` | string \| null | | | `data.summary.lastKnownCause` | object \| null | | | `data.summary.avgRssiDbm` | number \| null | | | `data.summary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` | | `data.outages` | array of object | | | `data.outages[].id` | string | | | `data.outages[].from` | string | ISO-8601 timestamp (UTC). | | `data.outages[].to` | string \| null | Null while the screen is still down. | | `data.outages[].durationSec` | integer \| null | | | `data.outages[].open` | boolean | | | `data.outages[].detectionPath` | string | | | `data.outages[].cause` | object \| null | | | `data.outages[].label` | string \| null | | | `data.outages[].sentence` | string \| null | | | `data.outages[].evidence` | object \| null | | | `data.outages[].expectedDark` | boolean \| null | True for planned darkness (operating hours): listed, never counted. | | `data.outages[].expectedReason` | string \| null | | | `data.outages[].selfReportedReason` | string \| null | | | `data.outages[].playerVersion` | string \| null | | | `data.truncated` | boolean | | 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/screens/{id}/playback-quality Get a screen's playback quality Check whether this screen's device is limiting playback quality. The response reports, for each 4K-capable video, whether it plays at full quality or has been reduced because of device limitations or stuttering, along with any hardware upgrade recommendation. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/playback-quality" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.model` | string \| null | | | `data.tier` | string \| null | | | `data.serves4k` | boolean | True when the device is sent 4K renditions. | | `data.videos4k` | array of object | | | `data.videos4k[].id` | string | | | `data.videos4k[].name` | string | | | `data.videos4k[].demoted` | boolean | | | `data.videos4k[].served` | boolean | | | `data.recommendation` | string \| null | | | `data.limitedBy` | "panel" \| "decoder" \| null | Why a 4K-tier device is not sent 4K: its panel shows less than 4K, or it has no hardware 4K decoder. Null when not limited. | 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/screens/{id}/preview Preview what a screen would play at a given time, without affecting the actual device. Pass `at` as an ISO timestamp to preview a different time; it defaults to now. **Notes.** - `data` is the player manifest. Content blocks are open objects in the player's own format; `v` versions it. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | | `at` | query | string | no | ISO timestamp to build the preview for; default now. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/preview" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | ManifestPreview | What the screen would play: the player manifest, built as the device would receive it. | | `data.v` | integer | Manifest format version. | | `data.screen` | object | | | `data.screen.id` | string | | | `data.screen.name` | string | | | `data.screen.rotation` | integer | | | `data.screen.tags` | array of string | | | `data.generatedAt` | string | ISO-8601 timestamp (UTC). | | `data.minPlayerVersion` | string | | | `data.content` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.content.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.standbyContent` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.standbyContent.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.screensOff` | boolean | True when the rules say the panel should be off now. | | `data.operatingWindow` | object \| null | Weekly on-hours by weekday key (`mon`…`sun`), or null for always on. | | `data.proofOfPlay` | boolean | | | `data.dooh` | boolean | True when the workspace has advertising on. Players ignore ad pods when this is false. | | `data.playbackMode` | "sync" \| "unsync" \| "device-time" | | | `data.clock` | object | | | `data.clock.timeZone` | string | | | `data.language` | string | | | `data.location` | object \| null | | | `data.playerSettings` | object | Effective player settings (volume, watermark, download policy, …). | | `data.watermarkText` | string \| null | | | `data.watermarkLogoUrl` | string | The customer's own logo as the corner mark, on the device-readable media route. Present only for a direct, paying workspace with a Brand Kit logo and the logo switch on. Draw it instead of the text mark; when it fails to load, draw no mark. | | `data.accountHold` | object | Present when the account is on hold: the screen shows a hold card, not content. | | `data.accountHold.status` | string | | | `data.accountHold.reason` | string | | | `data.kiosk` | object | Screen Lock. The device's PIN material is never returned here — only whether it is set. | | `data.kiosk.enabled` | boolean | | | `data.kiosk.graceSeconds` | integer | | | `data.kiosk.hasPin` | boolean | | | `data.kiosk.hasRecovery` | boolean | | | `data.apkUpdatePolicy` | object | | | `data.apkUpdatePolicy.window` | boolean | | | `data.apkUpdatePolicy.hourLocal` | integer | | | `data.apkUpdatePolicy.forceAfterDays` | integer | | | `data.apkUpdatePolicy.windowMinutes` | integer | | | `data.apkUpdatePolicy.force` | boolean | | | `data.apkUpdate` | object | | | `data.apkUpdate.version` | string | | | `data.apkUpdate.url` | string | | | `data.apkUpdate.sha256` | string | | | `data.apkUpdate.signature` | string \| null | | | `data.testMode` | true | | | `data.testEligible` | true | | | `data.flightRecorder` | object | | | `data.flightRecorder.sampleMs` | number | | | `data.flightRecorder.maxEdge` | number | | | `data.flightRecorder.quality` | number | | | `data.mediaBenchClipUrl` | string | A short public clip the player decodes off-screen for its media self-test. Absent unless configured. | | `data.fonts` | array of object | | | `data.fonts[].family` | string | | | `data.fonts[].url` | string | | | `data.fonts[].weights` | array of integer | | | `data.upcomingBlocks` | array of object | The next scheduled changes, so an offline device can pre-load them. | | `data.upcomingBlocks[].activatesAt` | string | ISO-8601 timestamp (UTC). | | `data.upcomingBlocks[].content` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.upcomingBlocks[].content.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.upcomingBlocks[].screensOff` | boolean | | | `data.retiredMediaIds` | array of string | Media this workspace deleted from its library in the last 30 days (newest first, at most 200). The device deletes its stored copies. Absent when there are none. | | `data.nextRefreshAt` | string | ISO-8601 timestamp (UTC). | | `data.prestagedOverrides` | array of object | Emergency templates pre-loaded on the device. | | `data.prestagedOverrides[].id` | string | | | `data.prestagedOverrides[].kind` | "emergency" \| "cast" | | | `data.prestagedOverrides[].severity` | "info" \| "warning" \| "critical" | | | `data.prestagedOverrides[].headline` | string | | | `data.prestagedOverrides[].body` | string \| null | | | `data.prestagedOverrides[].content` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.prestagedOverrides[].content.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.prestagedOverrides[].triggeredAt` | string \| null | | | `data.prestagedOverrides[].expiresAt` | string \| null | | | `data.cast` | object | | | `data.cast.id` | string | | | `data.cast.kind` | "emergency" \| "cast" | | | `data.cast.severity` | "info" \| "warning" \| "critical" | | | `data.cast.headline` | string | | | `data.cast.body` | string \| null | | | `data.cast.content` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.cast.content.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.cast.triggeredAt` | string \| null | | | `data.cast.expiresAt` | string \| null | | | `data.emergency` | object | | | `data.emergency.id` | string | | | `data.emergency.kind` | "emergency" \| "cast" | | | `data.emergency.severity` | "info" \| "warning" \| "critical" | | | `data.emergency.headline` | string | | | `data.emergency.body` | string \| null | | | `data.emergency.content` | ManifestContentBlock | Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it. | | `data.emergency.content.kind` | "none" \| "creative" \| "signage" \| "playlist" \| "app" \| "media" \| "layout" | | | `data.emergency.triggeredAt` | string \| null | | | `data.emergency.expiresAt` | string \| null | | | `data.sealed` | true | | | `data.brand` | object | | | `data.brand.partnerId` | string \| null | | | `data.brand.productName` | string | | | `data.brand.logoUrl` | string \| null | The logo the screen draws. A screen sits on a dark background, so this is the partner's logo for dark backgrounds when they set one. | | `data.brand.logoDarkUrl` | string \| null | The partner's logo for dark backgrounds, or null. | | `data.brand.brandColor` | string | | | `data.brand.cmsHost` | string | | | `data.brand.supportEmail` | string | | | `data.brand.termsUrl` | string \| null | | | `data.brand.privacyUrl` | string \| null | | | `data.brand.isWhiteLabel` | boolean | | 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/screens/{id}/quality Get a screen's playback and device quality Returns the quality data the screen's Health tab shows: the content items that played badly in the last 7 days (worst first), how often the player started today and why, and the device health readings from the last 24 hours, such as frame gaps, decoder failures, cache clears and the highest temperature. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/quality" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.problemItems` | array of object | Items that failed or played badly on this screen in the last 7 days, worst first. | | `data.problemItems[].contentId` | string | | | `data.problemItems[].name` | string \| null | | | `data.problemItems[].kind` | string \| null | | | `data.problemItems[].plays` | integer | | | `data.problemItems[].fails` | integer | | | `data.problemItems[].lastFailReason` | string \| null | | | `data.problemItems[].ttffMsMax` | number \| null | | | `data.problemItems[].stallCount` | integer | | | `data.problemItems[].stallMsMax` | number \| null | | | `data.problemItems[].blackMsMax` | number \| null | | | `data.problemItems[].dropPctMax` | number \| null | | | `data.problemItems[].seamWorstMs` | number \| null | | | `data.problemItems[].path` | string \| null | | | `data.problemItems[].src` | string \| null | | | `data.problemItems[].days` | integer | | | `data.restartsToday` | object | Player starts since 00:00 UTC, per launch reason. | | `data.restartSummary` | string \| null | | | `data.mediaBench` | object \| null | The screen's own media self-test (what it can decode), when it has run. | | `data.signals` | object \| null | The last 24 hours of device-health readings. Null when the screen reported none. | 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/screens/{id}/replace-device Unpair a screen's device Release the device currently paired with a screen, without deleting the screen itself. The screen's name, content, location, and history are kept. Follow up with POST /v1/screens/:id/claim-replacement to pair a new device. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/replace-device" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.awaitingReplacement` | true | | 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/screens/{id}/resource-pressure Get a screen's resource pressure Check a screen's storage, memory, and offline cache pressure. The response ranks the content contributing most to that pressure, with suggestions to remove or replace it, and includes hardware upgrade recommendations if relevant. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/resource-pressure" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.severity` | "none" \| "warning" \| "critical" | | | `data.resources` | array of "storage" \| "memory" \| "cache" | The resources under pressure. | | `data.storage` | object | | | `data.storage.severity` | "none" \| "warning" \| "critical" | | | `data.storage.freeMb` | number \| null | | | `data.storage.totalMb` | number \| null | | | `data.storage.freeFrac` | number \| null | Free as a fraction of total (0–1). | | `data.storage.headline` | string \| null | | | `data.storage.daysLeft` | number \| null | Days until full at the recent rate; null when not shrinking. | | `data.memory` | object | | | `data.memory.severity` | "none" \| "warning" \| "critical" | | | `data.memory.freeMb` | number \| null | | | `data.memory.totalMb` | number \| null | | | `data.memory.freeFrac` | number \| null | Free as a fraction of total (0–1). | | `data.memory.headline` | string \| null | | | `data.memory.daysLeft` | number \| null | Days until full at the recent rate; null when not shrinking. | | `data.cache` | object | | | `data.cache.severity` | "none" \| "warning" \| "critical" | | | `data.cache.cacheableBytes` | integer | | | `data.cache.budgetBytes` | integer \| null | | | `data.cache.ramTotalMb` | number \| null | | | `data.cache.videoCount` | integer | | | `data.cache.overBytes` | integer | | | `data.cache.headline` | string \| null | | | `data.heavyContent` | array of object | Assigned content that costs the most, with what removing it frees. | | `data.heavyContent[].kind` | "layout" \| "app" \| "media" | | | `data.heavyContent[].id` | string | | | `data.heavyContent[].name` | string | | | `data.heavyContent[].detail` | string | | | `data.heavyContent[].freesMb` | number | | | `data.heavyContent[].estimated` | boolean | | | `data.heavyContent[].freesLabel` | string | | | `data.heavyContent[].reason` | string | | | `data.hardware` | object \| null | A hardware upgrade suggestion, when the device is the limit. | | `data.summary` | 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 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/restore Restore a deleted screen Restore a screen deleted within the last 30 days, and restore its device pairing. A device that has kept its access token reconnects automatically, without needing to be re-paired on site. Auth: Bearer token. Permission: `screen.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{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 deleted screen with this id. Response 409: The screen is not deleted, or restoring it would exceed the plan. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/revoke-device Revoke a screen's device access Immediately invalidate the access token of the device currently paired with a screen, for example after a device is lost or stolen. The token can no longer be used, including to pair as a new screen. The screen itself is not deleted. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/revoke-device" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.revoked` | true | | | `data.at` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/rotate-token Rotate a screen's device token Generate a new access token for a screen's paired device, invalidating the previous one immediately. The new token is returned once in the response and cannot be retrieved afterward. **Notes.** - The response carries the NEW device credential. The device holding the old token is disconnected and must be given this token (or re-paired) to keep playing. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/rotate-token" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deviceToken` | string | The new device credential. Shown once; the old token stops working now. | | `data.rotatedAt` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/state Get a screen's reported device state Get the screen's most recently reported state, including what is currently displayed, the player software version, and its cache and resource status. The device's last heartbeat snapshot (telemetry, cache, current content, pending updates). Free-form: fields vary by player shell and version. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/state" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| null | Null before the first heartbeat. | 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 screen in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/{id}/telemetry Get a screen's raw telemetry Get the 100 most recent raw telemetry events sent by a screen, newest first, with parsed payload data. **Notes.** - The newest 100 events. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/telemetry" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].spaceId` | string | | | `data[].screenId` | string | | | `data[].type` | string | | | `data[].payload` | any | The event payload (decoded JSON); its shape depends on `type`. | | `data[].occurredAt` | string | ISO-8601 timestamp (UTC). | | `data[].receivedAt` | string | ISO-8601 timestamp (UTC). | 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/screens/{id}/trigger Trigger a screen interaction Send a real-time trigger to a screen: `refresh`, `next`, `go-to-scene`, or `send-event`. The screen receives it immediately. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | "refresh" \| "next" \| "prev" \| "go-to-page" \| "go-to-scene" \| "send-event" | yes | | | `page` | integer | no | `go-to-page`: 1–100. | | `sceneId` | string | no | `go-to-scene`: the scene to show. | | `event` | string | no | `send-event`: the event name the content listens for. | | `payload` | string | no | `send-event`: an optional string payload. | | `overlay` | object | no | A popup shown over what is playing for `seconds`, then removed. The content underneath does not restart. | | `overlay.contentKind` | "media" \| "app" \| "canvas" | yes | | | `overlay.contentId` | string | yes | | | `overlay.seconds` | number | no | 1–600 (clamped); default 15. | | `overlay.position` | "center" \| "top" \| "bottom" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" | no | Default `center`. | | `overlay.params` | object | no | Values passed to the content, e.g. `{ "table": "4" }`. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/trigger" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | The command id. | | `data.kind` | "trigger" | | | `data.trigger` | object | The trigger as stored (only the fields its kind uses). | | `data.trigger.kind` | string | | | `data.trigger.page` | integer | | | `data.trigger.sceneId` | string | | | `data.trigger.event` | string | | | `data.trigger.payload` | string | | | `data.overlay` | object | | | `data.overlay.contentKind` | "media" \| "app" \| "canvas" | | | `data.overlay.contentId` | string | | | `data.overlay.seconds` | integer | 1–600; default 15. | | `data.overlay.position` | "center" \| "top" \| "bottom" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" | | | `data.overlay.params` | object | Values passed to the content, e.g. `{ "table": "4" }`. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: Not a valid trigger, or the overlay content is not in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/{id}/unpower-and-delete Power off and delete a screen Retire a screen in one action: turn off the physical display, unpair the device, and delete the screen. The screen can be recovered within 30 days. Auth: Bearer token. Permission: `screen.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/{id}/unpower-and-delete" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.commandId` | string | The `cec-off` command sent before the device was unpaired. | 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. ## Screens (part 4 of 4) 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/screens/{id}/up-next Get a screen's up-next schedule Get the current running order and the next scheduled change for a screen, based on exactly what the screen itself will play. This endpoint is relatively expensive to compute and should be called on demand rather than polled regularly. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/up-next" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.now` | object \| object \| null | What is on the glass now; null when nothing is. | | `data.overriddenBy` | object \| null | | | `data.rotation` | array of object | The running order under any override, in play order. | | `data.rotation[].name` | string | | | `data.rotation[].kind` | string | | | `data.rotation[].seconds` | number \| null | Fixed dwell; null when the item plays for its own length. | | `data.loops` | boolean | | | `data.nextChange` | object \| null | | 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/screens/{id}/why Explain what a screen shows and why Get a plain-language explanation of why a screen is currently showing what it is showing. The explanation follows the order of precedence: emergency content, then manually assigned content, then scheduled content, then the default, including reasons such as a missing asset or a revoked share. The resolution chain (deactivated → emergency → cast → assigned content), what the device reports on the glass, and warnings. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screen id. | ```bash curl "https://api.brixsignage.com/v1/screens/{id}/why" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.summary` | string | | | `data.currentContent` | object | | | `data.currentContent.kind` | string | The winning layer, or `none`. | | `data.currentContent.id` | string \| null | | | `data.currentContent.name` | string \| null | | | `data.renderTruth` | object | | | `data.renderTruth.verdict` | string | | | `data.renderTruth.ok` | boolean | | | `data.renderTruth.problem` | boolean | | | `data.renderTruth.fault` | "user" \| "platform" \| null | | | `data.renderTruth.reason` | string \| null | | | `data.renderTruth.cause` | "nothing-assigned" \| "nothing-to-play" \| "outside-dates" \| "web-page-blank" \| "content-dark" \| null | For a blank picture: the cause the rows prove, most certain first. | | `data.renderTruth.nextAction` | string \| null | For a blank picture: the one next step. | | `data.renderTruth.headline` | string \| null | For a blank picture: two to four words naming the cause. | | `data.renderTruth.target` | object \| null | For a blank picture: the content the cause is about. | | `data.renderTruth.fix` | "remove-end-date" \| "remove-start-date" \| null | A one-click fix the console can offer. | | `data.renderTruth.since` | string \| null | When the picture started to look blank. | | `data.renderTruth.changed` | object \| null | For a setup cause: the last edit to that content, who and when. | | `data.renderTruth.lastPlayedAt` | string \| null | For a blank picture: the screen's newest proof-of-play time. | | `data.layers` | array of object | | | `data.layers[].layer` | string | | | `data.layers[].active` | boolean | | | `data.layers[].reason` | string | | | `data.layers[].contentName` | string | | | `data.layers[].startedAt` | string | ISO-8601 timestamp (UTC). | | `data.layers[].expiresAt` | string | ISO-8601 timestamp (UTC). | | `data.warnings` | array of string | | 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 screen in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/bulk-assign Set what many screens play Assign one piece of content to many screens in a single request. The content is validated the same way as in the single-screen assign endpoint. Screen IDs outside your access scope or belonging to another workspace are dropped; screens at locations not shared with the content are skipped and counted in the response. This action is recorded as a single entry in the activity log. Assigns one piece of content to many screens. Unknown or out-of-reach screen ids are silently dropped; screens whose location the content is not shared to are skipped and counted in `notShared`; screens under an approval policy the content was not reviewed by are skipped and counted in `needsApproval` unless the caller holds the content kind's approve permission there. Auth: Bearer token. Permission: `screen.cast`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | no | | | `groupId` | string | no | A screen group id (`sgrp_…`): every screen in it, in place of `screenIds`. A group grants nothing: each screen is still checked against what the caller may reach. Send `screenIds` or `groupId`, not both. | | `position` | integer | no | With `groupId`: only the members in this position of the group (index into its `positions`). To set every position at once, and keep it for screens that join later, send `positionContent` to `PATCH /v1/screen-groups/{id}`. | | `contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" | yes | | | `contentId` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/bulk-assign" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.updated` | integer | | | `data.notShared` | integer | | | `data.needsApproval` | integer | | | `data.screenIds` | array of string | The screens actually assigned. | 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 content, or no screen group with that `groupId`. Response 422: Empty/oversized `screenIds`, both `screenIds` and `groupId`, an empty group, `position` without `groupId`, invalid kind, or unplayable content. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/bulk-settings Apply settings to many screens Apply a Display Profile, a bundle of player settings, to many screens at once. You can also set placement fields such as `nodeId`, `location`, and `tags` for the screens in the same request. **Notes.** - A `rotation`, `displayPowerMode` or `playbackMode` value outside its set is ignored, not refused. Auth: Bearer token. Permission: `screen.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | no | Screens to change. Ids you cannot edit are skipped. | | `groupId` | string | no | A screen group id (`sgrp_…`): every screen in it, in place of `screenIds`. A group grants nothing: each screen is still checked against what the caller may reach. Send `screenIds` or `groupId`, not both. | | `settings` | object | yes | | | `settings.rotation` | 0 \| 90 \| 180 \| 270 | no | | | `settings.timezone` | string \| null | no | IANA time zone; null clears it. | | `settings.operatingHours` | string | no | | | `settings.displayPowerMode` | "always-on" \| "follow-schedule" \| "os-default" | no | | | `settings.playbackMode` | "sync" \| "unsync" \| "device-time" | no | | | `settings.powerPolicyId` | string \| null | no | | | `settings.nodeId` | string \| null | no | Move the screens to this location (needs screen.edit there). | | `settings.location` | object \| null | no | | | `settings.tags` | array of string | no | Replaces each screen's tags. | | `settings.playerSettings` | object | no | Merged into each screen's player settings. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/bulk-settings" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.updated` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 404: The destination location does not exist. Response 422: Invalid time zone or screen list. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/claim Pair a device by its code Pair a device using its 6-digit pairing code, creating a new screen. Provide `code`, `name`, and an optional `nodeId`. This endpoint is rate-limited because the pairing code space is small, and is refused if your account is suspended or cancelled. Claims the device showing a 6-digit pairing code into this workspace as a new screen. Auth: Bearer token. Permission: `screen.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | string | yes | The 6-digit code the device shows. | | `name` | string | no | Screen name. Default "New screen". | | `nodeId` | string | no | Location to file the screen under. | | `billingGroupId` | string | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/claim" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.screenId` | string | | | `data.name` | string | | | `data.nodeId` | string \| null | The location the new screen is filed under. | | `data.content` | object | What the new screen plays. Present when the workspace's first screen starts on its starter design. | | `data.content.kind` | "creative" | | | `data.content.id` | string | | | `data.content.name` | string | | | `data.previousScreen` | object \| null | The screen this same device was last paired to in this workspace, if any. | | `data.trialPlan` | object | Present when this pairing took the free trial past the plan chosen for its end: the plan grew to fit, and `totalCents` is charged to the saved card at `startsAt` unless the plan is changed on the Billing page. | | `data.trialPlan.from` | integer | | | `data.trialPlan.screens` | integer | | | `data.trialPlan.cadence` | "monthly" \| "annual" | | | `data.trialPlan.totalCents` | integer | | | `data.trialPlan.startsAt` | 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: `invalid_code`: no device is waiting with that code. Response 409: `ambiguous_code` or `already_claimed`. Response 410: `code_expired`. Response 422: `code` missing, or a foreign location. Response 429: Too many failed codes; honour `Retry-After`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/commands Send a command to many screens Queue the same command across many screens in a single request, using `screenIds`, `kind`, and an optional `payload`. Screen IDs you do not have permission to edit are silently dropped from the request rather than causing an error. Use this instead of sending one request per screen. Queues one command on many screens. Unknown or out-of-reach ids are silently dropped. Risky kinds (set-proxy, set-input, rs232, add-wifi) on a large cohort go to a small canary batch first and the rest are staged. **Notes.** - When no requested screen is reachable the answer is 200 (not 201) with `{ issued: 0, commandIds: [] }`. Auth: Bearer token. Permission: `screen.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | string | yes | | | `payload` | object | no | Per-kind payload: `set-volume` {level 0-100}, `set-brightness` {level}, `set-mute` {muted}, `set-input` {input}, … Most kinds take none. | | `screenIds` | array of string | no | | | `groupId` | string | no | A screen group id (`sgrp_…`): every screen in it, in place of `screenIds`. A group grants nothing: each screen is still checked against what the caller may reach. Send `screenIds` or `groupId`, not both. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/commands" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.issued` | integer | | | `data.commandIds` | array of string | | | `data.staged` | integer | Canary rollouts: commands held behind the canary. | | `data.rolloutId` | string | | | `data.canary` | true | | | `data.skippedAlreadySaved` | array of string | Wi-Fi pushes: screens skipped because they already have this network saved. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 409: `wifi_already_saved`: every requested screen already has this Wi-Fi network saved. Response 422: Unknown kind, invalid payload, or empty/oversized `screenIds`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/count-by-status Count screens by status Get a count of screens by status: online, offline, and unpaired. Counts are limited to the organization nodes you can see. **Notes.** - Returns the counts at the top level — NOT wrapped in `{ data }` like other routes. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/screens/count-by-status" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `online` | integer | | | `offline` | integer | | | `degraded` | integer | Always 0 today (reserved). | | `unpaired` | integer | Screens in `pairing` status. | | `obstructed` | integer | Online screens with a system dialog covering them (also counted in `online`). | 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/screens/enroll Enroll a screen programmatically Create a screen and pair it in a single call using a workspace API key, without a 6-digit pairing code. This is intended for automated device provisioning. The returned device token is shown once and cannot be retrieved again. The screen is created in the workspace the API key belongs to; an API key scoped to one organization node creates the screen under that node, while an account-wide key can target any node in the account. Auth: Bearer token. Permission: `screen.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default `New screen`. | | `nodeId` | string | no | | | `billingGroupId` | string \| null | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/enroll" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.screenId` | string | | | `data.name` | string | | | `data.status` | string | | | `data.deviceToken` | string | The device credential. Shown ONCE: install it on the device; it cannot be read again. | | `data.space` | object | | | `data.space.id` | string | | | `data.space.name` | string \| null | | | `data.node` | object \| 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: The location does not exist. Response 409: The account is suspended or cancelled. Response 429: More than 60 enrollments a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/heavy-check Check if content is too heavy for screens Compares the load of one piece of content (videos that decode at the same time, web zones, 4K video) with what each screen can play (memory, measured device limits and the screen's own media self-test). Leave out `screenIds` to check the screens that show the content now. This is read-only: it warns and never blocks an assignment. Compares one piece of content's load (videos that decode at the same time, web zones, 4K video) with each screen's capability (memory band, measured device limits, its own media self-test). Omit `screenIds` to check the screens that show this content now. Read-only: it warns, it never blocks an assignment. Auth: Bearer token. Permission: `screen.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screenIds` | array of string | no | | | `contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" | yes | | | `contentId` | string | yes | | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/heavy-check" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.load` | object | | | `data.load.concurrentVideos` | integer | | | `data.load.webZones` | integer | | | `data.load.has4kVideo` | boolean | | | `data.load.layout` | object \| null | The heaviest layout's zone mix, checked against each screen's memory band. Null when the content has no layout or the check is not on for this workspace. | | `data.screens` | array of object | Worst first. | | `data.screens[].screenId` | string | | | `data.screens[].name` | string | | | `data.screens[].verdict` | "ok" \| "heavy" \| "too-heavy" | | | `data.screens[].score` | number | | | `data.screens[].decodersNeeded` | integer | | | `data.screens[].decodersAvailable` | integer \| null | Null = no decoder limit on this device. | | `data.screens[].message` | 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: Missing contentKind or contentId, or an oversized `screenIds`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/pair-cost Price one more screen Get what one more screen costs before you pair it. `prompt` is true when the new screen goes past the screens your plan pays for. Then `cost` gives the price for the rest of the current period and the price for each period after it. Nothing is changed. **Notes.** - Read-only. Pairing a screen when `prompt` is true adds it to the plan and to the bill. - No prompt during a free trial, for an internal or partner-billed workspace, or when the plan has a free place. Auth: Bearer token. Permission: `screen.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `billingGroupId` | query | string | no | The billing group the new screen is billed to, when one is chosen. | ```bash curl "https://api.brixsignage.com/v1/screens/pair-cost" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.prompt` | boolean | True when the new screen goes past the screens already paid for. | | `data.reason` | string | | | `data.rail` | "brix" \| "chargebee" \| null | | | `data.plan` | object \| null | | | `data.buy` | object | How the caller pays for more screens. Only when `reason` is `over_plan`. | | `data.buy.canBuy` | boolean | True when the caller can add screens to the plan. | | `data.buy.card` | string \| null | The card that pays, for example "Visa •••• 4242". Null when it is not known or the caller cannot see it. | | `data.buy.carryUnderCents` | integer \| null | Under this amount, the part of the period goes on the next invoice. | | `data.buy.invoiceTermsDays` | integer \| null | Set when the account pays by invoice. More screens go on an invoice that is due in this number of days, and no card is charged. | | `data.cost` | object \| null | | 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/screens/pending List pending discovered devices List devices automatically discovered on the same network as you, newest first. The 6-digit pairing code is not included. To find the device that shows a code, set `code` to that code. **Notes.** - Only devices on the caller's own network (same public IPv4, or the same IPv6 /64) are listed, so call it from the network the devices are on. - The pairing code is not returned (only its last 2 digits, as `codeHint`, for a device that appeared in the last 30 minutes). At most 50 devices are listed for one network, newest first. Auth: Bearer token. Permission: `screen.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `code` | query | string | no | The 6-digit code a screen shows. Lists only the device that shows this code. | ```bash curl "https://api.brixsignage.com/v1/screens/pending" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].pairingId` | string | | | `data[].ordinal` | integer | Position in this list, 1 = newest. The device does not display it; to find the device showing a code, pass `code`. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].expiresAt` | string | ISO-8601 timestamp (UTC). | | `data[].deviceLabel` | string \| null | | | `data[].codeHint` | string \| null | The last 2 digits of the code the device shows, so you can tell devices apart. Present only for a device that appeared in the last 30 minutes; the full code is never returned. | | `data[].zmScreenName` | string \| null | The screen name the device carried over from a previous signage system, when it has one. | | `data[].zmMachineId` | string \| null | | | `data[].previousScreen` | object \| null | A screen in this workspace this device was paired to before; null for a new device. | 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/screens/pending/{id}/dismiss Dismiss a pending device Dismiss a discovered device that you do not want to claim. Its current pairing code expires and the device generates a new one. The dismissed entry is kept in the activity history. Auth: Bearer token. Permission: `screen.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Pending pairing id (`pairingId` from the pending list). | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/pending/{id}/dismiss" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | 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 pending device with this id on the caller's network. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/pending/{id}/identify Identify a pending device Briefly flash a discovered device's display so you can tell which physical screen it is. This only works for devices discovered on your own network; an ID from another network returns a not-found error. Auth: Bearer token. Permission: `screen.create`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Pending pairing id (`pairingId` from the pending list). | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/pending/{id}/identify" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | 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 pending device with this id on the caller's network. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/pending/claim Claim multiple discovered devices as screens in one request, using `items`, an array of objects with `pairingId`, `name`, an optional `nodeId` and an optional `code`. Set `code` to the 6-digit code that the screen shows. If the code is wrong, the API does not claim that screen. Wrong codes count toward the same lockout as POST /v1/screens/claim. To claim a device from a different network using its 6-digit code, use POST /v1/screens/claim instead. This request is refused if your account is suspended or cancelled. **Notes.** - Items that are not pending on the caller's network are skipped, not refused; `claimed` lists the ones that became screens. - One network can claim at most 100 devices an hour without a `code`. Items with the correct `code` are not limited. - A request checks at most one wrong `code`. After a wrong code, the other items that have a `code` are skipped. - The workspace owners get an email for each request that claims a device without a `code`. Auth: Bearer token. Permission: `screen.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `items` | array of object | yes | | | `items[].pairingId` | string | yes | | | `items[].name` | string | no | | | `items[].nodeId` | string | no | Location for the new screen. | | `items[].code` | string | no | The 6-digit code the screen shows. When given, the item is claimed only if it matches; a wrong code counts toward the same lockout as `POST /v1/screens/claim`. | ```bash curl -X POST "https://api.brixsignage.com/v1/screens/pending/claim" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.claimed` | array of object | | | `data.claimed[].pairingId` | string | | | `data.claimed[].screenId` | string | | | `data.claimed[].name` | string | | | `data.claimed[].nodeId` | string \| null | The location the new screen is filed under. | | `data.claimed[].content` | object | What the new screen plays. Present when the workspace's first screen starts on its starter design. | | `data.claimed[].content.kind` | "creative" | | | `data.claimed[].content.id` | string | | | `data.claimed[].content.name` | string | | | `data.skippedNetworkCap` | integer | Items with no `code` that were skipped because this network reached its hourly limit of claims without a code. | | `data.trialPlan` | object | Present when this pairing took the free trial past the plan chosen for its end: the plan grew to fit, and `totalCents` is charged to the saved card at `startsAt` unless the plan is changed on the Billing page. | | `data.trialPlan.from` | integer | | | `data.trialPlan.screens` | integer | | | `data.trialPlan.cadence` | "monthly" \| "annual" | | | `data.trialPlan.totalCents` | integer | | | `data.trialPlan.startsAt` | 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 409: The account is suspended or cancelled. Response 422: `items` is empty. Response 429: Too many wrong codes; claiming by code is locked for a while. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/screens/pending/identify-all Identify all pending devices Briefly flash the displays of every discovered device on your network at once. This is useful when several new devices appear at the same time. Auth: Bearer token. Permission: `screen.create`. ```bash curl -X POST "https://api.brixsignage.com/v1/screens/pending/identify-all" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.count` | integer | Devices asked to show their number. | 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/screens/recycle-bin List deleted screens List screens deleted within the last 30 days that can still be restored with POST /v1/screens/:id/restore. For deleted items across all types, use GET /v1/recycle-bin. **Notes.** - Screens deleted in the last 30 days; older ones are purged. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/screens/recycle-bin" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].kind` | "screen" | | | `data[].id` | string | | | `data[].name` | string | | | `data[].deletedAt` | string | ISO-8601 timestamp (UTC). | | `data[].nodeId` | 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 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/screens/touch-content Find content with tap buttons Say which of the content in `refs` (for example `creative:cr_1,layout:ly_2,playlist:pl_3`) has tap buttons, looking inside layout zones and playlist items. A caller limited to part of the workspace gets answers only for content on screens they can view. Auth: Bearer token. ```bash curl "https://api.brixsignage.com/v1/screens/touch-content" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Screenshots 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/screenshots List screenshots List screen captures uploaded by your screens. Filter by a specific screen using the `screenId` query parameter. The image bytes for each screenshot are retrieved separately from GET /v1/screenshots/:id/file. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `screenId` | query | string | no | Only this screen's captures. | ```bash curl "https://api.brixsignage.com/v1/screenshots" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].screenId` | string | | | `data[].screenName` | string | | | `data[].url` | string | Download path (GET /v1/screenshots/{id}/file). | | `data[].capturedAt` | string | ISO-8601 timestamp (UTC). | | `data[].confirmedAt` | string \| null | | | `data[].width` | integer \| null | | | `data[].height` | integer \| null | | | `data[].sourceWidth` | integer \| null | | | `data[].sourceHeight` | integer \| null | | | `data[].sizeBytes` | integer | | | `data[].capturedBy` | "agent" \| "projection" \| "accessibility" \| "webview" \| null | | | `data[].belowNative` | boolean | Present and true when the capture is smaller than the panel's native resolution. | 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/screenshots/{id}/file Download a screenshot Download the image bytes of one screen capture. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Screenshot id. | ```bash curl "https://api.brixsignage.com/v1/screenshots/{id}/file" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 screenshot with this id, or its file is gone. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Search 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/search Search media, playlists, screens and creatives Search across media, playlists, screens, and creatives using the `q` query parameter. Supports bare terms, prefix matching with `*`, the operators AND, OR, and NOT, and column filters such as `name:dashboard`. Results are scoped to the current space. Full-text search by name. Each list holds only kinds the caller may view (the others come back empty), best match first. A query under 2 characters returns empty lists. **Notes.** - The route is gated by `media.view` (the route-registry description says `screen.view`): a key without `media.view` is refused even if it could see screens. - A failing index query is swallowed and returns an empty list for that kind, so an empty result is not proof of no match. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `q` | query | string | yes | Search text (2+ characters). The last word matches as a prefix. | | `limit` | query | integer | no | Hits per kind (default 10, max 20). | ```bash curl "https://api.brixsignage.com/v1/search" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.media` | array of object | | | `data.media[].id` | string | | | `data.media[].name` | string | The item's name. | | `data.media[].snippet` | string | Matched text with `…` around the hit. | | `data.playlists` | array of object | | | `data.playlists[].id` | string | | | `data.playlists[].name` | string | The item's name. | | `data.playlists[].snippet` | string | Matched text with `…` around the hit. | | `data.screens` | array of object | | | `data.screens[].id` | string | | | `data.screens[].name` | string | The item's name. | | `data.screens[].snippet` | string | Matched text with `…` around the hit. | | `data.creatives` | array of object | | | `data.creatives[].id` | string | | | `data.creatives[].name` | string | The item's name. | | `data.creatives[].snippet` | string | Matched text with `…` around the hit. | 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. ## Serial templates 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/serial-templates List serial command templates List saved RS232 serial command templates for your workspace, such as profiles for turning a display on or switching its input. Each template includes the exact bytes each command sends. **Notes.** - Not paginated. Only templates at locations where the key has `screen.view` are listed. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/serial-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of SerialTemplate | | | `data[].id` | string | Serial template id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].model` | string \| null | Free-text panel model (`Sony Bravia FW-series`). | | `data[].nodeId` | string \| null | Home location; null = workspace root. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].items` | array of object | | | `data[].items[].id` | string | Command id. Kept across edits, so saved buttons that name it keep working. | | `data[].items[].name` | string | | | `data[].items[].value` | string | The command: literal text (`ascii`) or hex digits (`hex`). | | `data[].items[].encoding` | "ascii" \| "hex" | | | `data[].items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | Line ending added after the value. | | `data[].items[].hexPreview` | string | The exact bytes sent, as spaced hex (`2A 53 0A`). | 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/serial-templates Create a serial command template Create an RS232 command template. Provide a `name`, an optional `model`, an `items` array of commands each with `name`, `value`, `encoding` (`ascii` or `hex`), and `eol`, and an optional `nodeId`. Auth: Bearer token. Permission: `screen.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `model` | string \| null | no | | | `nodeId` | string \| null | no | Home location; null = workspace root. | | `items` | array of object | no | The commands, at most 200. On update the list replaces the stored one. | | `items[].id` | string | no | Keep an existing command's id; omit to get a new one. | | `items[].name` | string | yes | | | `items[].value` | string | yes | At most 512 characters, and it must give at least one byte. | | `items[].encoding` | "ascii" \| "hex" | no | Default `ascii`. An unknown value is read as `ascii`. | | `items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | no | Default `none`. An unknown value is read as `none`. | ```bash curl -X POST "https://api.brixsignage.com/v1/serial-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Sony Bravia","model":"FW-55BZ35","items":[{"name":"Power on","value":"*SCPOWR0000000000000001","encoding":"ascii","eol":"lf"}]}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SerialTemplate | A saved set of RS232 commands for one panel model. | | `data.id` | string | Serial template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.model` | string \| null | Free-text panel model (`Sony Bravia FW-series`). | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.items` | array of object | | | `data.items[].id` | string | Command id. Kept across edits, so saved buttons that name it keep working. | | `data.items[].name` | string | | | `data.items[].value` | string | The command: literal text (`ascii`) or hex digits (`hex`). | | `data.items[].encoding` | "ascii" \| "hex" | | | `data.items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | Line ending added after the value. | | `data.items[].hexPreview` | string | The exact bytes sent, as spaced hex (`2A 53 0A`). | ```json { "data": { "id": "sertpl_2b3c4d5e6f7a8b9c", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Sony Bravia", "model": "FW-55BZ35", "nodeId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "items": [ { "id": "sti_3c4d5e6f7a8b9c0d", "name": "Power on", "value": "*SCPOWR0000000000000001", "encoding": "ascii", "eol": "lf", "hexPreview": "2A 53 43 50 4F 57 52 30 30 30 30 30 30 30 30 30 30 30 30 30 30 30 31 0A" } ] } } ``` Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `name` is missing, `invalid_node` (the location is not in this workspace), or a command is not valid (no name, no value, too long, no bytes, a duplicate id, over 200 commands); `message` names it. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/serial-templates/{id} Get a serial command template Get one RS232 command template, including a preview of the exact bytes each command will send to the device. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Serial template id. | ```bash curl "https://api.brixsignage.com/v1/serial-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SerialTemplate | A saved set of RS232 commands for one panel model. | | `data.id` | string | Serial template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.model` | string \| null | Free-text panel model (`Sony Bravia FW-series`). | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.items` | array of object | | | `data.items[].id` | string | Command id. Kept across edits, so saved buttons that name it keep working. | | `data.items[].name` | string | | | `data.items[].value` | string | The command: literal text (`ascii`) or hex digits (`hex`). | | `data.items[].encoding` | "ascii" \| "hex" | | | `data.items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | Line ending added after the value. | | `data.items[].hexPreview` | string | The exact bytes sent, as spaced hex (`2A 53 0A`). | 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 serial template in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/serial-templates/{id} Update a serial command template Update an RS232 command template's name, model, organization node, or list of commands. Existing command IDs are preserved, so anything referencing a specific command continues to work. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Serial template id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Required on create. Cut to 120 characters. | | `model` | string \| null | no | | | `nodeId` | string \| null | no | Home location; null = workspace root. | | `items` | array of object | no | The commands, at most 200. On update the list replaces the stored one. | | `items[].id` | string | no | Keep an existing command's id; omit to get a new one. | | `items[].name` | string | yes | | | `items[].value` | string | yes | At most 512 characters, and it must give at least one byte. | | `items[].encoding` | "ascii" \| "hex" | no | Default `ascii`. An unknown value is read as `ascii`. | | `items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | no | Default `none`. An unknown value is read as `none`. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/serial-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SerialTemplate | A saved set of RS232 commands for one panel model. | | `data.id` | string | Serial template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.model` | string \| null | Free-text panel model (`Sony Bravia FW-series`). | | `data.nodeId` | string \| null | Home location; null = workspace root. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.items` | array of object | | | `data.items[].id` | string | Command id. Kept across edits, so saved buttons that name it keep working. | | `data.items[].name` | string | | | `data.items[].value` | string | The command: literal text (`ascii`) or hex digits (`hex`). | | `data.items[].encoding` | "ascii" \| "hex" | | | `data.items[].eol` | "none" \| "cr" \| "lf" \| "crlf" | Line ending added after the value. | | `data.items[].hexPreview` | string | The exact bytes sent, as spaced hex (`2A 53 0A`). | Response 401: Missing, expired or revoked bearer token. Response 403: No `screen.edit` at the destination location. Response 404: No such serial template in this workspace. Response 422: An empty `name`, `invalid_node` (the destination is not in this workspace), or a command is not valid; `message` names it. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/serial-templates/{id} Delete a serial command template Delete an RS232 command template. Commands already queued using this template are unaffected, because they carry their own fully expanded bytes rather than a reference to the template. **Notes.** - Answers `{ data: { ok: true } }`, not the `{ id, deleted: true }` most other deletes return. There is no restore route. Auth: Bearer token. Permission: `screen.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Serial template id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/serial-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | 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 serial template in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Shared in 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/shared-in/creative/{id}/thumbnail Get the picture of a design shared into this workspace Get a preview image of a design that a different workspace shares with yours. The item stays read-only. If the share has stopped or the item has no picture, the call returns a not-found error. **Notes.** - What a screen playing the shared item airs: the design composited server-side as an SVG. - The item stays read-only. Only the workspace a share names gets the picture. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The id of a design another workspace shares into this one, live. | | `v` | query | string | no | A version stamp. A versioned URL is kept a week. | ```bash curl "https://api.brixsignage.com/v1/shared-in/creative/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 live share of this item into this workspace (never shared, Stop sharing, a suspended source, a deleted item), or it has no picture. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/shared-in/layout/{id}/thumbnail Get the picture of a layout shared into this workspace Get a preview image of a layout that a different workspace shares with yours. The image shows the zones of the layout. If the share has stopped or the item has no picture, the call returns a not-found error. **Notes.** - What a screen playing the shared item airs: the layout's zones composited server-side as an SVG. - The item stays read-only. Only the workspace a share names gets the picture. Auth: Bearer token. Permission: `layout.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The id of a layout another workspace shares into this one, live. | | `v` | query | string | no | A version stamp. A versioned URL is kept a week. | ```bash curl "https://api.brixsignage.com/v1/shared-in/layout/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 live share of this item into this workspace (never shared, Stop sharing, a suspended source, a deleted item), or it has no picture. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/shared-in/media/{id}/thumbnail Get the picture of a media shared into this workspace Get a preview image of a file that a different workspace shares with yours: the poster image of a video or a small copy of an image. The call never returns the file itself. If the share has stopped or the file has no picture, the call returns a not-found error. **Notes.** - What a screen playing the shared item airs: the file's poster still, or a 320 px copy of an image. Never the file itself; a font, audio or web page answers 404. - The item stays read-only. Only the workspace a share names gets the picture. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The id of a media another workspace shares into this one, live. | | `v` | query | string | no | A version stamp. A versioned URL is kept a week. | ```bash curl "https://api.brixsignage.com/v1/shared-in/media/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 live share of this item into this workspace (never shared, Stop sharing, a suspended source, a deleted item), or it has no picture. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/shared-in/playlist/{id}/thumbnail Get the picture of a playlist shared into this workspace Get a preview image of a playlist that a different workspace shares with yours. The image is the picture of the first file or design in the playlist. If the share has stopped or the playlist has no picture, the call returns a not-found error. **Notes.** - What a screen playing the shared item airs: the picture of its first file or design. - The item stays read-only. Only the workspace a share names gets the picture. Auth: Bearer token. Permission: `media.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | The id of a playlist another workspace shares into this one, live. | | `v` | query | string | no | A version stamp. A versioned URL is kept a week. | ```bash curl "https://api.brixsignage.com/v1/shared-in/playlist/{id}/thumbnail" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` 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 live share of this item into this workspace (never shared, Stop sharing, a suspended source, a deleted item), or it has no picture. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Shared with Me 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/shared-with-me List airtime shared with me List airtime slices that other teams have reserved and made available for the caller's team to fill. **Notes.** - Only slices the caller can fill are listed. Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for. Auth: Bearer token. Permission: `playlist.view`. ```bash curl "https://api.brixsignage.com/v1/shared-with-me" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].allocationId` | string | | | `data[].label` | string | | | `data[].reservedForNodeId` | string | The location the slice is reserved for. | | `data[].reservedForName` | string | | | `data[].kind` | "percent" \| "every-nth" \| "daypart" | Only `percent` and `every-nth` slices are listed. | | `data[].value` | number | The share of airtime (a percentage, or every Nth item). | | `data[].requiresApproval` | boolean | | | `data[].sourcePlaylist` | object | | | `data[].sourcePlaylist.id` | string | | | `data[].sourcePlaylist.name` | string | | | `data[].sourcePlaylist.nodeId` | string \| null | | | `data[].fill` | object \| null | The playlist that fills the slice; null when none is bound. | 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/shared-with-me/{allocationId}/fill Create a fill playlist Create a new playlist and attach it as the fill for an airtime slice reserved for the caller's team. **Notes.** - Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for. - The new playlist is empty and is placed at the reserved location. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `allocationId` | path | string | yes | Slice (allocation) id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Default ` slice`. | ```bash curl -X POST "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/fill" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success: A fill playlist is already bound: it is returned (`created: false`) and nothing is created. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.allocationId` | string | | | `data.fillPlaylistId` | string | | | `data.name` | string | | | `data.created` | boolean | | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.allocationId` | string | | | `data.fillPlaylistId` | string | | | `data.name` | string | | | `data.created` | boolean | | Response 401: Missing, expired or revoked bearer token. Response 403: You cannot fill this slice. Response 404: No such fillable slice in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/shared-with-me/{allocationId}/fill Set the fill playlist Attach an existing playlist as the fill for an airtime slice reserved for the caller's team. Send `playlistId` as `null` to remove it. **Notes.** - Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `allocationId` | path | string | yes | Slice (allocation) id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `playlistId` | string \| null | yes | A playlist you can edit; null unbinds. | ```bash curl -X PUT "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/fill" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.allocationId` | string | | | `data.fillPlaylistId` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You cannot fill this slice, or cannot edit that playlist. Response 404: No such fillable slice, or no such playlist in this workspace. Response 422: The playlist is the one the slice belongs to. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/shared-with-me/{allocationId}/source Read the playlist a slice belongs to Get the owner playlist around an airtime slice shared with your team: its name, whether it shuffles, its items in play order (name, kind, thumbnail, duration), and the share itself (kind, value, whether approval is required, and your fill playlist). Read only. Besides `playlist.view`, you need `playlist.edit` at the location the slice is reserved for. Other locations’ shares and the owner’s settings are not returned. **Notes.** - Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for. - Read only. Other locations' shares and the owner's settings are not returned. Auth: Bearer token. Permission: `playlist.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `allocationId` | path | string | yes | Slice (allocation) id. | ```bash curl "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/source" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.playlist` | object | | | `data.playlist.id` | string | | | `data.playlist.name` | string | | | `data.playlist.shuffle` | boolean | | | `data.items` | array of object | The owner's items in order: what plays around your share. | | `data.items[].name` | string | | | `data.items[].kind` | string | | | `data.items[].thumbnailUrl` | string \| null | | | `data.items[].durationSec` | number | | | `data.share` | object | | | `data.share.kind` | "percent" \| "every-nth" \| "daypart" | | | `data.share.value` | number | | | `data.share.requiresApproval` | boolean | | | `data.share.reservedForName` | string | | | `data.share.fillPlaylistId` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You cannot fill this slice. Response 404: No such fillable slice in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Shares 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/shares/{kind}/{id} Get a content item's shares List the share entries for one content item, showing which nodes, users, and roles it is shared with, and at what level. Requires view, edit, or share permission on the item at its home node. **Notes.** - Besides the `screen.view` gate, the caller needs the item's view, edit or share permission (`playlist.view`, …) at its location; media is checked at the workspace root. - A row targets one location (and everything under it), one person or one role; a row with no target shares with every location. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `kind` | path | string | yes | `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. | | `id` | path | string | yes | The content item's id. | ```bash curl "https://api.brixsignage.com/v1/shares/{kind}/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].targetNodeId` | string \| null | | | `data[].targetUserId` | string \| null | | | `data[].targetRoleId` | string \| null | | | `data[].level` | "disabled" \| "play" \| "play_local" | | Response 401: Missing, expired or revoked bearer token. Response 403: You hold none of the item's view, edit or share permission at its location. Response 404: No such item in this workspace. Response 422: Unknown `kind`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PUT /v1/shares/{kind}/{id} Replace a content item's shares Replace the entire share set for one content item. Each entry targets exactly one of a node, a user, or a role. Requires the item's own share permission at its home node. **Notes.** - Replaces every share of the item in one step. Besides the `screen.view` gate, the caller needs the kind's share permission at the item's location (media: at the workspace root). - A row targets one location (and everything under it), one person or one role; a row with no target shares with every location. - The response echoes the request's rows rather than the stored ones. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `kind` | path | string | yes | `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. | | `id` | path | string | yes | The content item's id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `shares` | array of object | yes | The whole new share set (at most 200). An empty array removes every share. | | `shares[].targetNodeId` | string \| null | no | | | `shares[].targetUserId` | string \| null | no | | | `shares[].targetRoleId` | string \| null | no | | | `shares[].level` | string | yes | `disabled`, `play` or `play_local`; any other value is stored as `play`. | ```bash curl -X PUT "https://api.brixsignage.com/v1/shares/{kind}/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" | | | `data.contentId` | string | | | `data.shares` | array of object | The share set as SENT, with duplicate targets collapsed (last one wins): `level` is echoed as sent, not as stored, and there are no row ids (read them with GET). | | `data.shares[].targetNodeId` | string \| null | | | `data.shares[].targetUserId` | string \| null | | | `data.shares[].targetRoleId` | string \| null | | | `data.shares[].level` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the kind's share permission (`playlist.share`, …) at the item's location. Response 404: No such item in this workspace. Response 422: Unknown `kind`, more than 200 rows, a row with more than one target, or a person or role that is not in this workspace (a person must be one the share directory offers you). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/shares/directory List shareable people and roles List the people and roles a share can target, including id, display name, and, for roles, colour and member count. Available to anyone holding a share permission on any content, rather than requiring full user directory access. People are listed only from the caller's own workspace: a franchise child workspace sees its own people, never the parent's or another child workspace's. Email is returned only for people the caller can see with the user view permission; otherwise it is null. A role's member count counts only the listed people. **Notes.** - Besides the `screen.view` gate, the caller needs at least one share permission somewhere. - People stop at the child-workspace line: a franchise child workspace sees only its own people, and the parent does not see into a child. `email` needs `user.view` reaching that person, else it is null. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/shares/directory" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.users` | array of object | People in the workspace the caller shares from (active and invited; never across a franchise child-workspace line). | | `data.users[].id` | string | | | `data.users[].name` | string | | | `data.users[].email` | string \| null | Only for people the caller could read with `user.view`; null otherwise. | | `data.roles` | array of object | Every role in the workspace. | | `data.roles[].id` | string | | | `data.roles[].name` | string | | | `data.roles[].color` | string \| null | | | `data.roles[].memberCount` | integer | Members among the people listed above. | Response 401: Missing, expired or revoked bearer token. Response 403: You hold no share permission (`playlist.share`, `media.share`, …) anywhere. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Signage master templates 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/signage-master-templates List master signage templates Return the published catalog of signage templates curated by Brix. This catalog is shared across all workspaces rather than scoped to one, and is the only source of the masterId values required when creating a signage template. Drafts and deleted entries are not included. **Notes.** - Not paginated: the whole published catalog comes back, sorted by `sortOrder` then name. Auth: Bearer token. Permission: `creative.view`. ```bash curl "https://api.brixsignage.com/v1/signage-master-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of SignageMasterTemplate | | | `data[].id` | string | | | `data[].name` | string | | | `data[].description` | string \| null | | | `data[].industry` | string \| null | | | `data[].archetype` | string \| null | | | `data[].sortOrder` | integer | | | `data[].format` | "engine" \| "creative" \| "pack" | `engine`: `config` is the template. `creative`: `creative` is a finished design to create a creative from. `pack`: `creative.screens` holds one finished design per screen of a multi-screen set (for example three menu TVs side by side); create one creative from each. | | `data[].config` | object | The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write. | | `data[].creative` | any \| null | `creative` format: the design (the body `POST /v1/creatives` takes). `pack` format: `{ screens: [{ name?, ...design }] }`, in screen order. Null otherwise. | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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. ## Signage templates 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/signage-templates List signage templates Return the signage template instances in this workspace. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | 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). | ```bash curl "https://api.brixsignage.com/v1/signage-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of SignageTemplate | | | `data[].id` | string | Signage template id. | | `data[].spaceId` | string | | | `data[].name` | string | | | `data[].config` | object | The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write. | | `data[].nodeId` | string \| null | | | `data[].masterId` | string \| null | The master template it was copied from, if any. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | | `data[].deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | | `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/signage-templates Create a signage template instance from a configuration object containing archetype, style, palette, orientation, and content. **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. Auth: Bearer token. Permission: `creative.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | | | `config` | object \| string | no | A configuration object, or the same as a JSON string. Default `{}`. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `masterId` | string \| null | no | An id from `GET /v1/signage-master-templates`. | ```bash curl -X POST "https://api.brixsignage.com/v1/signage-templates" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Signage template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.config` | object | The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write. | | `data.nodeId` | string \| null | | | `data.masterId` | string \| null | | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: Missing name, invalid JSON, or a location outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/signage-templates/{id} Get a signage template Return one signage template instance. Auth: Bearer token. Permission: `creative.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Signage template id. | ```bash curl "https://api.brixsignage.com/v1/signage-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SignageTemplate | A signage template instance in this workspace. | | `data.id` | string | Signage template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.config` | object | The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write. | | `data.nodeId` | string \| null | | | `data.masterId` | string \| null | The master template it was copied from, if any. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | 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 signage template in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/signage-templates/{id} Update a signage template Edit a signage template instance's configuration or name. Screens currently playing it receive an updated manifest reflecting the change. **Notes.** - When the PATCH does not send `config`, the response carries the stored config as it is: an old row is not brought to the current `schemaVersion` here (GET does that). Auth: Bearer token. Permission: `creative.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Signage template id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | | | `config` | object \| string | no | A configuration object, or the same as a JSON string. Default `{}`. | | `nodeId` | string \| null | no | Home location. Default: the caller's own location. | | `masterId` | string \| null | no | An id from `GET /v1/signage-master-templates`. | | `baseUpdatedAt` | string | no | Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/signage-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SignageTemplate | A signage template instance in this workspace. | | `data.id` | string | Signage template id. | | `data.spaceId` | string | | | `data.name` | string | | | `data.config` | object | The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write. | | `data.nodeId` | string \| null | | | `data.masterId` | string \| null | The master template it was copied from, if any. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.deletedAt` | string \| null | Always null on these reads: deleted rows are not listed. | Response 401: Missing, expired or revoked bearer token. Response 403: Moving it to a location where you lack creative.edit. Response 404: No such signage template in this workspace. Response 409: `conflict`: the row changed since `baseUpdatedAt`; the body carries `current`. Response 422: Invalid JSON. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/signage-templates/{id} Delete a signage template Move a signage template instance to the recycle bin. Auth: Bearer token. Permission: `creative.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Signage template id. | | `force` | query | "true" | no | Delete even when it is shared into other places; the shares go with it. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/signage-templates/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.deleted` | true | | | `data.sharesRemoved` | integer | Shares removed with it. | 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 signage template in this workspace. Response 409: `content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/signage-templates/{id}/restore Restore a signage template Bring back a deleted signage template instance from the recycle bin. Auth: Bearer token. Permission: `creative.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Signage template id. | ```bash curl -X POST "https://api.brixsignage.com/v1/signage-templates/{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 signage template in this workspace, or it was purged. Response 409: `not_deleted`: it is not in the recycle bin. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Social accounts 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/social-accounts List social accounts List the social accounts connected to your workspace. Use the provider query parameter, for example provider=youtube, to filter by provider. Each result includes the display name and connection status for the account, but never the stored credentials. **Notes.** - Only accounts at locations the caller can see. Credentials are never returned. Auth: Bearer token. Permission: `integration.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `provider` | query | string | no | Only accounts of this provider, e.g. `instagram`. | ```bash curl "https://api.brixsignage.com/v1/social-accounts" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].id` | string | | | `data[].provider` | string | `instagram`, `facebook`, `youtube`, `google-calendar`, `google-sheets`, … | | `data[].externalId` | string | The account's id at the provider. | | `data[].displayName` | string | | | `data[].nodeId` | string \| null | | | `data[].expiresAt` | string \| null | When the provider's access expires, if known. | | `data[].needsReconnectAt` | string \| null | Set when the provider refused the stored access: sign in again. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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/social-accounts Add social account Create a social account connection by submitting its credentials directly. Credentials are encrypted before they are stored. For most providers, use the provider's OAuth start endpoint instead, since it handles sign-in and consent on your behalf. Auth: Bearer token. Permission: `integration.create`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `provider` | string | yes | | | `externalId` | string | yes | | | `displayName` | string | yes | | | `creds` | object | yes | The provider credential (for example access and refresh tokens). Encrypted; never returned. | | `nodeId` | string \| null | no | | | `expiresAt` | string \| null | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/social-accounts" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success: An account of the same provider and external id that needed a new sign-in was reconnected instead: its id is returned. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `integration.create` at the location. Response 422: `provider`, `externalId`, `displayName` or `creds` is missing, or a location outside this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/social-accounts/{id} Update social account Update a connected social account by its ID. You can change its display name or move it to a different location in your organization. **Notes.** - Answers `{ ok: true }`, not the account. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Social account id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `displayName` | string | no | | | `nodeId` | string \| null | no | Move the account; you need `integration.edit` at the destination too. | | `creds` | object | no | Replaces the stored credential and clears `needsReconnectAt`. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/social-accounts/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You cannot move the account to that location. Response 404: No such account in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/social-accounts/{id} Remove social account Delete a connected social account by its ID. This permanently removes the stored credentials and stops any apps that use the account from fetching new data. **Notes.** - Answers `{ ok: true }`. Auth: Bearer token. Permission: `integration.delete`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Social account id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/social-accounts/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | 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 account in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/social-accounts/preview-token Get social preview token Get a short-lived token used to preview a live social app before it is published to a screen. Pass this token as the dt query parameter when calling social feed endpoints from a preview. The token is issued only for your own workspace and cannot be requested for another one. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/social-accounts/preview-token" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.token` | string | A new short-lived token that lets an app preview read this workspace's social feeds (the `dt` parameter). Minted on each call. | | `data.expiresIn` | integer | Seconds until it expires (1800). | 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. ## SSO connections 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/sso-connections List SSO connections Returns the workspace's enterprise single sign-on connections, with client secrets masked. The key or person must have `settings.view` for the whole workspace. A caller limited to a location or to a franchise workspace gets 403. `lastClaims` holds the claims from the last sign-in: a person's email, name and groups. It is `null` unless the caller also has `user.view` for the whole workspace. Auth: Bearer token. Permission: `settings.view`. ```bash curl "https://api.brixsignage.com/v1/sso-connections" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of SsoConnection | | | `data[].id` | string | | | `data[].displayName` | string | | | `data[].vendor` | string | Free text; `generic-oidc` when not set. | | `data[].issuer` | string | The OpenID Connect issuer URL (`https://`, no trailing slash). | | `data[].clientId` | string | | | `data[].clientSecretPreview` | "••••••••" | Always this mask: the client secret is stored encrypted and is never returned. | | `data[].emailDomains` | string | Comma-separated, lower-case (a leading `@` and a trailing dot are removed). | | `data[].domainsVerifiedAt` | string \| null | When DNS proved the domains; null until verified. An unverified connection is not offered at sign-in. | | `data[].provenAt` | string \| null | When a sign-in first completed with the current issuer, client and domains; null until then. | | `data[].lastSignInAt` | string \| null | The latest sign-in through this connection. Only the list fills it; create and update answer null. | | `data[].jitProvisioning` | boolean | Create a person on their first sign-in. | | `data[].defaultRoleId` | string \| null | The role a new person gets at the workspace root when no rule applies. | | `data[].claimMapping` | SsoClaimMapping \| null | | | `data[].extraScopes` | string \| null | Scopes requested on top of `openid email profile`, space-separated. | | `data[].lastClaims` | object \| null | The claims of the last sign-in (a person's email, name and groups). Null unless the caller also holds `user.view` for the whole workspace. | | `data[].lastClaimsAt` | string \| null | | | `data[].enabled` | boolean | | | `data[].redirectUri` | string | The redirect URI to register in the identity provider. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/sso-connections Create SSO connection Creates an enterprise single sign-on connection. The client secret is encrypted before it is stored. **Notes.** - A new connection is unverified: prove its domains (`domain-challenge`, then `verify-domains`) before it is offered at sign-in. Auth: Bearer token. Permission: `settings.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `displayName` | string | yes | | | `vendor` | string | no | Free text, e.g. `okta`, `entra`. | | `issuer` | string | yes | Must start with `https://`. A trailing slash is removed. | | `clientId` | string | yes | | | `clientSecret` | string | yes | Encrypted before it is stored; never returned. | | `emailDomains` | string | yes | Comma-separated email domains, e.g. `acme.com,acme.org`. | | `jitProvisioning` | boolean | no | Default true. | | `enabled` | boolean | no | Default true. | | `defaultRoleId` | string \| null | no | You must be able to grant this role for the whole workspace. | | `claimMapping` | SsoClaimMapping \| null | no | You must be able to grant each rule's role where the rule grants it. Null clears it. | | `extraScopes` | string \| null | no | Space- or comma-separated scope tokens (at most 20). Null or empty clears them. | ```bash curl -X POST "https://api.brixsignage.com/v1/sso-connections" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"displayName":"Acme Okta","issuer":"https://acme.okta.com","clientId":"0oa1b2c3d4","clientSecret":"example-client-secret","emailDomains":"acme.com"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SsoConnection | An enterprise single sign-on (OpenID Connect) connection. | | `data.id` | string | | | `data.displayName` | string | | | `data.vendor` | string | Free text; `generic-oidc` when not set. | | `data.issuer` | string | The OpenID Connect issuer URL (`https://`, no trailing slash). | | `data.clientId` | string | | | `data.clientSecretPreview` | "••••••••" | Always this mask: the client secret is stored encrypted and is never returned. | | `data.emailDomains` | string | Comma-separated, lower-case (a leading `@` and a trailing dot are removed). | | `data.domainsVerifiedAt` | string \| null | When DNS proved the domains; null until verified. An unverified connection is not offered at sign-in. | | `data.provenAt` | string \| null | When a sign-in first completed with the current issuer, client and domains; null until then. | | `data.lastSignInAt` | string \| null | The latest sign-in through this connection. Only the list fills it; create and update answer null. | | `data.jitProvisioning` | boolean | Create a person on their first sign-in. | | `data.defaultRoleId` | string \| null | The role a new person gets at the workspace root when no rule applies. | | `data.claimMapping` | SsoClaimMapping \| null | | | `data.extraScopes` | string \| null | Scopes requested on top of `openid email profile`, space-separated. | | `data.lastClaims` | object \| null | The claims of the last sign-in (a person's email, name and groups). Null unless the caller also holds `user.view` for the whole workspace. | | `data.lastClaimsAt` | string \| null | | | `data.enabled` | boolean | | | `data.redirectUri` | string | The redirect URI to register in the identity provider. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there. Response 404: No such connection, role or location in this workspace. Response 422: A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### PATCH /v1/sso-connections/{id} Update SSO connection Updates an enterprise single sign-on connection. `clientSecret` is optional: when provided, it replaces the stored secret; when omitted, the existing secret is left unchanged. **Notes.** - Changing `emailDomains`, `issuer` or `clientId` clears `domainsVerifiedAt` (the DNS proof vouches for the IdP too; publish the new challenge and verify again). Changing `issuer`, `clientId`, `clientSecret` or `emailDomains` clears `provenAt`. Auth: Bearer token. Permission: `settings.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `displayName` | string | no | | | `vendor` | string | no | Free text, e.g. `okta`, `entra`. | | `issuer` | string | no | Must start with `https://`. A trailing slash is removed. | | `clientId` | string | no | | | `clientSecret` | string | no | Replaces the stored secret. Omitted or empty keeps it. | | `emailDomains` | string | no | Comma-separated email domains, e.g. `acme.com,acme.org`. | | `jitProvisioning` | boolean | no | Default true. | | `enabled` | boolean | no | Default true. | | `defaultRoleId` | string \| null | no | You must be able to grant this role for the whole workspace. | | `claimMapping` | SsoClaimMapping \| null | no | You must be able to grant each rule's role where the rule grants it. Null clears it. | | `extraScopes` | string \| null | no | Space- or comma-separated scope tokens (at most 20). Null or empty clears them. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/sso-connections/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | SsoConnection | An enterprise single sign-on (OpenID Connect) connection. | | `data.id` | string | | | `data.displayName` | string | | | `data.vendor` | string | Free text; `generic-oidc` when not set. | | `data.issuer` | string | The OpenID Connect issuer URL (`https://`, no trailing slash). | | `data.clientId` | string | | | `data.clientSecretPreview` | "••••••••" | Always this mask: the client secret is stored encrypted and is never returned. | | `data.emailDomains` | string | Comma-separated, lower-case (a leading `@` and a trailing dot are removed). | | `data.domainsVerifiedAt` | string \| null | When DNS proved the domains; null until verified. An unverified connection is not offered at sign-in. | | `data.provenAt` | string \| null | When a sign-in first completed with the current issuer, client and domains; null until then. | | `data.lastSignInAt` | string \| null | The latest sign-in through this connection. Only the list fills it; create and update answer null. | | `data.jitProvisioning` | boolean | Create a person on their first sign-in. | | `data.defaultRoleId` | string \| null | The role a new person gets at the workspace root when no rule applies. | | `data.claimMapping` | SsoClaimMapping \| null | | | `data.extraScopes` | string \| null | Scopes requested on top of `openid email profile`, space-separated. | | `data.lastClaims` | object \| null | The claims of the last sign-in (a person's email, name and groups). Null unless the caller also holds `user.view` for the whole workspace. | | `data.lastClaimsAt` | string \| null | | | `data.enabled` | boolean | | | `data.redirectUri` | string | The redirect URI to register in the identity provider. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there. Changing `claimMapping` or `defaultRoleId` (clearing included) also needs you to be able to grant every role the CURRENT mapping and default role give; a mapping that seats Owners can be changed only by an Owner signed in as a person. Changing `issuer`, `clientId` or `emailDomains`, or setting `enabled` back to true, needs an Owner signed in as a person (`owner_required`). Response 404: No such connection, role or location in this workspace. Response 422: A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/sso-connections/{id} Delete SSO connection Soft-deletes an enterprise single sign-on connection. **Notes.** - Answers `{ ok: true }`, not the `{ id, deleted }` shape of other deletes. The connection is also disabled. Auth: Bearer token. Permission: `settings.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/sso-connections/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/sso-connections/{id}/domain-challenge Get domain verification challenge Returns the DNS TXT records you must publish to prove control of the email domains used by this SSO connection. The key or person must have `settings.view` for the whole workspace. Auth: Bearer token. Permission: `settings.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | ```bash curl "https://api.brixsignage.com/v1/sso-connections/{id}/domain-challenge" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.records` | array of object | | | `data.records[].domain` | string | | | `data.records[].name` | string | The record name: `_brix-verify.`. | | `data.records[].type` | "TXT" | | | `data.records[].value` | string | The record value to publish: `brix-domain-verify=`. | | `data.verifiedAt` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/sso-connections/{id}/scim Get SCIM configuration Returns the SCIM base URL for this SSO connection and a preview of its currently live provisioning tokens. Token secrets themselves are never returned. Auth: Bearer token. Permission: `settings.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | ```bash curl "https://api.brixsignage.com/v1/sso-connections/{id}/scim" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.baseUrl` | string | The SCIM 2.0 base URL to give the identity provider. | | `data.tokens` | array of object | Live tokens only. | | `data.tokens[].id` | string | | | `data.tokens[].preview` | string | `••••` and the last four characters. | | `data.tokens[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data.tokens[].lastUsedAt` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/sso-connections/{id}/scim/tokens Create SCIM token Creates a new SCIM provisioning token for this SSO connection. The token value is shown exactly once, in this response. A connection can have at most 5 live tokens at a time. Only a workspace Owner, signed in as a person, can create one; the token stops working if that person is no longer an Owner. This action cannot be taken while impersonating another user. Auth: Bearer token. Permission: `settings.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | ```bash curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/scim/tokens" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.token` | string | The SCIM bearer token. Shown only here; store it now. | | `data.baseUrl` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). `owner_required`: only a workspace Owner, signed in as a person, can create a SCIM token (not an API key). The token stops working if that person is no longer an Owner. Response 404: No such connection in this workspace. Response 409: `too_many_tokens`: the connection already has 5 live tokens. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/sso-connections/{id}/scim/tokens/{tokenId} Revoke SCIM token Revokes one SCIM provisioning token belonging to this SSO connection. Auth: Bearer token. Permission: `settings.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | | `tokenId` | path | string | yes | SCIM token id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/sso-connections/{id}/scim/tokens/{tokenId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection, or no live token with this id. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/sso-connections/{id}/test-mapping Test SSO claim mapping Previews the role and location a person would be granted, given a set of example identity-provider claims, by running the same mapping logic used at sign-in. This is read-only and does not sign anyone in or change anything. Auth: Bearer token. Permission: `settings.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `claims` | object | yes | Example identity-provider claims. | | `claimMapping` | SsoClaimMapping \| null | no | An unsaved mapping to test; omitted = the saved one. | ```bash curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/test-mapping" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.mapped` | boolean | False when there is no mapping: `grants` is then the default role at the root, without names. | | `data.grants` | array of object | | | `data.grants[].nodeId` | string | Location id (the workspace id for the root). | | `data.grants[].roleId` | string | | | `data.grants[].roleName` | string \| null | Absent when `mapped` is false. | | `data.grants[].nodeName` | string \| null | Absent when `mapped` is false. | | `data.matchedRules` | array of integer | Indexes of the rules that matched. | | `data.unmatchedLocations` | array of string | Location values that matched no location. | | `data.ambiguousLocations` | array of string | Location values that matched more than one location. | | `data.usedDefault` | boolean | | | `data.denied` | boolean | True when the sign-in would be refused (`noMatch: deny`). | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection in this workspace. Response 422: `claims` is not an object, or `claimMapping` is invalid. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/sso-connections/{id}/verify-domains Verify SSO domains Verifies an SSO connection's email domains using a DNS TXT record lookup. Verified domains control whether the connection is offered at sign-in and whether cross-workspace sign-in is allowed for that domain. **Notes.** - Answers 200 with `verified: false` when a domain fails; the connection stays unverified. Auth: Bearer token. Permission: `settings.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | SSO connection id. | ```bash curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/verify-domains" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.verified` | boolean | True only when every domain proved out. | | `data.results` | array of object | | | `data.results[].domain` | string | | | `data.results[].ok` | boolean | | | `data.results[].reason` | string | Why a domain failed: `claimed_by_another_workspace`, `dns_`, or a lookup error. Absent when the lookup answered. | | `data.verifiedAt` | string \| null | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Response 404: No such connection in this workspace. Response 422: `no_domains`: the connection has no email domains. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/sso-connections/test Test SSO discovery Fetches the identity provider's OpenID Connect discovery document and returns its parsed authorization, token, and key endpoints, so the connection can be confirmed as reachable before the setup form is submitted. **Notes.** - Needs `settings.view` held anywhere, unlike the other SSO routes, which need it for the whole workspace. Auth: Bearer token. Permission: `settings.view`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `issuer` | string | yes | Must start with `https://`. | ```bash curl -X POST "https://api.brixsignage.com/v1/sso-connections/test" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.issuer` | string | The issuer the discovery document names; absent when it names none. | | `data.authorizationEndpoint` | string | | | `data.tokenEndpoint` | string | | | `data.jwksUri` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `issuer` is not `https://`. Response 502: `discovery_failed` (the provider answered an error), `discovery_incomplete` (an endpoint is missing), or `discovery_threw` (not reachable). Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Status 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/status Get platform status Get the current platform status, including overall state, 30-day latency attainment, open and recent published incidents, and a 90-day history strip. This endpoint requires no authentication. If the underlying status data is more than three hours old, the state is reported as `unknown` rather than `operational`. Pass `format=text` for a plain-text response. **Notes.** - Answers 200 during an outage too: the state is in the body. - With `format=text` the body is `text/plain`. Auth: none. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `format` | query | "text" | no | `text` answers a plain-text summary instead of JSON. | ```bash curl "https://api.brixsignage.com/v1/status" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.state` | "operational" \| "degraded" \| "outage" \| "unknown" | | | `data.computedAt` | string \| null | When the status was measured; null when never. | | `data.stale` | boolean | True when the measurement is more than three hours old (the state is then `unknown`). | | `data.latency` | object \| null | | | `data.incidents` | array of StatusIncident | Open incidents. | | `data.incidents[].id` | string | | | `data.incidents[].title` | string | | | `data.incidents[].status` | "investigating" \| "identified" \| "monitoring" \| "resolved" | | | `data.incidents[].impact` | "degraded" \| "outage" \| "none" | | | `data.incidents[].startedAt` | string | ISO-8601 timestamp (UTC). | | `data.incidents[].resolvedAt` | string \| null | | | `data.incidents[].updates` | array of object | Oldest first. | | `data.incidents[].updates[].at` | string | ISO-8601 timestamp (UTC). | | `data.incidents[].updates[].status` | "investigating" \| "identified" \| "monitoring" \| "resolved" | | | `data.incidents[].updates[].message` | string | | | `data.incidents[].screensPlaying` | boolean \| null | Whether screens kept playing during the incident; null when not stated. | | `data.recent` | array of StatusIncident | Recently resolved incidents. | | `data.recent[].id` | string | | | `data.recent[].title` | string | | | `data.recent[].status` | "investigating" \| "identified" \| "monitoring" \| "resolved" | | | `data.recent[].impact` | "degraded" \| "outage" \| "none" | | | `data.recent[].startedAt` | string | ISO-8601 timestamp (UTC). | | `data.recent[].resolvedAt` | string \| null | | | `data.recent[].updates` | array of object | Oldest first. | | `data.recent[].updates[].at` | string | ISO-8601 timestamp (UTC). | | `data.recent[].updates[].status` | "investigating" \| "identified" \| "monitoring" \| "resolved" | | | `data.recent[].updates[].message` | string | | | `data.recent[].screensPlaying` | boolean \| null | Whether screens kept playing during the incident; null when not stated. | | `data.days` | array of object | One entry per day, for the last 90 days. | | `data.days[].date` | string | `YYYY-MM-DD`. | | `data.days[].state` | "operational" \| "degraded" \| "outage" | | Response 401: Missing, expired or revoked bearer token. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/status/deprecations List API deprecations List every API route scheduled for retirement, when it stops working, and its replacement. This endpoint requires no authentication and is safe to poll from a script. An empty list means no routes are currently scheduled for retirement. Auth: none. ```bash curl "https://api.brixsignage.com/v1/status/deprecations" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.noticeDays` | integer | The minimum notice a retired route gets. | | `data.policy` | string | | | `data.deprecations` | array of object | | | `data.deprecations[].route` | string | `METHOD /path`. | | `data.deprecations[].announced` | string | Date (`YYYY-MM-DD`) it was listed. | | `data.deprecations[].sunset` | string | Date (`YYYY-MM-DD`) it stops working. | | `data.deprecations[].replacement` | string \| null | | | `data.deprecations[].why` | string | | | `data.deprecations[].noticeDays` | integer | Days between `announced` and `sunset`. | Response 401: Missing, expired or revoked bearer token. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Uptime 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/uptime Get uptime report Get an uptime report for a date range, with online percentage per screen and per location, downtime windows, and mean time to recovery. **Notes.** - Only screens at locations the caller can see. `outageSummary` is present only when there were outages. Auth: Bearer token. Permission: `screen.view`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `from` | query | string | no | ISO-8601 start (default: the start of the workspace's offline-history window). | | `to` | query | string | no | ISO-8601 end (default: now). | | `screenId` | query | string | no | Only this screen. | ```bash curl "https://api.brixsignage.com/v1/uptime" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.from` | string \| null | | | `data.to` | string \| null | | | `data.offlineRetentionDays` | integer | How far back offline history is kept. | | `data.fleet` | object | | | `data.fleet.screenCount` | integer | | | `data.fleet.onlinePct` | number | 0–100. | | `data.fleet.outages` | integer | | | `data.fleet.mttrSec` | number \| null | Mean time to recover, in seconds; null with no recovered outage. | | `data.fleet.totalDowntimeSec` | number | | | `data.fleet.plannedDarkSec` | number | Downtime the screen was expected to be dark (a schedule or power policy). | | `data.fleet.plannedDarkOutages` | integer | | | `data.fleet.outageSummary` | OutageSummary | Outages in a window, by cause. | | `data.fleet.outageSummary.windowDays` | integer | | | `data.fleet.outageSummary.count` | integer | Unplanned outages in the window. | | `data.fleet.outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. | | `data.fleet.outageSummary.byBucket` | object | | | `data.fleet.outageSummary.topCause` | string \| null | | | `data.fleet.outageSummary.topCauseShare` | number | | | `data.fleet.outageSummary.hedgedShare` | number | | | `data.fleet.outageSummary.lastCause` | object \| null | | | `data.fleet.outageSummary.lastAt` | string \| null | | | `data.fleet.outageSummary.lastKnownCause` | object \| null | | | `data.fleet.outageSummary.avgRssiDbm` | number \| null | | | `data.fleet.outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` | | `data.fleet.screensWithOutages` | integer | | | `data.screens` | array of object | | | `data.screens[].screenId` | string | | | `data.screens[].screenName` | string | | | `data.screens[].nodeId` | string \| null | | | `data.screens[].locationLabel` | string \| null | | | `data.screens[].status` | "online" \| "offline" \| "pairing" | | | `data.screens[].lastSeenAt` | string \| null | | | `data.screens[].windowSec` | number | | | `data.screens[].downtimeSec` | number | | | `data.screens[].uptimeSec` | number | | | `data.screens[].onlinePct` | number | | | `data.screens[].outages` | integer | | | `data.screens[].mttrSec` | number \| null | | | `data.screens[].plannedDarkOutages` | integer | | | `data.screens[].plannedDarkSec` | number | | | `data.screens[].downtimeWindows` | array of object | | | `data.screens[].downtimeWindows[].from` | string | ISO-8601 timestamp (UTC). | | `data.screens[].downtimeWindows[].to` | string \| null | Null while the screen is still down. | | `data.screens[].downtimeWindows[].durationSec` | number | | | `data.screens[].downtimeWindows[].detectionPath` | string | How the outage was noticed, e.g. `ws-close`, `heartbeat-timeout`. | | `data.screens[].downtimeWindows[].cause` | string \| null | | | `data.screens[].downtimeWindows[].causeDetail` | string \| null | | | `data.screens[].downtimeWindows[].causeLabel` | string \| null | | | `data.screens[].downtimeWindows[].reason` | string \| null | | | `data.screens[].downtimeWindows[].expectedDark` | boolean \| null | | | `data.screens[].downtimeWindows[].expectedReason` | string \| null | | | `data.screens[].outageSummary` | OutageSummary | Outages in a window, by cause. | | `data.screens[].outageSummary.windowDays` | integer | | | `data.screens[].outageSummary.count` | integer | Unplanned outages in the window. | | `data.screens[].outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. | | `data.screens[].outageSummary.byBucket` | object | | | `data.screens[].outageSummary.topCause` | string \| null | | | `data.screens[].outageSummary.topCauseShare` | number | | | `data.screens[].outageSummary.hedgedShare` | number | | | `data.screens[].outageSummary.lastCause` | object \| null | | | `data.screens[].outageSummary.lastAt` | string \| null | | | `data.screens[].outageSummary.lastKnownCause` | object \| null | | | `data.screens[].outageSummary.avgRssiDbm` | number \| null | | | `data.screens[].outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` | | `data.locations` | array of object | | | `data.locations[].nodeId` | string \| null | | | `data.locations[].name` | string | | | `data.locations[].screenCount` | integer | | | `data.locations[].onlinePct` | number | | | `data.locations[].windowSec` | number | | | `data.locations[].downtimeSec` | number | | | `data.locations[].outages` | integer | | | `data.locations[].mttrSec` | number \| null | | | `data.locations[].outageSummary` | OutageSummary | Outages in a window, by cause. | | `data.locations[].outageSummary.windowDays` | integer | | | `data.locations[].outageSummary.count` | integer | Unplanned outages in the window. | | `data.locations[].outageSummary.byCause` | object | Outage count per cause; a cause with none is absent. | | `data.locations[].outageSummary.byBucket` | object | | | `data.locations[].outageSummary.topCause` | string \| null | | | `data.locations[].outageSummary.topCauseShare` | number | | | `data.locations[].outageSummary.hedgedShare` | number | | | `data.locations[].outageSummary.lastCause` | object \| null | | | `data.locations[].outageSummary.lastAt` | string \| null | | | `data.locations[].outageSummary.lastKnownCause` | object \| null | | | `data.locations[].outageSummary.avgRssiDbm` | number \| null | | | `data.locations[].outageSummary.insight` | string \| null | The rollup sentence, e.g. `All 6 were Wi-Fi drops.` | | `data.locations[].screensWithOutages` | integer | | Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 422: `from` or `to` is not an ISO-8601 timestamp. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Users 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/users List users Returns the workspace roster: each person's role, which locations they can access, their sign-in method, two-factor authentication status, and last login. **Notes.** - Not paginated. Deleted (erased) people are not listed. A caller whose access is limited to some locations sees only the people with access there, and only those locations in `access`. Auth: Bearer token. Permission: `user.view`. ```bash curl "https://api.brixsignage.com/v1/users" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of User | | | `data[].id` | string | | | `data[].name` | string | | | `data[].email` | string | | | `data[].status` | "active" \| "invited" \| "deactivated" | `invited` until the person sets a password or signs in. | | `data[].roleId` | string \| null | The role of the first entry in `access`; null when the person has no access. | | `data[].scope` | string | The location name of the first entry in `access`; `—` when none. | | `data[].loginMethod` | "sso" \| "passkey" \| "password" | How the person signs in. | | `data[].totpEnabled` | boolean | Two-factor authentication with an authenticator app is on. | | `data[].passkeyCount` | integer | | | `data[].lastLoginAt` | string \| null | | | `data[].access` | array of object | Each location the person can access and the role they hold there. Only locations the caller can see are listed. | | `data[].access[].id` | string | Role assignment (membership) id. Use it to change or remove this assignment at `/v1/org-nodes/{nodeId}/members/{id}`. | | `data[].access[].nodeId` | string | Location id. | | `data[].access[].nodeName` | string | Location name; `—` when the location no longer exists. | | `data[].access[].roleId` | string | | | `data[].access[].roleName` | string | Role name; `—` when the role no longer exists. | | `data[].contentScope` | "all" \| "shared" \| null | This person's own content setting: `all`, `shared` (only content shared with them plus their own locations' content), or `null` = their roles' default. | | `data[].contentScopeEffective` | "all" \| "shared" | The content setting that applies now (person > roles > workspace default, which is `shared` unless the workspace chose `all`; an Owner and people seated at head office always `all` unless their own row says `shared`). | | `data[].contentScopeSource` | "person" \| "role" \| "workspace" \| "owner" \| "headOffice" | Where `contentScopeEffective` comes from. `headOffice`: the person holds a role at the workspace level, which always sees head office content. | 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. ### PATCH /v1/users/{id} Update user Updates a person's profile. Supported fields are `name` and `trainingStep` (which resets a feature walkthrough for that person). Email address and account status cannot be changed through this operation. Requires access to every location the target person belongs to. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Trimmed; must not be empty. | | `trainingStep` | string \| null | no | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`); null resets it. | | `contentScope` | "all" \| "shared" \| null | no | What content this person sees: `all`, `shared` (only content shared with them plus their own locations' content) or `null` (their roles' default). Never on your own row (403), never by a connected app (403), never `shared` on an Owner (422). | ```bash curl -X PATCH "https://api.brixsignage.com/v1/users/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.email` | string | | | `data.name` | string | | | `data.status` | "active" \| "invited" \| "deactivated" | | | `data.trainingStep` | string \| null | Walkthrough position; null when not started or reset. | | `data.contentScope` | "all" \| "shared" \| null | This person's own content setting after the update. | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`. Response 404: No such person in this workspace. Response 422: Nothing to update, an empty or over-long `name`, or an unknown `trainingStep`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/users/{id}/deactivate Deactivate user Deactivates a person's account. This revokes all of their active sessions, signing them out everywhere immediately and blocking further sign-in including through SSO, and removes them from every location's approver list. This action is reversible. You cannot deactivate your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner. **Notes.** - Only an owner can deactivate an owner, and nobody can deactivate a person who holds a permission they do not hold. An API key is never an owner, whatever its permissions. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | ```bash curl -X POST "https://api.brixsignage.com/v1/users/{id}/deactivate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.status` | "deactivated" | | | `data.deactivatedAt` | string | ISO-8601 timestamp (UTC). | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it. Response 404: No such person in this workspace. Response 409: `cant_deactivate_self`, `already_deactivated`, or `last_owner` (the last owner of the workspace or of a location). Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/users/{id}/erase Erase user under GDPR Permanently erases a deactivated person's personal data to satisfy a right-to-be-forgotten request: it anonymizes their profile and hard-deletes their passkeys, linked identities, sessions, and location role assignments. The account must already be deactivated. You cannot erase your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner. **Notes.** - Irreversible. The same rule as deactivation applies: only an owner can erase an owner, and the caller must hold every permission the person holds. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | ```bash curl -X POST "https://api.brixsignage.com/v1/users/{id}/erase" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.erased` | true | | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it. Response 404: No such person in this workspace (an erased person is not found again). Response 409: `cant_erase_self`, `last_owner`, or `must_deactivate_first`. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/users/{id}/reactivate Reactivate user Restores a deactivated person's account to active status. A person who never accepted their invite goes back to invited status. Their previous role assignments are restored along with the access they grant. Any approver-list entries removed at deactivation are not automatically restored. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | ```bash curl -X POST "https://api.brixsignage.com/v1/users/{id}/reactivate" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.status` | "active" \| "invited" | `invited` when the person never accepted their invite (never signed in, set a password or confirmed their email). | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it. Response 404: No such person in this workspace. Response 409: `not_deactivated`: the person is not deactivated. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/users/{id}/sessions List user sessions Returns a person's currently active sign-in sessions: id, creation time, last used time, expiry, device or browser, IP address, and which session belongs to the caller. Revoked and expired sessions are not included. **Notes.** - Needs `user.edit`, not `user.view`: the rows carry IP addresses. Sorted by last use, newest first. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | ```bash curl "https://api.brixsignage.com/v1/users/{id}/sessions" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of UserSession | | | `data[].id` | string | Session id (not the session token, which is never returned). | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].lastUsedAt` | string \| null | | | `data[].expiresAt` | string | ISO-8601 timestamp (UTC). | | `data[].userAgent` | string \| null | The browser or device that signed in. | | `data[].ipAddress` | string \| null | | | `data[].current` | boolean | This is the session making the call (always false for an API key). | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`. Response 404: No such person in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/users/{id}/sessions/{sessionId} Revoke user session Signs one of a person's devices out by revoking that session. The session record itself is kept, not deleted. Calling this on an already-revoked session is safe and reports `revoked: false`. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | | `sessionId` | path | string | yes | Session id from the session list. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/users/{id}/sessions/{sessionId}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.revoked` | boolean | False when the session was already revoked. | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`. Response 404: No such person, or no such session for this person. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/users/{id}/sessions/revoke-all Revoke all user sessions Signs a person out of every active session without deactivating their account, so they can still sign back in afterward. Returns the number of sessions that were revoked. Auth: Bearer token. Permission: `user.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | User id. | ```bash curl -X POST "https://api.brixsignage.com/v1/users/{id}/sessions/revoke-all" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | User id. | | `data.revoked` | integer | Sessions revoked. | Response 401: Missing, expired or revoked bearer token. Response 403: The person belongs to a location where you do not hold `user.edit`. Response 404: No such person in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/users/invite Invite user Creates a new person in the workspace, or reuses an existing one, and assigns them a role at the chosen locations. A new person gets an email with a link to set their password. When a signed-in user sends the invite, the email goes out only when that user's own email address is verified. An invite made with an API key sends the email in the workspace's name. You cannot grant a role carrying permissions you do not hold yourself. **Notes.** - Answers 200 (not 201) for a new person too; `created` tells the two apart. - For a signed-in user, the set-password email is sent only when that user's own email address is verified. If it is not, that user gets an email to confirm their address, and the held set-password email goes out when they open the link. An invite made with an API key sends the email too, from the workspace (the key's name is not shown). The 30-a-minute limit counts per key for a key. Auth: Bearer token. Permission: `user.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | yes | Stored in lower case. | | `name` | string | no | Used only when the person is new. | | `roleId` | string | yes | | | `nodeIds` | array of string | yes | Locations to grant the role at. You need `user.edit` and every permission of the role at each one. | ```bash curl -X POST "https://api.brixsignage.com/v1/users/invite" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"sam@example.com","name":"Sam Rivera","roleId":"role_5e6f7a8b9c0d1e2f","nodeIds":["on_4d5e6f7a8b9c0d1e"]}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.email` | string | | | `data.status` | "active" \| "invited" \| "deactivated" | | | `data.created` | boolean | True when a new person was created; false when an existing person got the extra access. | | `data.emailSent` | boolean | A set-password email went out. | | `data.emailBlockedReason` | "inviter-unverified" \| "provider-refused" \| null | Why no email went out for a new person: the calling user's own email address is not verified (never for an API key), or the mail provider refused it. Null when sent, or when the person already existed. | Response 401: Missing, expired or revoked bearer token. Response 403: The role holds permissions you do not hold, or you lack `user.edit` or the role's permissions at one of the locations. Response 404: No such role or location in this workspace. Response 422: Invalid `email`, or `roleId` / `nodeIds` missing. Response 429: More than 30 invites a minute. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Web recorder 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/web-recorder/{sid} Get a recording session Return the steps recorded so far in an in-progress sign-in recording session. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sid` | path | string | yes | Recording session id, from `start`. | ```bash curl "https://api.brixsignage.com/v1/web-recorder/{sid}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | The page the recording is on now. | | `data.steps` | array of RecordedStep | | | `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. | | `data.steps[].url` | string | | | `data.steps[].selector` | string | | | `data.steps[].label` | string | | | `data.steps[].value` | string | Typed text that is not secret. | | `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. | | `data.steps[].pixels` | number | | | `data.steps[].ms` | number | | | `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). | | `data.spaceId` | string | | 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 active session with this id in this workspace (it expired, was finished, or never started). Response 503: Recording is not available in this environment. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/web-recorder/{sid}/abort Cancel a recording Discard an in-progress sign-in recording session without changing the associated media asset. **Notes.** - Always answers `{ ok: true }`, for an unknown session too. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sid` | path | string | yes | Recording session id, from `start`. | ```bash curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/abort" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | 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/web-recorder/{sid}/action Record a sign-in step Append one recorded interaction, such as a click, typed text, or a wait, to an open sign-in recording session. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sid` | path | string | yes | Recording session id, from `start`. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `kind` | "click" \| "type" \| "scroll" \| "navigate" \| "accept-cookies" \| "wait" \| "pick" | yes | | | `selector` | string | no | | | `label` | string | no | | | `text` | string | no | For `type`: the typed text (not stored when `isSecret`). | | `isSecret` | boolean | no | For `type`: store a reference instead of the text. | | `url` | string | no | | | `dy` | number | no | | | `ms` | number | no | | | `mode` | string | no | | | `x` | number | no | | | `y` | number | no | | ```bash curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/action" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | The page the recording is on now. | | `data.steps` | array of RecordedStep | | | `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. | | `data.steps[].url` | string | | | `data.steps[].selector` | string | | | `data.steps[].label` | string | | | `data.steps[].value` | string | Typed text that is not secret. | | `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. | | `data.steps[].pixels` | number | | | `data.steps[].ms` | number | | | `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). | | `data.spaceId` | string | | Response 400: The body is not JSON. 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 active session with this id in this workspace (it expired, was finished, or never started). Response 503: Recording is not available in this environment. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/web-recorder/{sid}/finalize Save a recorded sign-in Save a completed recording to a web asset, using mediaId and optional secrets. The recorded steps are stored on the asset's web configuration, secrets are encrypted and referenced by name, and the session ends. **Notes.** - The asset's sign-in is replayed later to refresh its cookies; call `links/:mediaId/verify` to test it now. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sid` | path | string | yes | Recording session id, from `start`. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `mediaId` | string | yes | The web page asset to save the steps to. | | `secrets` | object | no | `valueRef` → secret value. Encrypted; never returned. Null or empty removes one. | | `expect` | object | no | The asset's `url` and `webConfig` as you last read them. The save is refused (409) if the address or sign-in steps changed since, so secrets are never stored for a link you did not see. | | `expect.url` | string | yes | | | `expect.webConfig` | any | yes | | | `removeSteps` | array of integer | no | Indices into the session's steps to leave out of the saved recording. | ```bash curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/finalize" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.ok` | true | | | `data.stepCount` | integer | | | `data.steps` | array of RecordedStep | The steps saved on the asset (the session's, minus `removeSteps`). | | `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. | | `data.steps[].url` | string | | | `data.steps[].selector` | string | | | `data.steps[].label` | string | | | `data.steps[].value` | string | Typed text that is not secret. | | `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. | | `data.steps[].pixels` | number | | | `data.steps[].ms` | number | | | `data.secretRefs` | array of object | Every secret step, so you can send values you have not sent yet. | | `data.secretRefs[].ref` | string | | | `data.secretRefs[].label` | string | | Response 400: `mediaId` is missing. Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `media.edit` where the asset lives. Response 404: The session expired or never started, or no such asset. Response 409: The asset's address or sign-in steps changed (or are not what `expect` says). Nothing was saved. Response 503: Recording is not available in this environment. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/web-recorder/links/{mediaId}/verify Test a recorded sign-in Run the finalized sign-in recording for a web asset and report whether the resulting session looks successfully logged in. This lets a caller confirm the recording works right after capturing it, rather than waiting until the content plays on a screen. **Notes.** - Runs the sign-in in a headless browser now (this can take 30 seconds or more). Answers 200 with `ok: false` when it fails. Auth: Bearer token. Permission: `media.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `mediaId` | path | string | yes | Web page asset id. | ```bash curl -X POST "https://api.brixsignage.com/v1/web-recorder/links/{mediaId}/verify" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object \| object | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `media.edit` where the asset lives. Response 503: The headless browser is not available. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/web-recorder/start Start recording a sign-in Begin a sign-in recording session for a web asset, given a url. Returns a session id, the url, and the steps recorded so far, which starts empty. Steps are then submitted using the Brix Recorder browser extension. **Notes.** - The recorder browser extension then sends each step with `action`. Invalid input answers 400, not 422. Auth: Bearer token. Permission: `media.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | yes | The sign-in page (http or https, a public host). | ```bash curl -X POST "https://api.brixsignage.com/v1/web-recorder/start" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.url` | string | The page the recording is on now. | | `data.steps` | array of RecordedStep | | | `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. | | `data.steps[].url` | string | | | `data.steps[].selector` | string | | | `data.steps[].label` | string | | | `data.steps[].value` | string | Typed text that is not secret. | | `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. | | `data.steps[].pixels` | number | | | `data.steps[].ms` | number | | | `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). | | `data.spaceId` | string | | | `data.sid` | string | | | `data.ok` | true | | Response 400: `url` is not http(s), or not a public address. Response 401: Missing, expired or revoked bearer token. Response 403: The token lacks the permission this operation needs (see `x-brix-permission`). Response 503: Recording is not available in this environment. Response 5XX: Server error. The body carries a `requestId` to quote to support. ## Webhooks 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/webhooks List webhook endpoints List the workspace's outbound webhook endpoints. The signing secret is never included in this response; it is shown only once, at creation. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `integration.edit`. ```bash curl "https://api.brixsignage.com/v1/webhooks" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of WebhookEndpoint | | | `data[].id` | string | Webhook endpoint id. | | `data[].url` | string | Where deliveries are POSTed. | | `data[].description` | string \| null | | | `data[].secretPreview` | string | First 8 characters of the signing secret. | | `data[].events` | array of string | Subscribed event names (see `GET /v1/webhooks/events`). | | `data[].enabled` | boolean | | | `data[].autoDisabledAt` | string \| null | Set when repeated failures switched the endpoint off. | | `data[].autoDisabledReason` | string \| null | | | `data[].consecutiveFailures` | integer | | | `data[].lastDeliveryAt` | string \| null | | | `data[].lastStatus` | integer \| null | HTTP status of the last delivery attempt. | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].updatedAt` | string | ISO-8601 timestamp (UTC). | 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/webhooks Create a webhook endpoint Create an endpoint. The response includes the signing secret once; after that, only a preview of it is available, since it is stored encrypted and cannot be retrieved in full. The endpoint URL is checked at creation and again before every delivery, since a hostname that resolved to a public address at save time could later be re-pointed at an internal address. Only `content.recalled` and `content.restored` events are actually sent today, even though the event catalog lists more. The response carries the signing `secret` ONCE. Store it: later reads return only `secretPreview`. **Notes.** - Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`. Auth: Bearer token. Permission: `integration.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | yes | An https URL on the public internet (private and loopback hosts are refused). | | `events` | array of "screen.offline" \| "screen.online" \| "content.recalled" \| "content.restored" \| "approval.requested" \| "approval.decided" \| "emergency.started" \| "emergency.cleared" | no | Events to deliver. Default: none. An unknown name is refused. | | `description` | string | no | Label; cut to 200 characters. | ```bash curl -X POST "https://api.brixsignage.com/v1/webhooks" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://hooks.example.com/brix","events":["screen.offline","screen.online"],"description":"Ops alerts"}' ``` Response 201: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | Webhook endpoint id. | | `data.url` | string | Where deliveries are POSTed. | | `data.description` | string \| null | | | `data.secretPreview` | string | First 8 characters of the signing secret. | | `data.events` | array of string | Subscribed event names (see `GET /v1/webhooks/events`). | | `data.enabled` | boolean | | | `data.autoDisabledAt` | string \| null | Set when repeated failures switched the endpoint off. | | `data.autoDisabledReason` | string \| null | | | `data.consecutiveFailures` | integer | | | `data.lastDeliveryAt` | string \| null | | | `data.lastStatus` | integer \| null | HTTP status of the last delivery attempt. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | | `data.secret` | string | The HMAC signing secret (64 hex characters). Shown only in this response. | ```json { "data": { "id": "whe_7a8b9c0d1e2f3a4b", "url": "https://hooks.example.com/brix", "description": "Ops alerts", "secretPreview": "3f9a1c2e", "events": [ "screen.offline", "screen.online" ], "enabled": true, "autoDisabledAt": null, "autoDisabledReason": null, "consecutiveFailures": 0, "lastDeliveryAt": null, "lastStatus": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "secret": "3f9a1c2e4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f" } } ``` Response 400: `bad_request` (missing url, unknown event) or `unsafe_url`. 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. ### PATCH /v1/webhooks/{id} Update a webhook endpoint Change a webhook endpoint's URL, event subscriptions, description, or enabled state. Re-enabling an endpoint clears any automatic disable and resets its failure count, since re-enabling means the receiver has been confirmed fixed. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. - Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Webhook endpoint id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | no | An https URL on the public internet. | | `events` | array of "screen.offline" \| "screen.online" \| "content.recalled" \| "content.restored" \| "approval.requested" \| "approval.decided" \| "emergency.started" \| "emergency.cleared" | no | Replaces the subscription. An unknown name is refused. | | `description` | string | no | Cut to 200 characters. | | `enabled` | boolean | no | `true` also clears an automatic switch-off and the failure count. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/webhooks/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":true}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | WebhookEndpoint | A customer webhook endpoint. The signing secret is never returned after creation. | | `data.id` | string | Webhook endpoint id. | | `data.url` | string | Where deliveries are POSTed. | | `data.description` | string \| null | | | `data.secretPreview` | string | First 8 characters of the signing secret. | | `data.events` | array of string | Subscribed event names (see `GET /v1/webhooks/events`). | | `data.enabled` | boolean | | | `data.autoDisabledAt` | string \| null | Set when repeated failures switched the endpoint off. | | `data.autoDisabledReason` | string \| null | | | `data.consecutiveFailures` | integer | | | `data.lastDeliveryAt` | string \| null | | | `data.lastStatus` | integer \| null | HTTP status of the last delivery attempt. | | `data.createdAt` | string | ISO-8601 timestamp (UTC). | | `data.updatedAt` | string | ISO-8601 timestamp (UTC). | ```json { "data": { "id": "whe_7a8b9c0d1e2f3a4b", "url": "https://hooks.example.com/brix", "description": "Ops alerts", "secretPreview": "3f9a1c2e", "events": [ "screen.offline", "screen.online" ], "enabled": true, "autoDisabledAt": null, "autoDisabledReason": null, "consecutiveFailures": 0, "lastDeliveryAt": null, "lastStatus": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z" } } ``` Response 400: `bad_request` (unknown event) or `unsafe_url`. 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 endpoint in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### DELETE /v1/webhooks/{id} Delete a webhook endpoint. Any deliveries still pending for it are abandoned rather than retried. **Notes.** - Answers `{ data: { id } }` — without the `deleted: true` most other deletes return. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Webhook endpoint id. | ```bash curl -X DELETE "https://api.brixsignage.com/v1/webhooks/{id}" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | 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 endpoint in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### POST /v1/webhooks/{id}/test Send a test webhook delivery Send a real, signed sample delivery to this endpoint now. It is a genuine delivery rather than a simulation, so it exercises the same signature verification your receiver uses in production. The payload has the same fields as a real event of that type, filled from one of your screens where possible, plus `test: true`. Pick the event with `event` in the body; by default the test uses the first event the endpoint is subscribed to. This call returns 409 if the endpoint is not subscribed to that event. Sends a real, signed delivery of one subscribed event now and records it in the delivery log. `data` carries every documented key of that event (the same shape a real event has), filled from a screen in the workspace when there is one and with sample values otherwise, plus `test: true`. A failed send is NOT an HTTP error: the answer is 200 with `ok: false`. **Notes.** - A test payload has `data.test: true`. Real events never carry `test`. - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Webhook endpoint id. | Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `event` | "screen.offline" \| "screen.online" \| "content.recalled" \| "content.restored" \| "approval.requested" \| "approval.decided" \| "emergency.started" \| "emergency.cleared" | no | The event to test. Default: the first event the endpoint is subscribed to. | ```bash curl -X POST "https://api.brixsignage.com/v1/webhooks/{id}/test" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.deliveryId` | string | Id of the delivery this call made (a new `whd_…` row in the delivery log). | | `data.ok` | boolean | The receiver answered 2xx. | | `data.status` | integer \| null | HTTP status the receiver answered with; null when no answer came. | | `data.error` | string \| null | Why the delivery failed (`http 500`, a timeout, an unsafe address); null on success. | | `data.event` | "screen.offline" \| "screen.online" \| "content.recalled" \| "content.restored" \| "approval.requested" \| "approval.decided" \| "emergency.started" \| "emergency.cleared" | The event the test delivery sent. | Response 400: `bad_request`: `event` is not a webhook event. 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 endpoint in this workspace. Response 409: `not_subscribed`: the endpoint is not subscribed to `event` (or to any event), or it is switched off. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/webhooks/deliveries List webhook deliveries List the webhook delivery log: what was sent, the response received, the number of attempts, and what is still pending. Each entry includes the exact payload that was sent. Results are paginated and can be filtered by endpoint and status. Failed deliveries are retried with increasing delay over roughly 8 to 12 hours before they are given up on. **Notes.** - Always paged: without `?limit` a page has 50 deliveries (not every row, unlike the lists that page only on request), and `nextCursor` is always present. - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | string | no | Page size, 1–200. Default 50. | | `cursor` | query | string | no | The `nextCursor` of the previous page. | | `endpointId` | query | string | no | Only this endpoint's deliveries. | | `status` | query | "pending" \| "delivered" \| "failed" \| "abandoned" | no | Only deliveries in this state. Another value is ignored. | ```bash curl "https://api.brixsignage.com/v1/webhooks/deliveries" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of WebhookDelivery | Newest first. | | `data[].id` | string | Webhook delivery id. | | `data[].endpointId` | string | | | `data[].event` | string | | | `data[].status` | "pending" \| "delivered" \| "failed" \| "abandoned" | `failed` is retried later; `abandoned` is not retried again. | | `data[].attempts` | integer | | | `data[].occurredAt` | string | ISO-8601 timestamp (UTC). | | `data[].createdAt` | string | ISO-8601 timestamp (UTC). | | `data[].nextAttemptAt` | string \| null | When the next retry is due; null when none is. | | `data[].deliveredAt` | string \| null | | | `data[].responseStatus` | integer \| null | | | `data[].error` | string \| null | | | `data[].replayOf` | string \| null | Set on a delivery made by a replay: the delivery it resends. | | `data[].payload` | object \| null | The JSON body as it was sent; null if the stored copy cannot be read. | | `nextCursor` | string \| null | Send it back as `?cursor=` for the next page; null on the last page. | 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/webhooks/deliveries/{id}/replay Replay a webhook delivery Resend a delivery as a new delivery with its own id and a `replayOf` field pointing at the original. The original delivery record is left unchanged, so a receiver that deduplicates on delivery id will not silently ignore the resend. Sends the payload again now, as a new delivery. A failed send is NOT an HTTP error: the answer is 200 with `ok: false`. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. Auth: Bearer token. Permission: `integration.edit`. Parameters: | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | yes | Id of the delivery to send again. | ```bash curl -X POST "https://api.brixsignage.com/v1/webhooks/deliveries/{id}/replay" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.deliveryId` | string | Id of the delivery this call made (a new `whd_…` row in the delivery log). | | `data.ok` | boolean | The receiver answered 2xx. | | `data.status` | integer \| null | HTTP status the receiver answered with; null when no answer came. | | `data.error` | string \| null | Why the delivery failed (`http 500`, a timeout, an unsafe address); null on success. | 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 delivery in this workspace. Response 5XX: Server error. The body carries a `requestId` to quote to support. ### GET /v1/webhooks/events List subscribable webhook events List the catalog of event types that can be subscribed to, each with a label and a description of what it carries. Only `content.recalled` and `content.restored` events are actually sent today; other listed events are not yet emitted. **Notes.** - `data` per event — screen.offline: screenId, screenName, status, nodeId, nodeName, lastSeenAt, upForSec, scheduledOff. screen.online: screenId, screenName, status, nodeId, nodeName, lastSeenAt, offlineSince, offlineForSec. approval.requested: requestId, contentKind, contentId, contentName, nodeId, nodeName, requestedById, requestedByName, requestedAt, note. approval.decided: the same plus decision (approved | rejected | withdrawn), decidedById, decidedByName, decidedAt, decisionNote. emergency.started: emergencyId, headline, body, severity, contentKind, contentId, scopeKind, scopeNodeId, scopeName, screenCount, triggeredById, triggeredByName, triggeredAt, expiresAt, templateId, templateName. emergency.cleared: the same plus clearedAt, clearedById, clearedByName, reason (cleared | expired | replaced | content-deleted). content.recalled: kind, id, name, reason, recalledBy. content.restored: kind, id, name. - screen.offline is sent once per outage, when Brix marks the screen offline (seconds after a socket drop, up to 45 minutes for a screen that reports only by heartbeat). A screen that drops again before it is back is the same outage. screen.online follows when it reports again, within about 5 minutes. Auth: Bearer token. Permission: `integration.view`. ```bash curl "https://api.brixsignage.com/v1/webhooks/events" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | array of object | | | `data[].event` | "screen.offline" \| "screen.online" \| "content.recalled" \| "content.restored" \| "approval.requested" \| "approval.decided" \| "emergency.started" \| "emergency.cleared" | | | `data[].label` | string | | | `data[].what` | string | What the event means and carries. | | `data[].fields` | array of string | The keys of the delivery's `data` object. Every key is always sent (null when unknown). Keys are added over time, never renamed or removed. | 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. ## Workspace 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](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md). 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/workspace Get the workspace Returns the calling workspace's id and name. Auth: Bearer token. Permission: `screen.view`. ```bash curl "https://api.brixsignage.com/v1/workspace" \ -H "Authorization: Bearer $BRIX_API_KEY" ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | WorkspaceRef | | | `data.id` | string | Workspace id. | | `data.name` | string \| null | Workspace name; null only if the workspace row is missing. | 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. ### PATCH /v1/workspace Rename workspace Renames the workspace. The name must be non-empty and no more than 120 characters. Requires permission to edit billing for the whole workspace. **Notes.** - Only `name` can be changed here. Auth: Bearer token. Permission: `billing.edit`. Request body: `application/json` | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Trimmed; 1–120 characters. | ```bash curl -X PATCH "https://api.brixsignage.com/v1/workspace" \ -H "Authorization: Bearer $BRIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Riverside Coffee"}' ``` Response 200: Success. | Field | Type | Description | | --- | --- | --- | | `data` | object | | | `data.id` | string | | | `data.name` | string | | Response 401: Missing, expired or revoked bearer token. Response 403: You do not hold `billing.edit` for the whole workspace (a grant at one location is not enough). Response 422: `invalid`: `name` missing, empty or over 120 characters. Response 5XX: Server error. The body carries a `requestId` to quote to support.