Endpoint

POST https://api.spotify.com/v1/users/{user_id}/playlists

Request Parameters

Path Parameters

Path Parameter Value
user_id The user’s Spotify user ID.

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. Creating a public playlist for a user requires authorization of the playlist-modify-public scope; creating a private playlist requires the playlist-modify-private scope. See Using Scopes.
Content-Type Required. The content type of the request body: application/json

Body Parameters

Request Body Data Value Type Value
name string Required. The name for the new playlist, for example "Your Coolest Playlist" . This name does not need to be unique; a user may have several playlists with the same name.
public Boolean Optional. Defaults to true . If true the playlist will be public, if false it will be private. To be able to create private playlists, the user must have granted the playlist-modify-private scope .
collaborative Boolean Optional. Defaults to false . If true the playlist will be collaborative. Note that to create a collaborative playlist you must also set public to false . To create collaborative playlists you must have granted playlist-modify-private and playlist-modify-public scopes .
description string Optional. value for playlist description as displayed in Spotify Clients and in the Web API.

Note that the request data is a JSON string, not three separate fields.

Response Format

On success, the response body contains the created playlist object in JSON format and the HTTP status code in the response header is 200 OK or 201 Created. There is also a Location response header giving the Web API endpoint for the new playlist.

On error, the header status code is an error code and the response body contains an error object. Trying to create a playlist when you do not have the user’s authorization returns error 403 Forbidden.

Example

Note that cURL requires quotation marks within the JSON data to be escaped, for example. \"public\":false.

curl -X POST "https://api.spotify.com/v1/users/thelinmichael/playlists" -H "Authorization: Bearer {your access token}" -H "Content-Type: application/json" --data "{\"name\":\"A New Playlist\", \"public\":false}"
{
   "collaborative": false,
   "description": null,
   "external_urls": {
     "spotify": "http://open.spotify.com/user/thelinmichael/playlist/7d2D2S200NyUE5KYs80PwO"
   },
   "followers": {
     "href": null,
     "total": 0
   },
   "href": "https://api.spotify.com/v1/users/thelinmichael/playlists/7d2D2S200NyUE5KYs80PwO",
   "id": "7d2D2S200NyUE5KYs80PwO",
   "images": [ ],
   "name": "A New Playlist",
   "owner": {
     "external_urls": {
       "spotify": "http://open.spotify.com/user/thelinmichael"
     },
     "href": "https://api.spotify.com/v1/users/thelinmichael",
     "id": "thelinmichael",
     "type": "user",
     "uri": "spotify:user:thelinmichael"
   },
   "public": false,
   "snapshot_id": "s0o3TSuYnRLl2jch+oA4OEbKwq/fNxhGBkSPnvhZdmWjNV0q3uCAWuGIhEx8SHIx",
   "tracks": {
     "href": "https://api.spotify.com/v1/users/thelinmichael/playlists/7d2D2S200NyUE5KYs80PwO/tracks",
     "items": [ ],
     "limit": 100,
     "next": null,
     "offset": 0,
     "previous": null,
     "total": 0
   },
 "type": "playlist",
 "uri": "spotify:user:thelinmichael:playlist:7d2D2S200NyUE5KYs80PwO"
}

Try it

playlist object (full)

Key Value Type Value Description
collaborative Boolean true if the owner allows other users to modify the playlist.
description string The playlist description. Only returned for modified, verified playlists, otherwise null.
external_urls an external URL object Known external URLs for this playlist.
followers a followers object Information about the followers of the playlist.
href string A link to the Web API endpoint providing full details of the playlist.
id string The Spotify ID for the playlist.
images an array of image objects Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See Working with Playlists. Note: If returned, the source URL for the image ( url ) is temporary and will expire in less than a day.
name string The name of the playlist.
owner a public user object The user who owns the playlist
public Boolean or null The playlist’s public/private status: true the playlist is public, false the playlist is private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists.
snapshot_id string The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version: see Remove tracks from a playlist
tracks array of playlist track objects inside a paging object Information about the tracks of the playlist.
type string The object type: “playlist”
uri string The Spotify URI for the playlist.