In this guide we explore how to use the Spotify Web API to manage users’ playlists.

The Spotify Playlist System

Playlists are containers for tracks. Spotify’s users have already created over 1.5 billion of them. By creating a playlist, a Spotify user can specify a subset of tracks and the order in which to play them.

Via context menus and through support for drag-and-drop actions, Spotify music players provide users with various controls for manually working with playlists. Playlists can be shared with and followed by other users, made available offline, and used to seed other Spotify services, like radio.

Playlist in the Spotify Player

Public, Private, and Collaborative Status

Unless the user has specified otherwise in their preferences, a playlist manually created by a user starts life with a “public” status. That means that any other user can see it (and find it in search results) in a Spotify music player. Users can change this initial status to “private” by selecting, for example, Make Secret from the desktop player’s right-click menu (1).

Spotify Playlist's Status Changes

A user can also choose to share a playlist with other users by making it collaborative (2).  Now, as well as the owner, users who have followed the collaborative playlist or who have the direct URI to it can see the playlist and add to or remove tracks from it.

It is important to understand that making a playlist collaborative automatically changes the playlist’s status to “private”: although the collaborators can see the playlist, it is no longer visible to other users. In the Spotify ecosystem there is no concept of group ownership of a playlist; the playlist is always owned by the user who created it. Only that user can decide if the playlist is collaborative or not.

Unchecking the Collaborative Playlist control still leaves the playlist in a “private” state (3). To make the playlist visible to all users, the owner must explicitly set the playlist state back to “public” (4).

In the Spotify Web API, the Create a Playlist endpoint lets you decide whether a newly created playlist should start life as “public” or “private”. You can also change the current public/private status using the Change a Playlist’s Details endpoint. Requests to these endpoints require, of course, the appropriate scopes to have been granted by the user: playlist-modify-public to modify public playlists, and playlist-modify-private to modify private ones.

Note: Collaborative playlists are not currently supported by the Web API. Therefore applications cannot switch the status of a playlist to or from the “private, collaborative” status, nor can an application view or manage a collaborative playlist unless it has the playlist’s URI.

Reading a Playlist

To read a playlist, we first need to find it, and for that we need its Spotify ID. The Get a List of a User’s Playlists gives us an easy way to get basic details about all of the user’s non-collaborative playlists, including their IDs.

Note that this endpoint returns both the playlists the user owns and the playlists the user is following (excluding, of course, collaborative playlists).

Once we have a list of playlists we can retrieve the details of a specific playlist using the Web API’s Get a Playlist endpoint, and a list of its tracks using Get a Playlist’s Tracks. This last endpoint returns, in addition to an array of track objects, information about who added the track and when it was added. (The tracks themselves are wrapped in a paging object to make it easy to retrieve very large playlists when necessary.)

Version Control and Snapshots

The Web API provides several endpoints that allow playlists to be modified. These include Add tracks to a playlist, Remove tracks from a playlist, and Replace a playlist’s tracks.

Every change to a playlist is saved in its version history. This makes possible features such as offline availability and collaborative editing, or restoring an accidentally removed playlist. Every time you add, remove, or move a track, your modification is applied on top of all previous modifications, causing the playlist to enter a new state known as a snapshot.

Spotify Playlists Version Control and Snapshots

If you need it, the Spotify Web API allows you to leverage snapshots in order to handle concurrent changes. Web API playlist endpoints like Create a Playlist and Get a Playlist, return a snapshot_id in the response body. This can be used later to identify the specific playlist version to target for changes, for example when Removing Tracks from a Playlist. Concurrent changes are then automatically merged into the latest playlist version.

Following and Unfollowing a Playlist

Playlists can be followed or unfollowed programmatically through the Follow a Playlist and Unfollow a Playlist endpoints. Any playlist can be followed — public, private, and collaborative — provided you know the owner’s and the playlist’s Spotify IDs. When a user follows a playlist, the playlist’s owner will receive a notification in their Spotify client. When a track is added to a playlist, its followers will receive a notification in their Spotify client.

We have no endpoint for deleting a playlist in the Web API; the notion of deleting a playlist is not relevant within the Spotify’s playlist system. Even if you’re the playlist’s owner and you choose to manually remove it from your list of playlists, you are simply unfollowing it. Although this behavior may sound strange, it means that other users who are already following the playlist can keep enjoying it. Manually restoring a deleted playlist through the Spotify Accounts Service is the same thing as following one of your own playlists that you have previously unfollowed.

Using Playlist Images

Every playlist has an associated set of images which can be retrieved through Web API endpoints like Get a playlist. In most cases, there will be one image in a variety of sizes and the image will be a mosaic created from the album covers for the first few tracks:

cover-art-mosaic

The images array that’s returned can be a bit different depending how many tracks are in the playlist, and if the playlist has been manually “annotated”.

The images array contains:

– Nothing, if the playlist is empty, ie has no tracks

– An album cover of size 640×640, if the playlist contains 1-3 track(s) or tracks from less than 4 different releases.

– Three mosaic images of size 640×640, 300×300, 60×60, if the playlist contains 4+ tracks

The above is ignored if the playlist has had an image set manually —for example, for some curated playlists. There, the playlist image will be a single custom image (example). These images have various sizes.

The JSON returned by the Web API endpoints includes both the image dimensions (largest first) and a temporary link to the images:

...

"images" : [ {
"height" : 640,
"url" : "https://mosaic.scdn.co/640/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",
"width" : 640
}, {
"height" : 300,
"url" : "https://mosaic.scdn.co/300/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",
"width" : 300
}, {
"height" : 60,
"url" : "https://mosaic.scdn.co/60/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",
"width" : 60
} ],

...

Be aware that the links will expire in less than one day.

The use of album artwork in your applications is covered by our Developer Terms of Use. In particular you should be aware that you must display the album artwork in the form that we provide it (although you can resize it) and that you should not store album artwork except when it is strictly necessary to operate your application. You must also provide a link close to the cover art back to the full length track. We provide design resources to help you with this.