# Screens (part 4 of 4)

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

Screens is split into 4 pages: [part 1](https://brixsignage.com/developers/api/screens.md) (`/v1/screens` to `/v1/screens/{id}`), [part 2](https://brixsignage.com/developers/api/screens-2.md) (`/v1/screens/{id}` to `/v1/screens/{id}/mirror`), [part 3](https://brixsignage.com/developers/api/screens-3.md) (`/v1/screens/{id}/outages` to `/v1/screens/{id}/unpower-and-delete`), [part 4](https://brixsignage.com/developers/api/screens-4.md) (`/v1/screens/{id}/up-next` to `/v1/screens/touch-content`).

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

- [GET /v1/screens/{id}/up-next](#get-v1-screens-id-up-next)
- [GET /v1/screens/{id}/why](#get-v1-screens-id-why)
- [POST /v1/screens/bulk-assign](#post-v1-screens-bulk-assign)
- [POST /v1/screens/bulk-settings](#post-v1-screens-bulk-settings)
- [POST /v1/screens/claim](#post-v1-screens-claim)
- [POST /v1/screens/commands](#post-v1-screens-commands)
- [GET /v1/screens/count-by-status](#get-v1-screens-count-by-status)
- [POST /v1/screens/enroll](#post-v1-screens-enroll)
- [POST /v1/screens/heavy-check](#post-v1-screens-heavy-check)
- [GET /v1/screens/pair-cost](#get-v1-screens-pair-cost)
- [GET /v1/screens/pending](#get-v1-screens-pending)
- [POST /v1/screens/pending/{id}/dismiss](#post-v1-screens-pending-id-dismiss)
- [POST /v1/screens/pending/{id}/identify](#post-v1-screens-pending-id-identify)
- [POST /v1/screens/pending/claim](#post-v1-screens-pending-claim)
- [POST /v1/screens/pending/identify-all](#post-v1-screens-pending-identify-all)
- [GET /v1/screens/recycle-bin](#get-v1-screens-recycle-bin)
- [GET /v1/screens/touch-content](#get-v1-screens-touch-content)

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.