---
title: "Remove a playlist item"
method: DELETE
path: "/v1/playlists/{id}/items/{itemId}"
tags: ["playlists"]
---

# Remove a playlist item

`DELETE /v1/playlists/{id}/items/{itemId}`

## Request

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

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.

## Path parameters

- `id` string, required
- `itemId` string, required

## 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`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `404`: No such playlist in this workspace.
- `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)