# Screen groups

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

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/screen-groups](#get-v1-screen-groups)
- [POST /v1/screen-groups](#post-v1-screen-groups)
- [GET /v1/screen-groups/{id}](#get-v1-screen-groups-id)
- [PATCH /v1/screen-groups/{id}](#patch-v1-screen-groups-id)
- [DELETE /v1/screen-groups/{id}](#delete-v1-screen-groups-id)
- [POST /v1/screen-groups/{id}/restore](#post-v1-screen-groups-id-restore)
- [POST /v1/screen-groups/{id}/screens](#post-v1-screen-groups-id-screens)
- [DELETE /v1/screen-groups/{id}/screens/{screenId}](#delete-v1-screen-groups-id-screens-screenid)
- [POST /v1/screen-groups/{id}/screens/remove](#post-v1-screen-groups-id-screens-remove)

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.
