## Playlists [/playlists]

Playlists are ordered collections of media. They can be dumb (just a list of media) or smart (based on a media query, such as "all albums from 2017"). They can be organized in (optionally nesting) folders.

Retrieving a playlist, or its items, will trigger a refresh of its metadata. This may cause the duration and number of items to change.

### Retrieve Playlists [GET /playlists/all{?playlistType,smart}]

Gets a list of playlists and playlist folders for a user. General filters are permitted, such as `sort=lastViewedAt:desc`. A flat playlist list can be retrieved using `type=15` to limit the collection to just playlists. Special attributes returned are:

- `smart` (0/1) - whether or not the playlist is smart.
- `duration` (milliseconds) - the total duration of the playlist.
- `leafCount` - the number of items in the playlist.
- `composite` - a composite image for the playlist.
- `key` - leads to a list of items in the playlist.
- `playlistType` - the type of the playlist (audio/video/photo).
- `specialPlaylistType` - if this is a special playlist, this returns its type (e.g. favorites).
- `readOnly` - if we return this as true then this playlist cannot be altered or deleted directly by the client.

+   Parameters
    + playlistType: `audio` (string, optional)  - limit to a type of playlist (`audio`, `video` or `photo`)
    + smart: `0` (boolean, optional) - optional, type of playlists to return (default is all).

+   Response 200 (application/xml)

        <MediaContainer size="2">
          <Playlist ratingKey="2561805" key="/playlists/2561805/items"  type="playlist" title="Background videos" summary="" smart="0" playlistType="video" composite="/playlists/2561805/composite/1485900004" viewCount="8" lastViewedAt="1484680617" duration="1512000" leafCount="8" addedAt="1476942219" updatedAt="1485900004"></Playlist>
          <Playlist ratingKey="1956389" key="/playlists/1956389/items" type="playlist" title="Fairly Recent" summary="" smart="1" playlistType="audio" composite="/playlists/1956389/composite/1486498661" duration="938507000" leafCount="3934" addedAt="1428993345" updatedAt="1486498661"></Playlist>
        </MediaContainer>

### Create a Playlist [POST /playlists?{title,type,smart,uri,playQueueID}]

Create a new playlist. By default the playlist is blank. To create a playlist along with a first item, pass:

- `uri` - The content URI for what we're playing (e.g. `library://...`).
- `playQueueID` - To create a playlist from an existing play queue.

If you're creating a smart playlist, you must pass `smart=1` and use the `uri=...` form. Playlists are owned by the account associated with the request.

+   Parameters
     + title: `My Playlist` (string) - name of the playlist
     + type: `audio` (string) - type of the playlist (`video`/`audio`/`photo`)
     + smart: `0` (0/1) - whether the playlist is smart or not.
     + uri: `library://..` (string, optional) - the content URI for the playlist.
     + playQueueID: `123` (integer, optional) - the play queue to copy to a playlist.

+   Response 200 (application/xml)

        <MediaContainer size="1">
          <Playlist ratingKey="2561805" key="/playlists/2561805/items"  type="playlist" title="Background videos" summary="" smart="0" playlistType="video" composite="/playlists/2561805/composite/1485900004" viewCount="8" lastViewedAt="1484680617" duration="1512000" leafCount="8" addedAt="1476942219" updatedAt="1485900004"></Playlist>
        </MediaContainer>

### Retrieve Playlist  [GET /playlists/{playlistID}]

Gets detailed metadata for a playlist. A playlist for many purposes (rating, editing metadata, tagging), can be treated like a regular metadata item:

Smart playlist details contain the `content` attribute. This is the content URI for the generator. This can then be parsed by a client to provide smart playlist editing.

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.

+   Response 200 (application/xml)

        <MediaContainer size="1">
            <Playlist content="library://22d0bfe3-21ce-4a67-9065-ccaf470cb3c2/directory/%2Flibrary%2Fsections%2F1224%2Fall%3Ftrack%2EaddedAt%3E%3D-12mon%26album%2Egenre!%3DPodcast%26album%2Egenre!%3DBooks%2520%2526%2520Spoken%26artist%2Etitle!%3DAOL%2520Music" ratingKey="1956389" key="/playlists/1956389/items" guid="com.plexapp.plugins.itunes://9F7B78609597F45F" type="playlist" title="Fairly Recent" summary="" smart="1" playlistType="audio" composite="/playlists/1956389/composite/1486764293" duration="957684000" leafCount="4015" addedAt="1428993345" updatedAt="1486764293"></Playlist>
        </MediaContainer>

### Retrieve Playlist Contents [GET /playlists/{playlistID}/items{?type}]

Gets the contents if a playlist. Should be paged by clients via standard mechanisms. By default leaves are returned (e.g. episodes, movies). In order to return other types you can use the `type` parameter. For example, you could use this to display a list of recently added albums vis a smart playlist. Note that for dumb playlists, items have a `playlistItemID` attribute which is used for deleting or moving items.

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.
    + type: `8` (integer) - the metadata type of the item to return.

+   Response 200 (application/xml)

        <MediaContainer size="100">
           <Video ... playlistItemID="123" />
        </MediaContainer>

### Delete a Playlist [DELETE /playlists/{playlistID}]

Deletes a playlist.

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.

+   Response 200

### Editing a Playlist [PUT /library/metadata/{playlistID}]

Use the standard metadata item editing endpoint (tag a playlist! edit the title!). Just listing it here to illustrate the potential.

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.

+   Response 200

### Editing a Playlist (PMS >= 1.9.1) [PUT /playlists/{playlistID}]

From PMS version 1.9.1 clients can also edit playlist metadata using this endpoint as they would via `PUT /library/metadata/{playlistID}`

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.

+   Response 200

### Clearing a playlist [DELETE /playlists/{playlistID}/items]

Clears a playlist, only works with dumb playlists. Returns the playlist.

+   Parameters
    + playlistID: `123` (integer) - the ID of the playlist.

+   Response 200

        <MediaContainer size="1">
          <Playlist ratingKey="2561805" key="/playlists/2561805/items"  type="playlist" title="Background videos" summary="" smart="0" playlistType="video" composite="/playlists/2561805/composite/1485900004" viewCount="8" lastViewedAt="1484680617" duration="1512000" leafCount="0" addedAt="1476942219" updatedAt="1485900004"></Playlist>
        </MediaContainer>

### Adding to  a Playlist [PUT /playlists/{playlistID}/items?{uri,playQueueID}]

Adds a generator to a playlist, same parameters as the POST above. With a dumb playlist, this adds the specified items to the playlist. With a smart playlist, passing a new `uri` parameter replaces the rules for the playlist. Returns the playlist.

+   Parameters
     + uri: `library://..` (string, optional) - the content URI for the playlist.
     + playQueueID: `123` (integer, optional) - the play queue to add to a playlist.

+   Response 200 (application/xml)

        <MediaContainer size="1">
          <Playlist ratingKey="2561805" key="/playlists/2561805/items" type="playlist" title="Background videos" summary="" smart="0" playlistType="video" composite="/playlists/2561805/composite/1485900004" viewCount="8" lastViewedAt="1484680617" duration="1512000" leafCount="8" addedAt="1476942219" updatedAt="1485900004"></Playlist>
        </MediaContainer>

### Moving items in a playlist [PUT /playlists/{playlistID}/items/{playlistItemID}/move{?after}]

Moves an item in a playlist. Only works with dumb playlists.

+   Parameters
     + playlistID: `123` (integer) - the playlist ID.
     + playlistItemID: `1` (integer) - the playlist item ID to move.
     + after: `2` (integer, optional) - the playlist item ID to insert the new item after.

+   Response 200

### Delete a Generator [DELETE /playlists/{playlistID}/items/{playlistItemID}]

Deletes an item from a playlist. Only works with dumb playlists.

+   Parameters
     + playlistID: `123` (integer) - the playlist ID.
     + playlistItemID: `1` (integer) - the playlist item ID to move.

+   Response 200

### Upload Playlists [POST /playlists/upload{?path,force}]

Imports m3u playlists by passing a path on the server to scan for m3u-formatted playlist files, or a path to a single playlist file.

+   Parameters
    + path: `/home/barkley/playlist.m3u` - absolute path to a directory on the server where m3u files are stored, or the absolute path to a playlist file on the server. If the `path` argument is a directory, that path will be scanned for playlist files to be processed. Each file in that directory creates a separate playlist, with a name based on the filename of the file that created it. The GUID of each playlist is based on the filename. If the `path` argument is a file, that file will be used to create a new playlist, with the name based on the filename of the file that created it. The GUID of each playlist is based on the filename.
    + force: `1` - force overwriting of duplicate playlists. By default, a playlist file uploaded with the same path will overwrite the existing playlist. The `force` argument is used to disable overwriting. If the `force` argument is set to 0, a new playlist will be created suffixed with the date and time that the duplicate was uploaded.

+   Response 200