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 and episodes. 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 episodes; and the order in which to play them.

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


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). Note that users who are following the playlists will still be able to access it.

Spotify Playlist's Status Changes

A user can also choose to share a playlist with other users by making it collaborative (2). When the owner has made a playlist collaborative, users who have followed the playlist or who have the direct URI to it can see it 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. In order to be able to read a user’s collaborative playlists the scope playlist-read-collaborative is needed. Note that, when using the Web API, only the owner of a collaborative playlist can make changes to that playlist.

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.

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 a user’s playlists, including their IDs. This is, the playlists the user owns and the playlists the user is following, excluding collaborative playlists owned by other users. The set of playlists will be determined by the scopes granted to the application:

  • Owned and followed non-collaborative public playlists will be returned
  • Owned and followed non-collaborative private playlists will only be returned when the scope playlist-read-private has been granted
  • Owned and followed collaborative playlists will only be returned when the scope playlist-read-collaborative has been granted

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 items using Get a Playlist’s Items. This last endpoint returns, in addition to an array of track and episode objects (depending on the additional_types parameter), information about who added the item and when it was added. (The items themselves are wrapped in a paging object to make it easy to retrieve very large playlists when necessary.)

Local Files

A playlist may contain one or more local files. For more information on these, read Local Files in Spotify Playlists.


Folders are not returned through the Web API, nor can be created using it.

Version Control and Snapshots

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

Every change to a playlist is saved in its version history. This makes possible features such as offline availability and collaborative editing, and 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 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 when, for example, Removing Items 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 are the playlist’s owner and you choose to manually remove it from your own 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:


The images array that’s returned can vary depending on how many tracks are in the playlist, and if the playlist has been manually “annotated”. The images array can contain:

  • Nothing, if the playlist has no tracks and is empty,
  • An album cover of size 640×640, if the playlist contains 1 to 3 tracks or has tracks from less than 4 different albums,
  • Three mosaic images of size 640×640, 300×300, and 60×60, if the playlist contains tracks from 4 or more albums,
  • A single custom image (example) in various sizes, if the playlist image has been set manually — for example, for some curated playlists.

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" : "",
"width" : 640
}, {
"height" : 300,
"url" : "",
"width" : 300
}, {
"height" : 60,
"url" : "",
"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 Service. 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),
  • You should not store album artwork except when it is strictly necessary to operate your application, and
  • You must provide a link close to the cover art back to the full length track on Spotify. We provide design resources to help you with this.