Playlists API

GET/v1/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.

curl "https://api.brixsignage.com/v1/playlists" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

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.

Request body application/json

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.

{
  "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}

Retrieve one playlist with its ordered items, including each item's reference kind and id, duration, and rules.

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

Response 200 Success.

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}

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

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/playlists/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

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

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

Response 200 Success.

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

Request body application/json

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.

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.

POST/v1/playlists/{id}/duplicate

Create a deep copy of a playlist, including its settings, share-of-voice allocations (fill assignments reset), and ordered items, named "<name> copy" and unique within the space. The copy starts as a draft with no assignment. Requires permission to create playlists at the source playlist's home node.

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

Response 201 Success.

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

Append one item to a playlist with refKind, refId, and an optional durationSec and other fields. Rejects references from another space, and rejects any nesting that would create a loop, such as a playlist referencing a layout zone that contains the same playlist, with a clear error rather than failing silently. Appends one item. A video or audio file defaults to playing its full length, an animated image to one loop, anything else to 10 seconds. Returns the whole playlist. **Notes.** - position is accepted and ignored. - The returned approvalState is the value from before the edit; an approved playlist is returned to draft in storage by this call. Re-read with GET to see it.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/playlists/{id}/items" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 `not_shared`: the content is not available at the playlist's location.

Response 404 No such playlist, or the referenced content is not in this workspace.

Response 422 Invalid body, a playlist loop, a layout with unbound zones, or an unknown allocation.

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

PUT/v1/playlists/{id}/items

Replace a playlist's entire item list in one call. Send the full array of items in the order you want; the same reference and loop validation applies as when adding a single item. Sets the order of the items: itemIds[0] plays first. Unknown ids are skipped. It does not add or remove items. Returns the whole playlist. **Notes.** - Items left out of itemIds keep their old position number, so two items can share a position. Send every item id. - A missing or malformed body is treated as an empty list, not refused.

Request body application/json

curl -X PUT "https://api.brixsignage.com/v1/playlists/{id}/items" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":["pli_7a8b9c0d1e2f3a4b","pli_1e2f3a4b5c6d7e8f"]}'

Response 200 Success.

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}/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.

Request body application/json

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.

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.

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

Response 200 Success.

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}/restore

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

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

Response 200 Success.

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

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.

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

Response 200 Success.

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.