# Playlists (part 1 of 2)

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

Playlists is split into 2 pages: [part 1](https://brixsignage.com/developers/api/playlists.md) (`/v1/playlists` to `/v1/playlists/{id}/allocations`), [part 2](https://brixsignage.com/developers/api/playlists-2.md) (`/v1/playlists/{id}/duplicate` to `/v1/playlists/bulk-delete`).

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/playlists](#get-v1-playlists)
- [POST /v1/playlists](#post-v1-playlists)
- [GET /v1/playlists/{id}](#get-v1-playlists-id)
- [PATCH /v1/playlists/{id}](#patch-v1-playlists-id)
- [DELETE /v1/playlists/{id}](#delete-v1-playlists-id)
- [PUT /v1/playlists/{id}/allocations](#put-v1-playlists-id-allocations)

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.
