Endpoint

DELETE https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Request Parameters

Path Parameters

Path Parameter Value
playlist_id The Spotify ID for the playlist.

Header Fields

Header Field Value
Authorization Required. A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user. Removing items from a user’s public playlist requires authorization of the playlist-modify-public scope; removing items from a private playlist requires the playlist-modify-private scope. See Using Scopes.
Content-Type Required. The content type of the request body: application/json

There are several ways to specify which items to remove, determined by the request parameters.

Removing all occurrences of specific items

You can remove all occurrences of an item (or multiple items) by specifying only the item URI(s):

Request data Value type Value
tracks array of objects containing Spotify URI strings Required. An array of objects containing Spotify URIs of the tracks and episodes to remove. For example: { "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }, { "uri": "spotify:episode:512ojhOuo1ktJprKbVcKyQ" }] }. A maximum of 100 objects can be sent at once.

Removing a specific occurrence of an item

You can remove an item from a certain position by specifying both the item URI and the item position in the playlist. If you specify incorrect information (for example, if the given item does not exist at the given position) an error will be returned and the entire request will fail. If you specify multiple deletions and one is malformed, the entire request will be failed and no edits will take place.

Request data Value type Value
tracks array of objects containing Spotify URI strings and their position in the playlist Required. An array of objects containing Spotify URIs of the tracks and episodes to remove with their current positions in the playlist. For example:
{ "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "positions": [0,3] },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M", "positions": [7] }, { "uri": "spotify:episode:512ojhOuo1ktJprKbVcKyQ", "positions": [8] }] }
The positions parameter is zero-indexed, that is the first item in the playlist has the value 0 , the second item 1 , and so on.
A maximum of 100 objects can be sent at once.

Removing a specific occurrence of an item in a specific playlist snapshot

To guard against errors when concurrent edits happen to the same playlist, we recommend specifying a snapshot_id parameter. The snapshot_id lets us know which version of the playlist you are trying to edit. Concurrent edits by another user will be automatically resolved. If a given item in a given position is not found in the specified snapshot, the entire request will fail and no edits will take place.

Although this mechanism should help avoid errors from conflicting edits, you should always endeavor to use the most recent snapshot_id available.

Request data Value type Value
tracks array of objects containing Spotify URI strings and their position in the playlist Required. An array of objects containing Spotify URIs of the tracks and episodes to remove with their current positions in the playlist. For example:
{ "tracks":[{"uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "positions": [2] },{"uri": "spotify:track:1301WleyT98MSxVHPZCA6M", "positions": [7] }, { "uri": "spotify:episode:512ojhOuo1ktJprKbVcKyQ", "positions": [8] }] }
The positions parameter is zero-indexed, that is the first item in the playlist has the value 0 , the second item 1 , and so on.
A maximum of 100 objects can be sent at once.
snapshot_id string Optional. The playlist’s snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist.

Removing the item at a given position in a specific playlist snapshot

Instead of specifying the items’ URIs, this endpoint also accepts which positions to remove. To guard against errors during concurrent editing, this requires you to specify snapshot_id parameter.

Request data Value type Value
tracks array of objects containing Spotify URI strings and their position in the playlist Required. An array of objects containing Spotify URIs of the tracks and episodes to remove with their current positions in the playlist. For example:

{ "tracks":[{"uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "positions": [2] },{
"uri": "spotify:track:1301WleyT98MSxVHPZCA6M", "positions": [7] }, { "uri": "spotify:episode:512ojhOuo1ktJprKbVcKyQ", "positions": [8] }] }


The positions parameter is zero-indexed, that is the first item in the playlist has the value 0, the second item 1, and so on.

A maximum of 100 objects can be sent at once.
snapshot_id string Optional. The playlist’s snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist.

Response Format

On success, the response body contains a snapshot_id in JSON format and the HTTP status code in the response header is 200 OK. The snapshot_id can be used to identify your playlist version in future requests.

On error, the header status code is an error code and the response body contains an error object. Trying to remove a item when you do not have the user’s authorization returns error 403 Forbidden. Attempting to use several different ways to remove items returns 400 Bad Request. Other client errors returning 400 Bad Request include specifying invalid positions.

Example

Note that cURL requires quotation marks within the JSON data to be escaped, for example. \"spotify:track:1301WleyT98MSxVHPZCA6M\".

curl -X DELETE -i -H "Authorization: Bearer {your access token}" -H "Content-Type: application/json" "https://api.spotify.com/v1/playlists/71m0QB5fUFrnqfnxVerUup/tracks" --data "{\"tracks\":[{\"uri\": \"spotify:track:4iV5W9uYEdYUVa79Axb7Rh\", \"positions\": [2] },{\"uri\":\"spotify:track:1301WleyT98MSxVHPZCA6M\", \"positions\": [7] }] }"
HTTP/1.1 200 OK
{ "snapshot_id" : "JbtmHBDBAYu3/bt8BOXKjzKx3i0b6LCa/wVjyl6qQ2Yf6nFXkbmzuEa+ZI/U1yF+" }

Try it

Frequently Asked Questions

  • Is it possible to delete a playlist? No, it isn’t. The reason there is no endpoint for this is explained in our Working With Playlists Guide in the section Following and Unfollowing a Playlist.
  • Can I use X-HTTP-Method-Override or similar to send a DELETE request overriding the HTTP verb? Not at the moment, the delete operation needs to be specified through a DELETE request.

NOTE: looking for DELETE https://api.spotify.com/v1/users/{user_id}/playlists/{playlist_id}/tracks? Read the blog post.