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 playlist via the GraphQL createPlaylist mutation. The playlist type is immutable after creation — pick it by what will rotate in the zone.

Parameter	Type	Required	Description
`name`	string	Yes	Name for the new playlist
`group_id`	string	Yes	Playlist group (folder) ID — required by the API
`type`	`Gallery` \| `Image` \| `Template` \| `Ticker`	No	Playlist type, default `Gallery`
`tags`	string[]	No	Tags
`duration`	number	No	Fixed duration in seconds, used with each source’s loop policy
`isRandomStart`	boolean	No	Start playback at a random source
`sources`	source[]	No	Initial sources, in playback order — see Source types
`items`	array	No	Legacy — media-only items mapped to `IMAGE` sources; see below

Playlist types

Type	Use for	Accepts sources
`Gallery` (default)	General mixed content, incl. video, images, YouTube, web pages, ads	Media, YouTube, WebPage, Rss/Url, Playlist (Gallery/Image), Command, ad types
`Image`	A still-image slideshow, no video	Image/Svg/Pdf/PowerPoint media, WebPage, Rss/Url, Playlist (Image), Command, ad types
`Template`	A rotation of full layouts, e.g. menu boards	Everything `Gallery` allows, plus Template sources (`templateId`)
`Ticker`	A scrolling text/marquee zone	Text, Rss/Url, DataTable, Playlist (Ticker), Command

The server enforces these rules on both create_playlist and add_playlist_source, rejecting a mismatch with the offending index, e.g. sources[1]: Video sources are not allowed in a Image playlist. Allowed: .... The tool does not duplicate the rules table, so the API stays the single source of truth.

Omitting type yields Gallery, which is what every playlist created before this tool became type-aware received — REST accepted a type but silently defaulted it.

Source types

Each entry in sources follows SourceInput:

Field	Type	Description
`type`	enum	Required. The exact SCREAMING_SNAKE enum name: `IMAGE`, `VIDEO`, `AUDIO`, `SVG`, `PDF`, `POWER_POINT`, `FLASH`, `GADGET`, `YOU_TUBE`, `WEB_PAGE`, `RSS`, `URL`, `TEXT`, `TEMPLATE`, `PLAYLIST`, `COMMAND`, `DATA_TABLE`, `TWITTER`, `AD_BREAK`, `VISTAR_MEDIA`, `VISTAR_MEDIA_EX`, `PLACE_EXCHANGE`
`name`	string	Display name
`mediaId`	string	Media file ID (`IMAGE`, `VIDEO`, `AUDIO`, `PDF`, `SVG`)
`templateId`	string	Template ID (`TEMPLATE`)
`playlistId`	string	Embedded playlist ID (`PLAYLIST`)
`value`	string	URL or text (`URL`, `WEB_PAGE`, `RSS`, `TEXT`, `YOU_TUBE`)
`interval`	number	Duration in seconds
`loopPolicyType`	string	Loop policy for fixed-duration playlists
`conditions`	condition[]	When/where this source plays — same shape as schedule conditions

type is a GraphQL enum, so "Image" or "WebPage" are rejected before reaching a resolver. Use IMAGE, WEB_PAGE.

Example — a menu-board rotation of two templates:

{
  "name": "Menu boards",
  "group_id": "<group-id>",
  "type": "Template",
  "sources": [
    { "type": "TEMPLATE", "templateId": "<template-id>", "interval": 15 },
    { "type": "TEMPLATE", "templateId": "<template-id>", "interval": 20 }
  ]
}

Legacy `items`

items predates sources and is kept so existing calls keep working. Each entry maps to an IMAGE source, ordered by sequence:

Field	Type	Required	Description
`media_id`	string	Yes	Media item ID → `mediaId`
`duration`	number	No	Display duration in seconds → `interval`
`sequence`	number	No	Order position (0-based); entries without one keep their given order

items cannot be combined with sources. transition is no longer accepted — SourceInput has no equivalent field, so it was always dropped. An item pointing at a video file is still labelled IMAGE, exactly as before.

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
`items`	array	No	Complete replacement items array

The playlist type cannot be changed after creation — neither REST nor the CMS writes it on update, so it is not accepted here.

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. The source must be valid for the playlist’s type — the server rejects a mismatch, e.g. a VIDEO source in an Image playlist or a TEMPLATE source in a Gallery playlist.

Parameter	Type	Required	Description
`playlistId`	string	Yes	The playlist ID to add the source to
`source`	object	Yes	Source definition (`type` required, SCREAMING_SNAKE — e.g. `IMAGE`, `VIDEO`, `TEMPLATE`, `URL`, `PLAYLIST`; plus `mediaId` / `templateId` / `value` / `interval` / `conditions`). See Source types
`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

Back to Home