Playlists API (part 1 of 2)

GET /v1/playlists

Auth: Bearer token. Permission: playlist.view.

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

Auth: Bearer token. Permission: playlist.create.

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}

Auth: Bearer token. Permission: playlist.view.

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}

Auth: Bearer token. Permission: playlist.edit.

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}

Auth: Bearer token. Permission: playlist.delete.

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

Auth: Bearer token. Permission: playlist.edit.

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.