Playlists
Tools for managing playlists. A playlist is an ordered sequence of media items (images, videos, web pages) that play in rotation on devices.
list_playlists
List all playlists in the account. Returns playlist objects with id, name, group assignment, duration, and item count.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id |
string or string[] | No | Filter by playlist group ID(s) |
group_name |
string or string[] | No | Filter by playlist group name(s) |
take |
number | No | Results per page |
page |
number | No | Page number (1-based) |
get_playlist
Get a playlist by ID including its full list of media items (sources). Returns the playlist’s name, group, duration, sharing status, and an ordered items array.
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The playlist ID |
create_playlist
Create a new playlist. At minimum a name is required. Optionally pre-populate with media items.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Name for the new playlist |
group_id |
string | No | Playlist group ID |
is_shared |
boolean | No | Share across organizations |
items |
array | No | Ordered array of playlist items |
Each item in the items array:
| Field | Type | Required | Description |
|---|---|---|---|
media_id |
string | Yes | Media item ID |
duration |
number | No | Display duration in seconds |
transition |
number | No | Transition duration in milliseconds |
sequence |
number | No | Order position (0-based) |
update_playlist
Update a playlist’s properties or media items. When updating items, send the complete ordered array — it replaces existing items entirely.
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The playlist ID |
name |
string | No | Updated name |
group_id |
string | No | Move to this group |
is_shared |
boolean | No | Share across organizations |
items |
array | No | Complete replacement items array |
delete_playlist
Permanently delete a playlist. Schedules referencing this playlist will need to be updated. Devices currently playing this playlist will stop once they refresh.
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The playlist ID |
Playlist Sources
The following tools edit a single source within a playlist without resending the whole sources array. They are GraphQL-backed — REST’s update_playlist can only replace the entire list at once.
add_playlist_source
Add a content source to an existing playlist.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlistId |
string | Yes | The playlist ID to add the source to |
source |
object | Yes | Source definition (type required — e.g. Image, Video, Template, Url, Playlist; plus mediaId / templateId / value / interval / conditions). See introspect_schema typeName SourceInput |
position |
number | No | Zero-based insertion index. Omit to append |
update_playlist_source
Update a single source within a playlist (e.g. change its media or duration).
| Parameter | Type | Required | Description |
|---|---|---|---|
playlistId |
string | Yes | The playlist ID |
sourceId |
string | Yes | The ID of the source to update |
source |
object | Yes | Updated source definition (see SourceInput) |
remove_playlist_source
Remove a single source from a playlist by source ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlistId |
string | Yes | The playlist ID |
sourceId |
string | Yes | The ID of the source to remove |
reorder_playlist_sources
Reorder the sources within a playlist by supplying the desired source-ID sequence.
| Parameter | Type | Required | Description |
|---|---|---|---|
playlistId |
string | Yes | The playlist ID |
sourceIds |
string[] | Yes | Source IDs in the desired play order |