---
title: "Add an item to a playlist"
method: POST
path: "/v1/playlists/{id}/items"
tags: ["playlists"]
---

# Add an item to a playlist

`POST /v1/playlists/{id}/items`

## Request

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

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.

## Path parameters

- `id` string, required

## Request body

- object: Unknown fields are refused.
  - `refKind` 'media' | 'playlist' | 'app' | 'layout' | 'ad-slot', required
  - `refId` string, required
  - `durationMode` 'fixed' | 'full' | 'live' | 'loop' | 'manual'
  - `durationSeconds` integer
  - `loopCount` number
  - `fit` string: contain, cover, fill or blur-fill; anything else means inherit.
  - `fullscreen` boolean
  - `playOnlyWhenTapped` boolean: Skip it in the rotation; show it only from a `show-design` tap. Default false.
  - `position` number: Accepted but ignored: the item is always appended. Reorder with PUT /v1/playlists/{id}/items.
  - `allocationId` string

## Response `201`

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`: `not_shared`: the content is not available at the playlist's location.
- `404`: No such playlist, or the referenced content is not in this workspace.
- `422`: Invalid body, a playlist loop, a layout with unbound zones, or an unknown allocation.
- `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)