---
title: "Update a playlist"
method: PATCH
path: "/v1/playlists/{id}"
tags: ["playlists"]
---

# Update a playlist

`PATCH /v1/playlists/{id}`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/playlists/{id}`
- Auth: HTTP bearer

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

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string
  - `description` string
  - `shuffle` boolean
  - `fullscreen` boolean
  - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill', nullable
  - `startsAt` string, nullable
  - `expiresAt` string, nullable
  - `nodeId` string, nullable: Move to another location (needs playlist.edit there).
  - `baseUpdatedAt` string: The `updatedAt` your edit is based on; a stale value answers 409 with `current`.

## Response `200`

Success.

- object
  - `data` Playlist, required: A playlist with its ordered items.
    - `id` string, required: Playlist id.
    - `spaceId` string, required
    - `name` string, required
    - `description` string, required
    - `shuffle` boolean, required
    - `fullscreen` boolean, required
    - `startsAt` string, nullable, required: Plays only from this date (YYYY-MM-DD) or time, stored as sent.
    - `expiresAt` string, nullable, required: Stops after this date (YYYY-MM-DD) or time, stored as sent.
    - `approvalState` 'draft' | 'pending' | 'approved' | 'rejected', required: Only `approved` content airs where the location requires approval.
    - `nodeId` string, nullable, required: Home location; null = workspace root.
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).
    - `deletedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill', nullable, required
    - `approvedSnapshot` string, nullable, required: Internal: the approved version, as stored JSON text.
    - `importSourceId` string, nullable, required
    - `recalledAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `recalledBy` string, nullable, required
    - `usedByScreenCount` integer, required
    - `usedByScreens` object[], required: Up to 12 screens playing it.
      - `id` string, required
      - `name` string, required
    - `allocations` PlaylistAllocation[], required
      - `id` string, required
      - `label` string, required
      - `ownerKind` 'user' | 'group' | 'org-unit', required
      - `ownerId` string, required
      - `ownerName` string, required
      - `kind` 'percent' | 'every-nth' | 'daypart', required
      - `value` integer, required
      - `endValue` integer: Absent (not null) when unset.
      - `colorClass` string, required
      - `fillSpaceId` string, nullable, required
      - `fillPlaylistId` string, nullable, required
      - `unfilledBehavior` 'collapse' | 'filler' | 'holding', required
      - `fillerRefKind` 'media' | 'playlist' | 'app' | 'layout' | 'ad-slot', nullable, required
      - `fillerRefId` string, nullable, required
      - `requiresApproval` boolean, required
    - `items` PlaylistItem[], required
      - `id` string, required: Playlist item id.
      - `refKind` 'media' | 'playlist' | 'app' | 'layout' | 'ad-slot', required
      - `refId` string, required: The media / app instance / layout / playlist id.
      - `name` string, required
      - `thumbnailUrl` string, required: Empty string when there is none.
      - `kind` string, required: The media kind for media items; `app`, `layout` or `playlist` otherwise.
      - `nestedItemCount` integer, nullable, required: Nested playlists only: its top-level item count.
      - `nestedShuffle` boolean, nullable: Nested playlists only: whether that playlist plays its items in shuffled order.
      - `durationMode` 'fixed' | 'full' | 'live' | 'loop' | 'manual', required
      - `durationSeconds` integer, required: Dwell in seconds for `fixed`.
      - `loopCount` integer, required
      - `loopDurationMs` integer, nullable, required
      - `mediaDurationSec` number, nullable, required
      - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill', nullable, required: The item's own fit; null = inherit.
      - `assetFit` 'contain' | 'cover' | 'fill' | 'blur-fill', nullable, required
      - `assetStartsAt` string, nullable, required
      - `assetExpiresAt` string, nullable, required
      - `assetActive` boolean, nullable, required
      - `fullscreen` boolean, required
      - `playOnlyWhenTapped` boolean, required: The rotation skips this item; a design's `show-design` tap action shows it.
      - `withheld` 'expired' | 'archived' | 'not-yet', nullable, required: Why a media item is not airing now, or null.
      - `allocationId` string, nullable, required
      - `position` integer, required
    - `sharedIn` true: Present when the playlist is outside your locations and was shared in.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: Moving it to a location where you lack playlist.edit.
- `404`: No such playlist in this workspace.
- `409`: `conflict`: `baseUpdatedAt` is stale; the body carries `current`.
- `422`: An unparsable date or an unknown location.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)