Skip to content
Web APIReferences / Playlists / Create Playlist

Create Playlist

Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.) Each user is generally limited to a maximum of 11000 playlists.

Authorization scopes

Request

supports free form additional properties
  • 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

    Defaults to true. The playlist's public/private status (if it should be added to the user's profile or not): true the playlist will be public, false the playlist will be private. To be able to create private playlists, the user must have granted the playlist-modify-private scope. For more about public/private status, see Working with Playlists

  • collaborative
    boolean

    Defaults to false. If true the playlist will be collaborative. Note: 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

    value for playlist description as displayed in Spotify Clients and in the Web API.

Response

A playlist

  • collaborative
    boolean

    true if the owner allows other users to modify the playlist.

  • description
    string
    Nullable

    The playlist description. Only returned for modified, verified playlists, otherwise null.

  • Known external URLs for this playlist.

  • Information about the followers of the playlist.

    • href
      string
      Nullable

      This will always be set to null, as the Web API does not support it at the moment.

    • total
      integer

      The total number of followers.

  • href
    string

    A link to the Web API endpoint providing full details of the playlist.

  • id
    string

    The Spotify ID for the playlist.

  • 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.

    • url
      string
      Required

      The source URL of the image.

      Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
    • height
      integer
      Required
      Nullable

      The image height in pixels.

      Example: 300
    • width
      integer
      Required
      Nullable

      The image width in pixels.

      Example: 300
  • name
    string

    The name of the playlist.

  • The user who owns the playlist

    • Known public external URLs for this user.

    • Information about the followers of this user.

      • href
        string
        Nullable

        This will always be set to null, as the Web API does not support it at the moment.

      • total
        integer

        The total number of followers.

    • href
      string

      A link to the Web API endpoint for this user.

    • id
      string

      The Spotify user ID for this user.

    • type
      string

      The object type.

      Allowed values: "user"
    • uri
      string

      The Spotify URI for this user.

    • display_name
      string
      Nullable

      The name displayed on the user's profile. null if not available.

  • public
    boolean

    The playlist's public/private status (if it is added to the user's profile): 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

  • The tracks of the playlist.

    • href
      string
      Required

      A link to the Web API endpoint returning the full result of the request

      Example: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
    • limit
      integer
      Required

      The maximum number of items in the response (as set in the query or by default).

      Example: 20
    • next
      string
      Required
      Nullable

      URL to the next page of items. ( null if none)

      Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
    • offset
      integer
      Required

      The offset of the items returned (as set in the query or by default)

      Example: 0
    • previous
      string
      Required
      Nullable

      URL to the previous page of items. ( null if none)

      Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
    • total
      integer
      Required

      The total number of items available to return.

      Example: 4
    • Required
      • added_at
        string [date-time]

        The date and time the track or episode was added. Note: some very old playlists may return null in this field.

      • The Spotify user who added the track or episode. Note: some very old playlists may return null in this field.

        • Known public external URLs for this user.

        • Information about the followers of this user.

          • href
            string
            Nullable

            This will always be set to null, as the Web API does not support it at the moment.

          • total
            integer

            The total number of followers.

        • href
          string

          A link to the Web API endpoint for this user.

        • id
          string

          The Spotify user ID for this user.

        • type
          string

          The object type.

          Allowed values: "user"
        • uri
          string

          The Spotify URI for this user.

      • is_local
        boolean

        Whether this track or episode is a local file or not.

      • track
        oneOf

        Information about the track or episode.

        Will be one of the following:
          • The album on which the track appears. The album object includes a link in href to full information about the album.

            • album_type
              string
              Required

              The type of the album.

              Allowed values: "album", "single", "compilation"Example: "compilation"
            • total_tracks
              integer
              Required

              The number of tracks in the album.

              Example: 9
            • available_markets
              array of strings
              Required

              The markets in which the album is available: ISO 3166-1 alpha-2 country codes. NOTE: an album is considered available in a market when at least 1 of its tracks is available in that market.

              Example: ["CA","BR","IT"]
            • Required

              Known external URLs for this album.

            • href
              string
              Required

              A link to the Web API endpoint providing full details of the album.

            • id
              string
              Required

              The Spotify ID for the album.

              Example: "2up3OPMp9Tb4dAKM2erWXQ"
            • Required

              The cover art for the album in various sizes, widest first.

              • url
                string
                Required

                The source URL of the image.

                Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
              • height
                integer
                Required
                Nullable

                The image height in pixels.

                Example: 300
              • width
                integer
                Required
                Nullable

                The image width in pixels.

                Example: 300
            • name
              string
              Required

              The name of the album. In case of an album takedown, the value may be an empty string.

            • release_date
              string
              Required

              The date the album was first released.

              Example: "1981-12"
            • release_date_precision
              string
              Required

              The precision with which release_date value is known.

              Allowed values: "year", "month", "day"Example: "year"
            • Included in the response when a content restriction is applied.

              • reason
                string

                The reason for the restriction. Albums may be restricted if the content is not available in a given market, to the user's subscription type, or when the user's account is set to not play explicit content. Additional reasons may be added in the future.

                Allowed values: "market", "product", "explicit"
            • type
              string
              Required

              The object type.

              Allowed values: "album"
            • uri
              string
              Required

              The Spotify URI for the album.

              Example: "spotify:album:2up3OPMp9Tb4dAKM2erWXQ"
            • Required

              The artists of the album. Each artist object includes a link in href to more detailed information about the artist.

              • Known external URLs for this artist.

              • href
                string

                A link to the Web API endpoint providing full details of the artist.

              • id
                string

                The Spotify ID for the artist.

              • name
                string

                The name of the artist.

              • type
                string

                The object type.

                Allowed values: "artist"
              • uri
                string

                The Spotify URI for the artist.

          • The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.

            • Known external URLs for this artist.

            • Information about the followers of the artist.

              • href
                string
                Nullable

                This will always be set to null, as the Web API does not support it at the moment.

              • total
                integer

                The total number of followers.

            • genres
              array of strings

              A list of the genres the artist is associated with. If not yet classified, the array is empty.

              Example: ["Prog rock","Grunge"]
            • href
              string

              A link to the Web API endpoint providing full details of the artist.

            • id
              string

              The Spotify ID for the artist.

            • Images of the artist in various sizes, widest first.

              • url
                string
                Required

                The source URL of the image.

                Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
              • height
                integer
                Required
                Nullable

                The image height in pixels.

                Example: 300
              • width
                integer
                Required
                Nullable

                The image width in pixels.

                Example: 300
            • name
              string

              The name of the artist.

            • popularity
              integer

              The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist's popularity is calculated from the popularity of all the artist's tracks.

            • type
              string

              The object type.

              Allowed values: "artist"
            • uri
              string

              The Spotify URI for the artist.

          • available_markets
            array of strings

            A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.

          • disc_number
            integer

            The disc number (usually 1 unless the album consists of more than one disc).

          • duration_ms
            integer

            The track length in milliseconds.

          • explicit
            boolean

            Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown).

          • Known external IDs for the track.

          • Known external URLs for this track.

          • href
            string

            A link to the Web API endpoint providing full details of the track.

          • id
            string

            The Spotify ID for the track.

          • is_playable
            boolean

            Part of the response when Track Relinking is applied. If true, the track is playable in the given market. Otherwise false.

          • Part of the response when Track Relinking is applied, and the requested track has been replaced with different track. The track in the linked_from object contains information about the originally requested track.

            • Included in the response when a content restriction is applied.

              • reason
                string

                The reason for the restriction. Supported values:

                • market - The content item is not available in the given market.
                • product - The content item is not available for the user's subscription type.
                • explicit - The content item is explicit and the user's account is set to not play explicit content.

                Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

            • name
              string

              The name of the track.

            • popularity
              integer

              The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
              The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.
              Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note: the popularity value may lag actual popularity by a few days: the value is not updated in real time.

            • preview_url
              string
              Nullable

              A link to a 30 second preview (MP3 format) of the track. Can be null

              Important policy note
            • track_number
              integer

              The number of the track. If an album has several discs, the track number is the number on the specified disc.

            • type
              string

              The object type: "track".

              Allowed values: "track"
            • uri
              string

              The Spotify URI for the track.

            • is_local
              boolean

              Whether or not the track is from a local file.

            • audio_preview_url
              string
              Required
              Nullable

              A URL to a 30 second preview (MP3 format) of the episode. null if not available.

              Important policy note
              Example: "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17"
            • description
              string
              Required

              A description of the episode. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

              Example: "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us."
            • html_description
              string
              Required

              A description of the episode. This field may contain HTML tags.

              Example: "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>"
            • duration_ms
              integer
              Required

              The episode length in milliseconds.

              Example: 1686230
            • explicit
              boolean
              Required

              Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown).

            • Required

              External URLs for this episode.

            • href
              string
              Required

              A link to the Web API endpoint providing full details of the episode.

              Example: "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ"
            • id
              string
              Required

              The Spotify ID for the episode.

              Example: "5Xt5DXGzch68nYYamXrNxZ"
            • Required

              The cover art for the episode in various sizes, widest first.

              • url
                string
                Required

                The source URL of the image.

                Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
              • height
                integer
                Required
                Nullable

                The image height in pixels.

                Example: 300
              • width
                integer
                Required
                Nullable

                The image width in pixels.

                Example: 300
            • is_externally_hosted
              boolean
              Required

              True if the episode is hosted outside of Spotify's CDN.

            • is_playable
              boolean
              Required

              True if the episode is playable in the given market. Otherwise false.

            • language
              string
              Deprecated

              The language used in the episode, identified by a ISO 639 code. This field is deprecated and might be removed in the future. Please use the languages field instead.

              Example: "en"
            • languages
              array of strings
              Required

              A list of the languages used in the episode, identified by their ISO 639-1 code.

              Example: ["fr","en"]
            • name
              string
              Required

              The name of the episode.

              Example: "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators"
            • release_date
              string
              Required

              The date the episode was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".

              Example: "1981-12-15"
            • release_date_precision
              string
              Required

              The precision with which release_date value is known.

              Allowed values: "year", "month", "day"Example: "day"
            • The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.

              • fully_played
                boolean

                Whether or not the episode has been fully played by the user.

              • resume_position_ms
                integer

                The user's most recent position in the episode in milliseconds.

            • type
              string
              Required

              The object type.

              Allowed values: "episode"
            • uri
              string
              Required

              The Spotify URI for the episode.

              Example: "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr"
            • Included in the response when a content restriction is applied.

              • reason
                string

                The reason for the restriction. Supported values:

                • market - The content item is not available in the given market.
                • product - The content item is not available for the user's subscription type.
                • explicit - The content item is explicit and the user's account is set to not play explicit content.

                Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

            • Required

              The show on which the episode belongs.

              • available_markets
                array of strings
                Required

                A list of the countries in which the show can be played, identified by their ISO 3166-1 alpha-2 code.

              • Required

                The copyright statements of the show.

                • text
                  string

                  The copyright text for this content.

                • type
                  string

                  The type of copyright: C = the copyright, P = the sound recording (performance) copyright.

              • description
                string
                Required

                A description of the show. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

              • html_description
                string
                Required

                A description of the show. This field may contain HTML tags.

              • explicit
                boolean
                Required

                Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown).

              • Required

                External URLs for this show.

              • href
                string
                Required

                A link to the Web API endpoint providing full details of the show.

              • id
                string
                Required

                The Spotify ID for the show.

              • Required

                The cover art for the show in various sizes, widest first.

                • url
                  string
                  Required

                  The source URL of the image.

                  Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
                • height
                  integer
                  Required
                  Nullable

                  The image height in pixels.

                  Example: 300
                • width
                  integer
                  Required
                  Nullable

                  The image width in pixels.

                  Example: 300
              • is_externally_hosted
                boolean
                Required

                True if all of the shows episodes are hosted outside of Spotify's CDN. This field might be null in some cases.

              • languages
                array of strings
                Required

                A list of the languages used in the show, identified by their ISO 639 code.

              • media_type
                string
                Required

                The media type of the show.

              • name
                string
                Required

                The name of the episode.

              • publisher
                string
                Required

                The publisher of the show.

              • type
                string
                Required

                The object type.

                Allowed values: "show"
              • uri
                string
                Required

                The Spotify URI for the show.

              • total_episodes
                integer
                Required

                The total number of episodes in the show.

    • type
      string

      The object type: "playlist"

    • uri
      string

      The Spotify URI for the playlist.

    endpointhttps://api.spotify.com/v1/users/{user_id}/playlistsuser_id

    Request body


    Response sample