Playlists

A playlist is either static, with videos you add and order yourself, or smart, with videos chosen by rules. The playlist calls are listed in the API reference under Playlist; this page covers what you need to know to use them.

Static and smart playlists

Set is_smart when you create a playlist with playlist/add: 1 for a smart playlist, 0 (or nothing) for a static one. A smart playlist’s videos come from its rules (see Smart playlist rules below); a static playlist’s videos are the ones you add.

Creating and editing

Parameter	Description
name `(string)`	Playlist name. Required when you create a playlist.
partner_id `(integer)`	Your website ID. Required when you create a playlist.
publish `(string)`	Publish date, as `YYYY-MM-DD`. Empty means today. The API reference calls this field `publish_date`, but the API reads `publish`.
status `(integer)`	`1` published, `0` unpublished. In `playlist/all` responses, a published playlist with a future publish date shows `7` (pending). To change only the status, use `playlist/change_status/{id}`.
tags `(string)`	The playlist’s own tags, comma-separated.
exclude_tag `(string)`	Static playlists: a tag name. Videos in the playlist that carry it aren’t shown.

Send the publish date and the tags with every edit. An edit without publish sets the publish date to today, and an edit without tags removes all of the playlist’s tags.

Smart playlist rules

Send the rules with playlist/add or playlist/edit/{id}. Lists are comma-separated.

Parameter	Description
include_tags_taxonomy_ids `(string)`	Videos in any of these IAB categories (by ID), including their sub-categories.
exclude_tags_taxonomy_ids `(string)`	Leaves out videos in these IAB categories and their sub-categories.
lang `(string)`	Only videos in this language, matched exactly as set on the video.
video_type `(integer)`	`0` all videos, `1` vertical videos only, `2` no vertical videos.
video_publish_date `(string)`	A date as `YYYY-MM-DD`, used with `video_publish_date_period`.
video_publish_date_period `(integer)`	`1` videos published on or before `video_publish_date`, `2` on or after it.
max_duration `(integer)`	Longest video length, in seconds. Applied when the playlist plays in the player, not to `playlist/view` or `playlist/all`.

A smart playlist only ever contains videos that are published and past their publish date, not expired, not rejected and not DRM-protected. The newest videos come first.

Videos in a static playlist

playlist/add_videos/{id} with ids: the videos are added at the top of the playlist. Videos already in it are skipped. Use it also to fill a new static playlist after playlist/add.
playlist/sort/{id} with sort: the comma-separated IDs of all the playlist’s videos, in the new order. A list that misses or adds a video is rejected.
playlist/delete_videos/{id} with ids removes those videos.
These calls only affect static playlists. A smart playlist ignores videos added this way.

Reading playlists

Call	Returns
`playlist/list/{partner_id}`	Only the IDs and names of the playlists, e.g. `{"123": "Highlights"}`. Supports `page` and `limit`.
`playlist/all/{partner_id}`	Full playlist records, each with a few of its videos. `videos` sets how many (default 3, at most 25), and `search` matches playlist names.
`playlist/view/{id}`	One playlist and its videos, page by page (`page`, `limit`).

To use a playlist as an MRSS, Roku or Yahoo feed, see Playlist feeds (MRSS).

Webhooks

Playlist changes send these events to your webhook endpoint (see Webhooks):

Event	Sent after
`playlist_add`	`playlist/add`
`playlist_edit`	`playlist/edit`
`playlist_delete`	`playlist/delete`
`playlist_add_videos`	`playlist/add_videos`
`playlist_delete_videos`	`playlist/delete_videos`
`playlist_sort`	`playlist/sort`
`playlist_clear`	`playlist/clear`
`playlist_change_status`	`playlist/change_status`