Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)

Endpoint

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

Request Parameters

Path parameter
Value
user_id
The user's Spotify user ID.

Header field
Value
AuthorizationRequired. 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-TypeRequired. The content type of the request body: application/json

Request body dataValue typeValue
namestringRequired. 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.
publicBooleanOptional, default 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.

Note that the request data is a JSON string, not two 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 in our Web API Console

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_urlsan external URL object Known external URLs for this playlist.
followers
a followers object
Information about the followers of the playlist.
hrefstringA 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 objectThe user who owns the playlist
public
Boolean or nullThe 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_idstringThe version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version: see Remove tracks from a playlist
tracksarray of playlist track objects inside a paging object Information about the tracks of the playlist.
type
string
The object type: "playlist"
uristringThe Spotify URI for the playlist.