Playlists API (part 3 of 3)
Playlists endpoints in the Brix REST API, part 3 of 3: 6 operations from /v1/playlists/{id}/items/{itemId}, each with auth, permission and curl.
View as Markdown · For AI agents: the full docs index is at /llms.txt
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, Errors and rate limits and Pagination.
Playlists is split into 3 pages: part 1 (/v1/playlists to /v1/playlists/{id}), part 2 (/v1/playlists/{id}/allocations to /v1/playlists/{id}/items), part 3 (/v1/playlists/{id}/items/{itemId} to /v1/playlists/bulk-delete).
PATCH /v1/playlists/{id}/items/{itemId}DELETE /v1/playlists/{id}/items/{itemId}POST /v1/playlists/{id}/items/batchPOST /v1/playlists/{id}/restoreGET /v1/playlists/{id}/share-readinessPOST /v1/playlists/bulk-delete
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. |
PATCH /v1/playlists/{id}/items/{itemId}
Edit one playlist item's duration, loop count, fit, full-screen setting, screen tag rules or allocation. refKind and refId cannot be changed on an existing item; delete it and add a new item to point at different content.
Notes.
- An unknown itemId is not refused: nothing changes and the answer is 200 with the playlist.
- targetTags and excludeTags are stored but not returned on the items.
- Fields of the wrong type are ignored rather than refused.
- The returned playlist row (updatedAt, approvalState) is the one read before this edit; an approved playlist is returned to draft in storage by this call. Re-read with GET to see it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Playlist id. |
itemId | path | string | yes | Playlist item id. |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
durationMode | "fixed" | "full" | "live" | "loop" | "manual" | no | |
durationSeconds | number | no | Dwell for fixed, rounded and clamped to 1 second through 24 hours. |
loopCount | number | no | Plays per turn for loop; rounded. |
fit | "contain" | "cover" | "fill" | "blur-fill" | null | no | The item's own fit; null = follow the file's fit. |
fullscreen | boolean | no | Take over the whole screen, over any layout. |
playOnlyWhenTapped | boolean | no | Skip it in the rotation; show it only from a show-design tap. |
targetTags | array of string | null | no | Play only on screens with one of these tags. null or [] clears the rule. |
excludeTags | array of string | null | no | Never play on screens with one of these tags. null or [] clears the rule. |
allocationId | string | null | no | Put the item in one of this playlist's allocations; null = the base rotation. |
curl -X PATCH "https://api.brixsignage.com/v1/playlists/{id}/items/{itemId}" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | Playlist | A playlist with its ordered items. |
data.id | string | Playlist id. |
data.spaceId | string | |
data.name | string | |
data.description | string | |
data.shuffle | boolean | |
data.fullscreen | boolean | |
data.transition | "none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | null | Change between items: fade crossfades, slide-* pushes the next item in from that side, zoom fades it in from slightly larger; null cuts (the default). |
data.transitionMs | integer | null | How long the transition runs, in ms; null = the default 450. |
data.startsAt | string | null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. |
data.expiresAt | string | null | Stops after this date (YYYY-MM-DD) or time, stored as sent. |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Only approved content airs where the location requires approval. |
data.nodeId | string | null | Home location; null = workspace root. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | |
data.fit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.approvedSnapshot | string | null | Internal: the approved version, as stored JSON text. |
data.importSourceId | string | null | |
data.copySourceId | string | null | The partner library item this was copied from (Copy to client workspace), or null. |
data.folderId | string | null | Content folder (GET /v1/content-folders); null = the list's top level. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.usedByScreenCount | integer | |
data.usedByScreens | array of object | Up to 12 screens playing it. |
data.usedByScreens[].id | string | |
data.usedByScreens[].name | string | |
data.allocations | array of PlaylistAllocation | |
data.allocations[].id | string | |
data.allocations[].label | string | |
data.allocations[].ownerKind | "user" | "group" | "org-unit" | |
data.allocations[].ownerId | string | |
data.allocations[].ownerName | string | |
data.allocations[].kind | "percent" | "every-nth" | "daypart" | |
data.allocations[].value | integer | |
data.allocations[].endValue | integer | Absent (not null) when unset. |
data.allocations[].colorClass | string | |
data.allocations[].fillSpaceId | string | null | |
data.allocations[].fillPlaylistId | string | null | |
data.allocations[].unfilledBehavior | "collapse" | "filler" | "holding" | |
data.allocations[].fillerRefKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null | |
data.allocations[].fillerRefId | string | null | |
data.allocations[].requiresApproval | boolean | |
data.items | array of PlaylistItem | |
data.items[].id | string | Playlist item id. |
data.items[].refKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | |
data.items[].refId | string | The media / app instance / layout / playlist id. |
data.items[].name | string | |
data.items[].thumbnailUrl | string | Empty string when there is none. |
data.items[].kind | string | The media kind for media items; app, layout or playlist otherwise. |
data.items[].nestedItemCount | integer | null | Nested playlists only: its top-level item count. |
data.items[].nestedShuffle | boolean | null | Nested playlists only: whether that playlist plays its items in shuffled order. |
data.items[].sharedFrom | string | null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. |
data.items[].repeatLoop | object | null | A design that repeats for each row: what it really plays. durationSeconds does not apply to it. Null otherwise. |
data.items[].durationMode | "fixed" | "full" | "live" | "loop" | "manual" | |
data.items[].durationSeconds | integer | Dwell in seconds for fixed. |
data.items[].loopCount | integer | |
data.items[].loopDurationMs | integer | null | |
data.items[].mediaDurationSec | number | null | |
data.items[].pageCount | integer | null | A PowerPoint or PDF item: the number of pages it shows. The item's seconds are split across them. Null for other items. |
data.items[].fit | "contain" | "cover" | "fill" | "blur-fill" | null | The item's own fit; null = inherit. |
data.items[].assetFit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.items[].assetStartsAt | string | null | |
data.items[].assetExpiresAt | string | null | |
data.items[].assetActive | boolean | null | |
data.items[].fullscreen | boolean | |
data.items[].playOnlyWhenTapped | boolean | The rotation skips this item; a design's show-design tap action shows it. |
data.items[].withheld | "expired" | "archived" | "not-yet" | null | Why a media item is not airing now, or null. |
data.items[].allocationId | string | null | |
data.items[].position | integer | |
data.sharedIn | true | Present when the playlist is outside your locations and was shared in. |
Response 401: Missing, expired or revoked bearer token.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 404: No such playlist in this workspace.
Response 422: allocationId is not one of this playlist's allocations, or nothing to update.
Response 5XX: Server error. The body carries a requestId to quote to support.
DELETE /v1/playlists/{id}/items/{itemId}
Remove one item from a playlist. The remaining items keep their existing order.
Removes the item and closes the gap in the positions. Returns the whole playlist.
Notes.
- An unknown itemId is not refused: nothing is removed and the answer is 200 with the playlist.
- The returned playlist row (updatedAt, approvalState) is the one read before this edit; an approved playlist is returned to draft in storage by this call. Re-read with GET to see it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Playlist id. |
itemId | path | string | yes | Playlist item id. |
curl -X DELETE "https://api.brixsignage.com/v1/playlists/{id}/items/{itemId}" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | Playlist | A playlist with its ordered items. |
data.id | string | Playlist id. |
data.spaceId | string | |
data.name | string | |
data.description | string | |
data.shuffle | boolean | |
data.fullscreen | boolean | |
data.transition | "none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | null | Change between items: fade crossfades, slide-* pushes the next item in from that side, zoom fades it in from slightly larger; null cuts (the default). |
data.transitionMs | integer | null | How long the transition runs, in ms; null = the default 450. |
data.startsAt | string | null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. |
data.expiresAt | string | null | Stops after this date (YYYY-MM-DD) or time, stored as sent. |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Only approved content airs where the location requires approval. |
data.nodeId | string | null | Home location; null = workspace root. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | |
data.fit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.approvedSnapshot | string | null | Internal: the approved version, as stored JSON text. |
data.importSourceId | string | null | |
data.copySourceId | string | null | The partner library item this was copied from (Copy to client workspace), or null. |
data.folderId | string | null | Content folder (GET /v1/content-folders); null = the list's top level. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.usedByScreenCount | integer | |
data.usedByScreens | array of object | Up to 12 screens playing it. |
data.usedByScreens[].id | string | |
data.usedByScreens[].name | string | |
data.allocations | array of PlaylistAllocation | |
data.allocations[].id | string | |
data.allocations[].label | string | |
data.allocations[].ownerKind | "user" | "group" | "org-unit" | |
data.allocations[].ownerId | string | |
data.allocations[].ownerName | string | |
data.allocations[].kind | "percent" | "every-nth" | "daypart" | |
data.allocations[].value | integer | |
data.allocations[].endValue | integer | Absent (not null) when unset. |
data.allocations[].colorClass | string | |
data.allocations[].fillSpaceId | string | null | |
data.allocations[].fillPlaylistId | string | null | |
data.allocations[].unfilledBehavior | "collapse" | "filler" | "holding" | |
data.allocations[].fillerRefKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null | |
data.allocations[].fillerRefId | string | null | |
data.allocations[].requiresApproval | boolean | |
data.items | array of PlaylistItem | |
data.items[].id | string | Playlist item id. |
data.items[].refKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | |
data.items[].refId | string | The media / app instance / layout / playlist id. |
data.items[].name | string | |
data.items[].thumbnailUrl | string | Empty string when there is none. |
data.items[].kind | string | The media kind for media items; app, layout or playlist otherwise. |
data.items[].nestedItemCount | integer | null | Nested playlists only: its top-level item count. |
data.items[].nestedShuffle | boolean | null | Nested playlists only: whether that playlist plays its items in shuffled order. |
data.items[].sharedFrom | string | null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. |
data.items[].repeatLoop | object | null | A design that repeats for each row: what it really plays. durationSeconds does not apply to it. Null otherwise. |
data.items[].durationMode | "fixed" | "full" | "live" | "loop" | "manual" | |
data.items[].durationSeconds | integer | Dwell in seconds for fixed. |
data.items[].loopCount | integer | |
data.items[].loopDurationMs | integer | null | |
data.items[].mediaDurationSec | number | null | |
data.items[].pageCount | integer | null | A PowerPoint or PDF item: the number of pages it shows. The item's seconds are split across them. Null for other items. |
data.items[].fit | "contain" | "cover" | "fill" | "blur-fill" | null | The item's own fit; null = inherit. |
data.items[].assetFit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.items[].assetStartsAt | string | null | |
data.items[].assetExpiresAt | string | null | |
data.items[].assetActive | boolean | null | |
data.items[].fullscreen | boolean | |
data.items[].playOnlyWhenTapped | boolean | The rotation skips this item; a design's show-design tap action shows it. |
data.items[].withheld | "expired" | "archived" | "not-yet" | null | Why a media item is not airing now, or null. |
data.items[].allocationId | string | null | |
data.items[].position | integer | |
data.sharedIn | true | Present when the playlist is outside your locations and was shared in. |
Response 401: Missing, expired or revoked bearer token.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 404: No such playlist in this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/playlists/{id}/items/batch
Append several items in order as ONE change — { items: [<the POST /items body>, …] }, 1–50. Every item passes the same gates as POST /items; any refusal refuses the whole batch with that item's answer and index, and nothing is written. One audit row, one push. Takes idempotency-key. playlist.edit.
Appends 1 to 50 items in the order sent, as one change: each item passes the same checks as adding one item, and if any item is refused nothing is added. The refusal carries the item's place in the list as data.index. Returns the whole playlist. Send an Idempotency-Key header to make a retry safe: a repeat with the same key returns the stored answer and adds nothing.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Playlist id. |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object | yes | The items, each the body of POST /v1/playlists/{id}/items. |
items[].refKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | yes | |
items[].refId | string | yes | |
items[].durationMode | "fixed" | "full" | "live" | "loop" | "manual" | no | |
items[].durationSeconds | integer | no | |
items[].loopCount | number | no | |
items[].fit | string | no | contain, cover, fill or blur-fill; anything else means inherit. |
items[].fullscreen | boolean | no | |
items[].playOnlyWhenTapped | boolean | no | Skip it in the rotation; show it only from a show-design tap. Default false. |
items[].position | number | no | Accepted but ignored: the item is always appended. Reorder with PUT /v1/playlists/{id}/items. |
items[].allocationId | string | no |
curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/items/batch" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 201: Success.
| Field | Type | Description |
|---|---|---|
data | Playlist | A playlist with its ordered items. |
data.id | string | Playlist id. |
data.spaceId | string | |
data.name | string | |
data.description | string | |
data.shuffle | boolean | |
data.fullscreen | boolean | |
data.transition | "none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | null | Change between items: fade crossfades, slide-* pushes the next item in from that side, zoom fades it in from slightly larger; null cuts (the default). |
data.transitionMs | integer | null | How long the transition runs, in ms; null = the default 450. |
data.startsAt | string | null | Plays only from this date (YYYY-MM-DD) or time, stored as sent. |
data.expiresAt | string | null | Stops after this date (YYYY-MM-DD) or time, stored as sent. |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Only approved content airs where the location requires approval. |
data.nodeId | string | null | Home location; null = workspace root. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | |
data.fit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.approvedSnapshot | string | null | Internal: the approved version, as stored JSON text. |
data.importSourceId | string | null | |
data.copySourceId | string | null | The partner library item this was copied from (Copy to client workspace), or null. |
data.folderId | string | null | Content folder (GET /v1/content-folders); null = the list's top level. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.usedByScreenCount | integer | |
data.usedByScreens | array of object | Up to 12 screens playing it. |
data.usedByScreens[].id | string | |
data.usedByScreens[].name | string | |
data.allocations | array of PlaylistAllocation | |
data.allocations[].id | string | |
data.allocations[].label | string | |
data.allocations[].ownerKind | "user" | "group" | "org-unit" | |
data.allocations[].ownerId | string | |
data.allocations[].ownerName | string | |
data.allocations[].kind | "percent" | "every-nth" | "daypart" | |
data.allocations[].value | integer | |
data.allocations[].endValue | integer | Absent (not null) when unset. |
data.allocations[].colorClass | string | |
data.allocations[].fillSpaceId | string | null | |
data.allocations[].fillPlaylistId | string | null | |
data.allocations[].unfilledBehavior | "collapse" | "filler" | "holding" | |
data.allocations[].fillerRefKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null | |
data.allocations[].fillerRefId | string | null | |
data.allocations[].requiresApproval | boolean | |
data.items | array of PlaylistItem | |
data.items[].id | string | Playlist item id. |
data.items[].refKind | "media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | |
data.items[].refId | string | The media / app instance / layout / playlist id. |
data.items[].name | string | |
data.items[].thumbnailUrl | string | Empty string when there is none. |
data.items[].kind | string | The media kind for media items; app, layout or playlist otherwise. |
data.items[].nestedItemCount | integer | null | Nested playlists only: its top-level item count. |
data.items[].nestedShuffle | boolean | null | Nested playlists only: whether that playlist plays its items in shuffled order. |
data.items[].sharedFrom | string | null | The workspace that shares this item in, when it is not this workspace's own: the item plays that workspace's latest version and cannot be changed here. Empty string when its name is not readable; null for this workspace's own items. |
data.items[].repeatLoop | object | null | A design that repeats for each row: what it really plays. durationSeconds does not apply to it. Null otherwise. |
data.items[].durationMode | "fixed" | "full" | "live" | "loop" | "manual" | |
data.items[].durationSeconds | integer | Dwell in seconds for fixed. |
data.items[].loopCount | integer | |
data.items[].loopDurationMs | integer | null | |
data.items[].mediaDurationSec | number | null | |
data.items[].pageCount | integer | null | A PowerPoint or PDF item: the number of pages it shows. The item's seconds are split across them. Null for other items. |
data.items[].fit | "contain" | "cover" | "fill" | "blur-fill" | null | The item's own fit; null = inherit. |
data.items[].assetFit | "contain" | "cover" | "fill" | "blur-fill" | null | |
data.items[].assetStartsAt | string | null | |
data.items[].assetExpiresAt | string | null | |
data.items[].assetActive | boolean | null | |
data.items[].fullscreen | boolean | |
data.items[].playOnlyWhenTapped | boolean | The rotation skips this item; a design's show-design tap action shows it. |
data.items[].withheld | "expired" | "archived" | "not-yet" | null | Why a media item is not airing now, or null. |
data.items[].allocationId | string | null | |
data.items[].position | integer | |
data.sharedIn | true | Present when the playlist is outside your locations and was shared in. |
Response 401: Missing, expired or revoked bearer token.
Response 403: not_shared: an item's content is not available at the playlist's location (data.index names it).
Response 404: No such playlist, or an item's content is not in this workspace.
Response 422: Invalid body, a playlist loop, a layout with unbound zones, or an unknown allocation (data.index names the item).
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/playlists/{id}/restore
Restore a deleted playlist so its items and ordering return to the playlist library.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Playlist id. |
curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/restore" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.restored | true |
Response 401: Missing, expired or revoked bearer token.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 404: No such playlist in this workspace, or it was purged.
Response 409: not_deleted: the playlist is not in the recycle bin.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/playlists/bulk-delete
Move up to 500 playlists to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in ok and the rest in failed, so one failure does not stop the rest.
curl -X POST "https://api.brixsignage.com/v1/playlists/bulk-delete" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.
Response 5XX: Server error. The body carries a requestId to quote to support.