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

Every 4xx and 5xx response below returns this body:

FieldTypeDescription
errorstringMachine-readable code: unauthorized, forbidden, not_found, validation_error, conflict, rate_limited, internal_error, …
messagestringHuman-readable explanation. Safe to show an operator.
requestIdstringPresent on 5xx: quote it to support.

PATCH /v1/playlists/{id}/items/{itemId}

Auth: Bearer token. Permission: playlist.edit.

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.

ParameterInTypeRequiredDescription
idpathstringyesPlaylist id.
itemIdpathstringyesPlaylist item id.

Request body: application/json

FieldTypeRequiredDescription
durationMode"fixed" | "full" | "live" | "loop" | "manual"no
durationSecondsnumbernoDwell for fixed, rounded and clamped to 1 second through 24 hours.
loopCountnumbernoPlays per turn for loop; rounded.
fit"contain" | "cover" | "fill" | "blur-fill" | nullnoThe item's own fit; null = follow the file's fit.
fullscreenbooleannoTake over the whole screen, over any layout.
playOnlyWhenTappedbooleannoSkip it in the rotation; show it only from a show-design tap.
targetTagsarray of string | nullnoPlay only on screens with one of these tags. null or [] clears the rule.
excludeTagsarray of string | nullnoNever play on screens with one of these tags. null or [] clears the rule.
allocationIdstring | nullnoPut 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.

FieldTypeDescription
dataPlaylistA playlist with its ordered items.
data.idstringPlaylist id.
data.spaceIdstring
data.namestring
data.descriptionstring
data.shuffleboolean
data.fullscreenboolean
data.transition"none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | nullChange 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.transitionMsinteger | nullHow long the transition runs, in ms; null = the default 450.
data.startsAtstring | nullPlays only from this date (YYYY-MM-DD) or time, stored as sent.
data.expiresAtstring | nullStops 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.nodeIdstring | nullHome location; null = workspace root.
data.createdAtstringISO-8601 timestamp (UTC).
data.updatedAtstringISO-8601 timestamp (UTC).
data.deletedAtstring | null
data.fit"contain" | "cover" | "fill" | "blur-fill" | null
data.approvedSnapshotstring | nullInternal: the approved version, as stored JSON text.
data.importSourceIdstring | null
data.copySourceIdstring | nullThe partner library item this was copied from (Copy to client workspace), or null.
data.folderIdstring | nullContent folder (GET /v1/content-folders); null = the list's top level.
data.recalledAtstring | null
data.recalledBystring | null
data.usedByScreenCountinteger
data.usedByScreensarray of objectUp to 12 screens playing it.
data.usedByScreens[].idstring
data.usedByScreens[].namestring
data.allocationsarray of PlaylistAllocation
data.allocations[].idstring
data.allocations[].labelstring
data.allocations[].ownerKind"user" | "group" | "org-unit"
data.allocations[].ownerIdstring
data.allocations[].ownerNamestring
data.allocations[].kind"percent" | "every-nth" | "daypart"
data.allocations[].valueinteger
data.allocations[].endValueintegerAbsent (not null) when unset.
data.allocations[].colorClassstring
data.allocations[].fillSpaceIdstring | null
data.allocations[].fillPlaylistIdstring | null
data.allocations[].unfilledBehavior"collapse" | "filler" | "holding"
data.allocations[].fillerRefKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null
data.allocations[].fillerRefIdstring | null
data.allocations[].requiresApprovalboolean
data.itemsarray of PlaylistItem
data.items[].idstringPlaylist item id.
data.items[].refKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative"
data.items[].refIdstringThe media / app instance / layout / playlist id.
data.items[].namestring
data.items[].thumbnailUrlstringEmpty string when there is none.
data.items[].kindstringThe media kind for media items; app, layout or playlist otherwise.
data.items[].nestedItemCountinteger | nullNested playlists only: its top-level item count.
data.items[].nestedShuffleboolean | nullNested playlists only: whether that playlist plays its items in shuffled order.
data.items[].sharedFromstring | nullThe 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[].repeatLoopobject | nullA 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[].durationSecondsintegerDwell in seconds for fixed.
data.items[].loopCountinteger
data.items[].loopDurationMsinteger | null
data.items[].mediaDurationSecnumber | null
data.items[].pageCountinteger | nullA 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" | nullThe item's own fit; null = inherit.
data.items[].assetFit"contain" | "cover" | "fill" | "blur-fill" | null
data.items[].assetStartsAtstring | null
data.items[].assetExpiresAtstring | null
data.items[].assetActiveboolean | null
data.items[].fullscreenboolean
data.items[].playOnlyWhenTappedbooleanThe rotation skips this item; a design's show-design tap action shows it.
data.items[].withheld"expired" | "archived" | "not-yet" | nullWhy a media item is not airing now, or null.
data.items[].allocationIdstring | null
data.items[].positioninteger
data.sharedIntruePresent 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}

Auth: Bearer token. Permission: playlist.edit.

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.

ParameterInTypeRequiredDescription
idpathstringyesPlaylist id.
itemIdpathstringyesPlaylist item id.
curl -X DELETE "https://api.brixsignage.com/v1/playlists/{id}/items/{itemId}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

FieldTypeDescription
dataPlaylistA playlist with its ordered items.
data.idstringPlaylist id.
data.spaceIdstring
data.namestring
data.descriptionstring
data.shuffleboolean
data.fullscreenboolean
data.transition"none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | nullChange 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.transitionMsinteger | nullHow long the transition runs, in ms; null = the default 450.
data.startsAtstring | nullPlays only from this date (YYYY-MM-DD) or time, stored as sent.
data.expiresAtstring | nullStops 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.nodeIdstring | nullHome location; null = workspace root.
data.createdAtstringISO-8601 timestamp (UTC).
data.updatedAtstringISO-8601 timestamp (UTC).
data.deletedAtstring | null
data.fit"contain" | "cover" | "fill" | "blur-fill" | null
data.approvedSnapshotstring | nullInternal: the approved version, as stored JSON text.
data.importSourceIdstring | null
data.copySourceIdstring | nullThe partner library item this was copied from (Copy to client workspace), or null.
data.folderIdstring | nullContent folder (GET /v1/content-folders); null = the list's top level.
data.recalledAtstring | null
data.recalledBystring | null
data.usedByScreenCountinteger
data.usedByScreensarray of objectUp to 12 screens playing it.
data.usedByScreens[].idstring
data.usedByScreens[].namestring
data.allocationsarray of PlaylistAllocation
data.allocations[].idstring
data.allocations[].labelstring
data.allocations[].ownerKind"user" | "group" | "org-unit"
data.allocations[].ownerIdstring
data.allocations[].ownerNamestring
data.allocations[].kind"percent" | "every-nth" | "daypart"
data.allocations[].valueinteger
data.allocations[].endValueintegerAbsent (not null) when unset.
data.allocations[].colorClassstring
data.allocations[].fillSpaceIdstring | null
data.allocations[].fillPlaylistIdstring | null
data.allocations[].unfilledBehavior"collapse" | "filler" | "holding"
data.allocations[].fillerRefKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null
data.allocations[].fillerRefIdstring | null
data.allocations[].requiresApprovalboolean
data.itemsarray of PlaylistItem
data.items[].idstringPlaylist item id.
data.items[].refKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative"
data.items[].refIdstringThe media / app instance / layout / playlist id.
data.items[].namestring
data.items[].thumbnailUrlstringEmpty string when there is none.
data.items[].kindstringThe media kind for media items; app, layout or playlist otherwise.
data.items[].nestedItemCountinteger | nullNested playlists only: its top-level item count.
data.items[].nestedShuffleboolean | nullNested playlists only: whether that playlist plays its items in shuffled order.
data.items[].sharedFromstring | nullThe 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[].repeatLoopobject | nullA 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[].durationSecondsintegerDwell in seconds for fixed.
data.items[].loopCountinteger
data.items[].loopDurationMsinteger | null
data.items[].mediaDurationSecnumber | null
data.items[].pageCountinteger | nullA 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" | nullThe item's own fit; null = inherit.
data.items[].assetFit"contain" | "cover" | "fill" | "blur-fill" | null
data.items[].assetStartsAtstring | null
data.items[].assetExpiresAtstring | null
data.items[].assetActiveboolean | null
data.items[].fullscreenboolean
data.items[].playOnlyWhenTappedbooleanThe rotation skips this item; a design's show-design tap action shows it.
data.items[].withheld"expired" | "archived" | "not-yet" | nullWhy a media item is not airing now, or null.
data.items[].allocationIdstring | null
data.items[].positioninteger
data.sharedIntruePresent 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

Auth: Bearer token. Permission: playlist.edit.

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.

ParameterInTypeRequiredDescription
idpathstringyesPlaylist id.

Request body: application/json

FieldTypeRequiredDescription
itemsarray of objectyesThe items, each the body of POST /v1/playlists/{id}/items.
items[].refKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative"yes
items[].refIdstringyes
items[].durationMode"fixed" | "full" | "live" | "loop" | "manual"no
items[].durationSecondsintegerno
items[].loopCountnumberno
items[].fitstringnocontain, cover, fill or blur-fill; anything else means inherit.
items[].fullscreenbooleanno
items[].playOnlyWhenTappedbooleannoSkip it in the rotation; show it only from a show-design tap. Default false.
items[].positionnumbernoAccepted but ignored: the item is always appended. Reorder with PUT /v1/playlists/{id}/items.
items[].allocationIdstringno
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.

FieldTypeDescription
dataPlaylistA playlist with its ordered items.
data.idstringPlaylist id.
data.spaceIdstring
data.namestring
data.descriptionstring
data.shuffleboolean
data.fullscreenboolean
data.transition"none" | "fade" | "slide-left" | "slide-right" | "slide-up" | "slide-down" | "zoom" | nullChange 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.transitionMsinteger | nullHow long the transition runs, in ms; null = the default 450.
data.startsAtstring | nullPlays only from this date (YYYY-MM-DD) or time, stored as sent.
data.expiresAtstring | nullStops 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.nodeIdstring | nullHome location; null = workspace root.
data.createdAtstringISO-8601 timestamp (UTC).
data.updatedAtstringISO-8601 timestamp (UTC).
data.deletedAtstring | null
data.fit"contain" | "cover" | "fill" | "blur-fill" | null
data.approvedSnapshotstring | nullInternal: the approved version, as stored JSON text.
data.importSourceIdstring | null
data.copySourceIdstring | nullThe partner library item this was copied from (Copy to client workspace), or null.
data.folderIdstring | nullContent folder (GET /v1/content-folders); null = the list's top level.
data.recalledAtstring | null
data.recalledBystring | null
data.usedByScreenCountinteger
data.usedByScreensarray of objectUp to 12 screens playing it.
data.usedByScreens[].idstring
data.usedByScreens[].namestring
data.allocationsarray of PlaylistAllocation
data.allocations[].idstring
data.allocations[].labelstring
data.allocations[].ownerKind"user" | "group" | "org-unit"
data.allocations[].ownerIdstring
data.allocations[].ownerNamestring
data.allocations[].kind"percent" | "every-nth" | "daypart"
data.allocations[].valueinteger
data.allocations[].endValueintegerAbsent (not null) when unset.
data.allocations[].colorClassstring
data.allocations[].fillSpaceIdstring | null
data.allocations[].fillPlaylistIdstring | null
data.allocations[].unfilledBehavior"collapse" | "filler" | "holding"
data.allocations[].fillerRefKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative" | null
data.allocations[].fillerRefIdstring | null
data.allocations[].requiresApprovalboolean
data.itemsarray of PlaylistItem
data.items[].idstringPlaylist item id.
data.items[].refKind"media" | "playlist" | "app" | "layout" | "ad-slot" | "creative"
data.items[].refIdstringThe media / app instance / layout / playlist id.
data.items[].namestring
data.items[].thumbnailUrlstringEmpty string when there is none.
data.items[].kindstringThe media kind for media items; app, layout or playlist otherwise.
data.items[].nestedItemCountinteger | nullNested playlists only: its top-level item count.
data.items[].nestedShuffleboolean | nullNested playlists only: whether that playlist plays its items in shuffled order.
data.items[].sharedFromstring | nullThe 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[].repeatLoopobject | nullA 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[].durationSecondsintegerDwell in seconds for fixed.
data.items[].loopCountinteger
data.items[].loopDurationMsinteger | null
data.items[].mediaDurationSecnumber | null
data.items[].pageCountinteger | nullA 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" | nullThe item's own fit; null = inherit.
data.items[].assetFit"contain" | "cover" | "fill" | "blur-fill" | null
data.items[].assetStartsAtstring | null
data.items[].assetExpiresAtstring | null
data.items[].assetActiveboolean | null
data.items[].fullscreenboolean
data.items[].playOnlyWhenTappedbooleanThe rotation skips this item; a design's show-design tap action shows it.
data.items[].withheld"expired" | "archived" | "not-yet" | nullWhy a media item is not airing now, or null.
data.items[].allocationIdstring | null
data.items[].positioninteger
data.sharedIntruePresent 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

Auth: Bearer token. Permission: playlist.delete.

Restore a deleted playlist so its items and ordering return to the playlist library.

ParameterInTypeRequiredDescription
idpathstringyesPlaylist id.
curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

FieldTypeDescription
dataobject
data.idstring
data.restoredtrue

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No such playlist in this workspace, or it was purged.

Response 409: not_deleted: the playlist is not in the recycle bin.

Response 5XX: Server error. The body carries a requestId to quote to support.

GET /v1/playlists/{id}/share-readiness

Auth: Bearer token. Permission: playlist.view.

For a playlist's airtime reserved for other teams, list who at each location can fill their share, and the narrowest role that would let them do so. Notes. - requiredPermissions is absent when locations is empty.

ParameterInTypeRequiredDescription
idpathstringyesPlaylist id.
curl "https://api.brixsignage.com/v1/playlists/{id}/share-readiness" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

FieldTypeDescription
dataobject
data.locationsarray of objectOne per location that holds a percent share of this playlist.
data.locations[].nodeIdstring
data.locations[].nodeNamestring
data.locations[].canFillbooleanSomebody at the location can fill the share now.
data.locations[].fillerCountinteger
data.locations[].candidatesarray of objectPeople at the location who cannot fill it yet.
data.locations[].candidates[].userIdstring
data.locations[].candidates[].namestring
data.locations[].candidates[].emailstring
data.locations[].roleIdstring | nullThe narrowest existing role that would let them fill it.
data.locations[].roleNamestring | null
data.locations[].mayGrantbooleanThe caller may give that role at that location.
data.locations[].fillApprovalState"draft" | "pending" | "approved" | "rejected" | nullWhere the location's own content stands in review; null when nothing is added yet.
data.locations[].requiresApprovalbooleanThe owner checks this location's content before it airs.
data.requiredPermissionsarray of stringThe permissions filling a share needs. Absent when no location holds a share.

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No such playlist in this workspace.

Response 5XX: Server error. The body carries a requestId to quote to support.

POST /v1/playlists/bulk-delete

Auth: Bearer token.

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.