The following documentation is automatically generated. Please do not edit this file, but rather the original, inline with Net::Async::Spotify::API::Generated::Playlists at lib/Net/Async/Spotify/API/Generated/Playlists.pm (on the system that originally ran this). If you do edit this file, and don't want your changes to be removed, make sure you change the first line.
Net::Async::Spotify::API::Generated::Playlists - Package representing Spotify Playlists API
Autogenerated module. Based on https://developer.spotify.com/documentation/web-api/reference/#reference-index Check crawl-api-doc.pl for more information.
crawl-api-doc.pl
add_tracks_to_playlist - Add Items to a Playlist
Add one or more items to a user’s playlist.
with Request details being:
Type: string | Required: 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.Adding items to the current user’s public playlists requires authorization of the playlist-modify-public scope; adding items to the current user’s private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.
Type: string | Required: required Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Type: integer | Required: optional The position to insert the items, a zero-based index. For example, to insert the items in the first position: position=0 ; to insert the items in the third position: position=2. If omitted, the items will be appended to the playlist. Items are added in the order they appear in the uris array. For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M"], "position": 3}
Type: array[string] | Required: optional A JSON array of the Spotify URIs to add. For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}A maximum of 100 items can be added in one request. Note: if the uris parameter is present in the query string, any URIs listed here in the body will be ignored.
Type: string | Required: required The Spotify ID for the playlist.
Type: integer | Required: optional The position to insert the items, a zero-based index. For example, to insert the items in the first position: position=0; to insert the items in the third position: position=2 . If omitted, the items will be appended to the playlist. Items are added in the order they are listed in the query string or request body.
Type: string | Required: optional A comma-separated list of Spotify URIs to add, can be track or episode URIs. For example:uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQA maximum of 100 items can be added in one request. Note: it is likely that passing a large number of item URIs as a query parameter will exceed the maximum length of the request URI. When adding a large number of items, it is recommended to pass them in the request body, see below.
and Response Objects being:
- error object
On success, the HTTP status code in the response header is 201 Created. The response body contains a snapshot_id in JSON format. 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 add an item when you do not have the user’s authorization, or when there are more than 10.000 items in the playlist, returns error 403 Forbidden.Try in our Web Console
change_playlist_details - Change a Playlist's Details
Change a playlist’s name and public/private state. (The user must, of course, own the playlist.)
Type: string | Required: 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.Changing a public playlist for a user requires authorization of the playlist-modify-public scope; changing a private playlist requires the playlist-modify-private scope. See Using Scopes.
Type: string | Required: required The content type of the request body: application/json
Type: boolean | Required: optional If true , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. Note: You can only set collaborative to true on non-public playlists.
Type: string | Required: optional Value for playlist description as displayed in Spotify Clients and in the Web API.
Type: string | Required: optional The new name for the playlist, for example "My New Playlist Title"
Type: boolean | Required: optional If true the playlist will be public, if false it will be private.
On success the HTTP status code in the response header is 200 OK.On error, the header status code is an error code and the response body contains an error object. Trying to change a playlist when you do not have the user’s authorization returns error 403 Forbidden.Try in our Web Console
create_playlist - Create a Playlist
Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
Type: string | Required: 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.
Type: string | Required: optional The content type of the request body: application/json
Type: boolean | Required: 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 .
Type: string | Required: optional value for playlist description as displayed in Spotify Clients and in the Web API.
Type: string | Required: 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.
Type: boolean | Required: 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
Type: string | Required: required The user’s Spotify user ID.
- playlist object - error object
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.Try in our Web Console
get_a_list_of_current_users_playlists - Get a List of Current User's Playlists
Get a list of the playlists owned or followed by the current Spotify user.
Type: string | Required: required A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.Private playlists are only retrievable for the current user and requires the playlist-read-private scope to have been authorized by the user. Note that this scope alone will not return collaborative playlists, even though they are always private.Collaborative playlists are only retrievable for the current user and requires the playlist-read-collaborative scope to have been authorized by the user.
Type: integer | Required: optional ‘The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.’
Type: integer | Required: optional ‘The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.’
- playlist object
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object. Please note that the access token has to be tied to a user.Try in our Web Console
get_list_users_playlists - Get a List of a User's Playlists
Get a list of the playlists owned or followed by a Spotify user.
Type: integer | Required: optional The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.
Type: integer | Required: optional The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.
On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.Try in our Web Console
get_playlist - Get a Playlist
Get a playlist owned by a Spotify user.
Type: string | Required: required A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. Both Public and Private playlists belonging to any user are retrievable on provision of a valid access token.
Type: string | Required: optional A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the type field of each object.
Type: string | Required: optional Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist’’s description and URI: fields=description,uri. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: fields=tracks.items(added_at,added_by.id). Use multiple parentheses to drill down into nested objects, for example: fields=tracks.items(track(name,href,album(name,href))). Fields can be excluded by prefixing them with an exclamation mark, for example: fields=tracks.items(track(name,href,album(!name,href)))
Type: string | Required: optional An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. Note: If neither market or user country are provided, the episode is considered unavailable for the client.
On success, the response body contains a playlist object in JSON format and the HTTP status code in the response header is 200 OK. If an episode is unavailable in the given market, its information will not be included in the response. On error, the header status code is an error code and the response body contains an error object. Requesting playlists that you do not have the user’s authorization to access returns error 403 Forbidden.Try in our Web Console
get_playlist_cover - Get a Playlist Cover Image
Get the current image associated with a specific playlist.
Type: string | Required: 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.This access token must be issued on behalf of the user. Current playlist image for both Public and Private playlists of any user are retrievable on provision of a valid access token.
- image object
On success, the response body contains a list of image objects in JSON format and the HTTP status code in the response header is 200 OK On error, the header status code is an error code and the response body contains an error object.Try in our Web Console
get_playlists_tracks - Get a Playlist's Items
Get full details of the items of a playlist owned by a Spotify user.
Type: string | Required: optional Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit:fields=total,limitA dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder:fields=items(added_at,added_by.id)Use multiple parentheses to drill down into nested objects, for example:fields=items(track(name,href,album(name,href)))Fields can be excluded by prefixing them with an exclamation mark, for example:fields=items.track.album(!external_urls,images)
Type: integer | Required: optional The maximum number of items to return. Default: 100. Minimum: 1. Maximum: 100.
Type: string | Required: required An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. Note: If neither market or user country are provided, the episode is considered unavailable for the client.
Type: integer | Required: optional The index of the first item to return. Default: 0 (the first object).
- track object
On success, the response body contains an array of track objects and episode objects (depends on the additional_types parameter), wrapped in a paging object in JSON format and the HTTP status code in the response header is 200 OK. If an episode is unavailable in the given market, its information will not be included in the response. On error, the header status code is an error code and the response body contains an error object. Requesting playlists that you do not have the user’s authorization to access returns error 403 Forbidden.Try in our Web Console
remove_tracks_playlist - Remove Items from a Playlist
Remove one or more items from a user’s playlist.
Type: string | Required: 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.
Type: string | Required: 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.
Type: array[string] | Required: required An array of objects containing Spotify URIs of the tracks or episodes to remove. For example: { "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }. A maximum of 100 objects can be sent at once.
Type: string | Required: required The Spotify ID
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 an 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.Notes### 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.Try in our Web Console
reorder_or_replace_playlists_tracks - Reorder or Replace a Playlist's Items
Either reorder or replace items in a playlist depending on the request’s parameters. To reorder items, include range_start, insert_before, range_length and snapshot_id in the request’s body. To replace items, include uris as either a query parameter or in the request’s body. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.
Note: Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters. These operations can’t be applied together in a single request.
Type: string | Required: 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. Reordering or replacing items in the current user’s public playlists requires authorization of the playlist-modify-public scope; reordering or replacing items in the current user’s private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.
Type: string | Required: optional Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Type: integer | Required: optional The position where the items should be inserted.To reorder the items to the end of the playlist, simply set insert_before to the position after the last item.Examples:To reorder the first item to the last position in a playlist with 10 items, set range_start to 0, and insert_before to 10.To reorder the last item in a playlist with 10 items to the start of the playlist, set range_start to 9, and insert_before to 0.
Type: integer | Required: optional The amount of items to be reordered. Defaults to 1 if not set.The range of items to be reordered begins from the range_start position, and includes the range_length subsequent items.Example:To move the items at index 9-10 to the start of the playlist, range_start is set to 9, and range_length is set to 2.
Type: integer | Required: optional The position of the first item to be reordered.
Type: string | Required: optional The playlist’s snapshot ID against which you want to make the changes.
Type: array[string] | Required: optional
Type: string | Required: optional A comma-separated list of Spotify URIs to set, can be track or episode URIs. For example: uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQA maximum of 100 items can be set in one request.
On a successful reorder operation, 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 a successful replace operation, the HTTP status code in the response header is 201 Created.On error, the header status code is an error code, the response body contains an error object, and the existing playlist is unmodified. Trying to set an item when you do not have the user’s authorization returns error 403 Forbidden.Try in our Web Console
upload_custom_playlist_cover - Upload a Custom Playlist Cover Image
Replace the image used to represent a specific playlist.
Type: string | Required: 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.This access token must be tied to the user who owns the playlist, and must have the scope ugc-image-upload granted. In addition, the token must also contain playlist-modify-public and/or playlist-modify-private, depending the public status of the playlist you want to update . See Using Scopes.
Type: string | Required: required The content type of the request body: image/jpeg
If you get status code 429, it means that you have sent too many requests. If this happens, have a look in the Retry-After header, where you will see a number displayed. This is the amount of seconds that you need to wait, before you can retry sending your requests.NotesThe request should contain a Base64 encoded JPEG image data, maximum payload size is 256 KB.Rate Limiting: If you get status code 429, it means that you have sent too many requests. If this happens, have a look in the Retry-After header, where you will see a number displayed. This is the amount of seconds that you need to wait, before you can retry sending your requests.Try in our Web Console
call_api, decode_response, new, parse_response, spotify
To install Net::Async::Spotify, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Async::Spotify
CPAN shell
perl -MCPAN -e shell install Net::Async::Spotify
For more information on module installation, please visit the detailed CPAN module installation guide.