Each user on a Plex server can create their own playlists. A playlist can contain either videos, music, or photos, and can't be shared with other users. There are smart and non-smart playlists. This API command will create a non-smart playlist for a user.
POST http://[IP address]:32400/playlists?type=[Playlist Type]&title=[Playlist Title]&smart=[Smart Flag]&uri=server://[Machine ID]/com.plexapp.plugins.library/[Library Key]?X-Plex-Token=[PlexToken]
|IP address||The IP address of the Plex Media server.|
|PlexToken||The authentication Plex token.|
|Playlist Type||The type of playlist to be created. Valid values: audio, video, photo.|
|Playlist Title||The name of the playlist.|
|Machine ID||The ID associated with the Plex server. Can be found by calling the Server Identity command and getting the |
|Library Key||The key associated with the library item to be added to the playlist. See below for information on this value.|
|200||Success - The request was successful.|
|400||Bad request - A parameter is missing.|
|401||Unauthorized - The Plex token provided is not valid.|
|500||Internal server error - A parameter value is not valid.|
XML string value that provides details of the playlist that was just created. An example of the XML return value is shown below:
<?xml version="1.0" encoding="UTF-8"?> <MediaContainer size="1"> <Playlist ratingKey="289130" key="/playlists/289130/items" guid="com.plexapp.agents.none://aa1ce6fe-b6f3-48c5-bd4f-23df120ee1f8" type="playlist" title="My Playlist" summary="" smart="0" playlistType="video" composite="/playlists/279131/composite/1786162547" icon="playlist://image.smart" duration="4246000" leafCount="1" addedAt="1684162647" updatedAt="1684162647"></Playlist> </MediaContainer> </MediaContainer>
The XML return provides information on the new playlist. The root is the
MediaContainer element. This element contains a single attribute indicating that one playlist has been returned from the server.
|size||The number of playlists returned.|
MediaContainer there is one
Playlist child element. The
Playlist element contains information on the new playlist on the Plex server.
|ratingKey||A key associated with the playlist.|
|key||The relative URL of the items in the playlist. This URL returns information about the items in the playlist.|
|guid||The unique identifier comprised of the Plex agent and playlist identifier for the agent.|
|type||The type of media.|
|title||The title of the playlist.|
|summary||A description of the playlist. This can be changed by editing the playlist from within Plex after it has been created.|
|smart||1 - playlist is a smart playlist.|
0 - playlist is not a smart playlist.
|playlistType||video - playlist contains videos/movies.|
audio - playlist contains audio/music.
photo - playlist contains photos.
|composite||The URL of the image used to represent the playlist.|
|icon||Icon used for smart playlists. Not used for non-smart playlists.|
|duration||The total duration, in milliseconds, of the number of items in the playlist. This value doesn't exist for photo playlists.|
|leafCount||Number of items in the playlist.|
|addedAt||The date and time, in Unix time, the playlist was added to the library.|
|updatedAt||The date and time in epoch time, the playlist was updated in the library.|
Library key parameter
Library Key parameter value can be found if you access the Plex server from the Web app.
When you hover over any item - movie, TV show, music, photo, etc. there will be a
key parameter in the URL. That key value is the value you will use for the
Library Key parameter.
The value is easy to find in the URL of the item. It has the structure
/library/metadata/[Item ID]. You will use the entire value of the
key parameter from the media item URL.
type parameter should indicate the type of media that will be in the playlist. A playlist cannot have different media types. This means that a playlist can only contain either videos, music or photos, but not more than one type.
If the value of the
type parameter does not match the media item specified in the
uri parameter, the playlist type will be the same as the media item.
For example, if the
type parameter value is
video but the media item type in the
uri parameter is a photo, the playlist will be a photo playlist and not a video playlist. The response XML will indicate the proper playlist type.
If a video was added to that same playlist, a new video playlist with the same name will be created for videos.
type parameter must be provided or a
400 - Bad Request will be returned and the playlist won't be created.
The command and parameters explained on this page are used for creating non-smart playlists in Plex. If you use the same command but set the
smart parameter to
1 you will create an empty playlist.
The API request for submitting a smart playlist is similar, but is different with regards to parameters.
Adds the media item with ID 915 to a new video playlist that on the Plex Media Server located at the IP address of 192.168.1.4:
POST http://192.168.1.4:32400/playlists?type=video&title=My Playlist&smart=0&uri=server://2a547027b56abd6dcdf72484564db8567a747430/com.plexapp.plugins.library/library/metadata/915&X-Plex-Token=L6vkd7JtLHjsH5987vYY
Adds the media item with ID 2015 to a new audio/music playlist that on the Plex Media Server located at the IP address of 192.168.1.4:
POST http://192.168.1.4:32400/playlists?type=audio&title=My Playlist&smart=0& uri=server://2a547027b56abd6dcdf72484564db8567a747430/com.plexapp.plugins.library/library/metadata/2015&X-Plex-Token=L6vkd7JtLHjsH5987vYY