Amazon Music Web API
Web API Playlist V1.0
Important:
These Amazon Music documents are in preview status. Be aware that content may change. Please use the
developer forum for any questions or comments.
Playlist
Methods for retrieving meta-data from playlists and updating playlists.
Get Playlist
Authorization Scope: [music::library]
Get playlist meta-data for a playlist owned by an Amazon Music user. This includes the title of the playlist and the track count. Does not include playlist tracks (see
GET /playlists/{id}/tracks).
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to be retrieved. |
Example
curl --request GET 'https://api.music.amazon.dev/v1/playlists/4a5afe86-7316' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing a playlist:
Name |
Data Type |
Required |
Description |
playlist
|
playlist
|
No |
The playlist data requested |
Example
{
"data": {
"playlist": {
"id": "4a5afe86-7316",
"curator": {
"id": "yy7aiqasggy2violdby46fka"
},
"duration": 19988,
"images": [
{
"url": "https://m.media-amazon.com/images/I/818RHu4x47L.jpg",
"imageType": "PRIMARY"
}
],
"eligibility": {
"playback": {
"canPlayOnDemand": true,
"shuffleType": "INLINE"
},
"playbackSubscriptionTiers": [],
"isDownloadable": false,
"isPurchaseable": false,
"isPreviewable": false,
"isPrimeEligible": false
},
"title": "A day of Pink Floyd",
"trackCount": 59,
"url": "https://music.amazon.com/my/playlists/c49978fe-f7f7",
"visibility": "PRIVATE"
}
}
}
Update Playlist
Authorization Scope: [music::library]
Update playlist meta-data for a playlist owned by an Amazon Music user. This includes the title of the playlist description and visibility. Does not include playlist tracks (see
PUT or
PATCH /playlists/{id}/tracks).
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to be updated. |
Request Body Parameters
Name |
Data Type |
Required |
Description |
title
|
string
|
Yes |
The new title to assign to the updated playlist. |
description
|
string
|
Yes |
The new description to assign to the updated playlist. |
visibility
|
string
|
Yes |
The visibility setting to assign to the updated playlist. Valid values are PUBLIC and PRIVATE. |
Example
curl --request PUT 'https://api.music.amazon.dev/v1/playlists/4a5afe86-7316' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'title=One of these days' \
--data-urlencode 'description=A day of Pink Floyd' \
--data-urlencode 'visibility=PUBLIC'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
updatePlaylist
|
Playlist
|
No |
Data about the updated Amazon Music playlist |
Example
{
"data": {
"updatePlaylist": {
"id": "4a5afe86-7316-4faf-9956-b7f38f6f7900",
"curator": {
"id": "yy7aiqay2violdby6dcpo46fka"
},
"title": "One of these days",
"url": "https://music.amazon.com/my/playlists/c49978fe-f7f7",
"visibility": "PUBLIC",
"description": "A day of Pink Floyd"
}
}
Get Playlist Images
GET
/playlists/{id}/images
Authorization Scope: [music::catalog]
Get playlist cover images for the specified playlist.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to retrieve. |
Example
curl --request GET 'https://api.music.amazon.dev/v1/playlists/4a5afe86/images' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object a play list object containing only the Array of Images for the specified playlist:
Name |
Data Type |
Required |
Description |
playlist
|
playlist
|
No |
A playlist object containing an Array of Images |
Example
{
"data": {
"playlist": {
"id": "8af45217-71d5-48dd-a9e8-fead406625f9",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 2339,
"images": [
{
"url": "https://m.media-amazon.com/images/I/61tFaqrPBxL.jpg"
}
],
"title": "some funky music",
"trackCount": 12,
"url": "https://music.amazon.ca/my/playlists/00cc5447"
}
}
}
Get Multiple Playlists
Authorization Scope: [music::library]
Get the meta-data for multiple user playlists identified by comma-separated catalog IDs. This includes the title of the playlist and the track count. Does not include playlist tracks (see Get Playlist Tracks).
Path Parameters
Name |
Data Type |
Required |
Description |
ids
|
string
|
Yes |
A comma-separated list of the Amazon Music IDs for the playlists. Maximum: 100 IDs. |
Example
curl --request GET 'https://api.music.amazon.dev/v1/playlists?ids=B01IQC56L6,B08L1BWKNG' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
playlist
|
Playlist[]
|
No |
An array of playlists |
Example
{
"data": {
"playlists": [
{
"id": "8af45217-71d5-48dd-a9e8-fead406625f9",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 2339,
"images": [
{
"height": null,
"width": null,
"url": "https://m.media-amazon.com/images/I/61tFaqrPBxL.jpg"
}
],
"title": "Testing CA Playlist",
"trackCount": 12,
"url": "https://music.amazon.ca/my/playlists/00cc5447-8ca2"
}
]
}
}
Create Playlist
Authorization Scope: [music::library]
Create a playlist for an Amazon Music user. Returns an object which includes the ID of the newly-created playlist.
Body Parameters
Name |
Data Type |
Required |
Description |
title
|
string
|
Yes |
The title of the playlist to be created. |
description
|
string
|
Yes |
The description of the playlist to be created. |
visibility
|
string
|
Yes |
Specifies whether the playlist to be created should be publically visible or visible to the user only. This is an enumerated type. The allowed values are PUBLIC and PRIVATE. |
Example
curl --request POST 'https://api.music.amazon.dev/v1/playlists' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{"title":"My Playlist", \
"description":"Amazing Songs", \
"visibility":"PRIVATE"}'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
createPlaylist
|
Playlist
|
No |
Data about the newly created Amazon Music playlist |
Example
{
"data": {
"createPlaylist": {
"id": "c7c68ef6-5002-49f6-bf78-93a54a9fbd4e",
"curator": {
"id": "yy7aiqay2violdby6dcpo46fka"
},
"title": "My Playlist",
"url": "https://music.amazon.com/my/playlists/d74b9e47",
"visibility": "PUBLIC",
"description": "Deep Purple songs"
}
}
}
Delete Playlist
Authorization Scope: [music::library]
Delete specified playlist for the current Amazon Music user.
Query Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to delete. |
Example
curl --request Delete 'https://api.music.amazon.dev/v1/playlists/4a5afe86' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
deletePlaylists
|
Response
|
No |
Data about the removed Amazon Music playlists |
Example
{
"data": {
"deletePlaylist": {
"id": 'b8619c5c-5190-4020-813f-eefc7650c8cb',
"isDeleted": true,
}
}
Delete Multiple Playlists [deprecated]
Warning: This API has been deprecated and should not be used. Please utilize the Delete Playlist API instead.
Authorization Scope: [music::library]
Delete owned playlists for a specified Amazon Music user.
Body Parameters
Name |
Data Type |
Required |
Description |
ids
|
string
|
Yes |
A comma-separated list of the Amazon Music IDs for the playlists. Maximum: 100 IDs. |
Example
curl --request Delete 'https://api.music.amazon.dev/v1/playlists' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{"ids":["f1e0f6ad1e8741718a1930c458d9771fsune", \
"37ad21b55b8a4e4a87975cd9d1ebbb63sune"]}'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
deletePlaylists
|
Response
|
No |
Data about the removed Amazon Music playlists |
Example
{
"data": {
"deletePlaylists": {
"deletedPlaylists": [
"f1e0f6ad1e8741718a1930c458d9771fsune",
"37ad21b55b8a4e4a87975cd9d1ebbb63sune"
]
}
}
}
Get Playlist Tracks
GET
/playlists/{id}/tracks
Authorization Scope: [music::library:read]
Get a list of tracks and associated meta-data for the specified playlist. The tracks can be paginated based on a specified page size, and a specific page may be requested.
Learn more about pagination.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to be retrieved. |
Query Parameters
Name |
Data Type |
Required |
Description |
limit
|
number
|
No |
The maximum number of tracks to return (default: 100). Minimum of 1, maximum of 100. |
cursor
|
string
|
No |
The cursor/token for the page to continue pagination results from. |
curl --request GET 'https://api.music.amazon.dev/v1/playlists/4a5afe86/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
playlist
|
Playlist
|
No |
Playlist data including a list of tracks |
Example
{
"data": {
"playlist": {
"id": "8af45217-71d5-48dd-a9e8-fead406625f9",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 2339,
"images": [
{
"height": null,
"width": null,
"url": "https://m.media-amazon.com/images/I/61tFaqrPBxL.jpg"
}
],
"title": "Testing CA Playlist",
"trackCount": 1,
"url": "https://music.amazon.ca/my/playlists/00cc5447",
"tracks": {
"pageInfo": {
"hasNextPage": true,
"token": "1:71c1c7a7-b2c9-416e-87b9-09cc2bb8f37d"
},
"edgeCount": 1,
"edges": [
{
"cursor": "0:f71687e4-8826-4bd6-b0b0-e5f51f3a9394",
"node": {
"id": "B08VZYTCC5",
"title": "I Lost Myself (feat. Anna Clendening)",
"url": "https://music.amazon.ca/albums/B08VZKXRMB/?trackAsin=B08VZYTCC5"
}
}
]
}
}
}
}
Add Playlist Tracks
PUT
/playlists/{id}/tracks
Authorization Scope: [music::library]
Add one or more tracks to a user’s playlist.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to append tracks to. |
Body Parameters
Name |
Data Type |
Required |
Description |
trackIds
|
array of strings
|
Yes |
A list of track IDs to append to the user’s playlist. |
addDuplicateTracks
|
Boolean
|
No |
A flag to indicate if a track should be added if it already exists in the playlist. DEFAULT = false |
Example
curl --request PUT 'https://api.music.amazon.dev/v1/playlists/a4808cb8/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{"trackIds":["B0BCP462HB"], \
"addDuplicateTracks": false}'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
appendTracks
|
Playlist
|
No |
Data about the Amazon Music playlist that was updated. null if the update failed |
Example
{
"data": {
"appendTracks": {
"id": "173a15e0-24f8-4cc1-bc32-e0cc658085c6",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"title": "New Beginnings",
"url": "https://music.amazon.ca/my/playlists/0725803e"
}
}
}
Errors
Response |
Code |
Status |
Message |
400
|
BAD_REQUEST |
400 |
The request could not be accepted because it would cause the playlist to contain duplicate tracks. |
Delete Playlist Tracks
DELETE
/playlists/{id}/tracks
Authorization Scope: [music::library]
Delete one or more tracks from a user’s playlist.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The ID of the playlist to delete tracks from. |
Body Parameters
Name |
Data Type |
Required |
Description |
entryIds
|
array of strings
|
Yes |
The playlist track entry IDs of the tracks to be removed from the playlist. |
Important:
The entry ids are not the same as track IDs. They represent the playlist entry position. You can find them when calling GET /playlists/{id}/tracks in the edge array containing the tracks, the cursor parameter contains the entry id. The entry id is the part of the cursor following the colon.
i.e. cursor: <array index>:<entryID>
Example
curl --request DELETE 'https://api.music.amazon.dev/v1/playlists/a4808cb84ac/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{"entryIds":["b6b4deec-f210-4efb-b483-e593d868dff5", "4a06378a-8036-4843-8cc4-450dcbde76f2"]}'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
removeTracks
|
Response
|
No |
data about the playlist that had tracks deleted |
Example
{
"data": {
"removeTracks": {
"id": "173a15e0-24f8-4cc1-bc32-e0cc658085c6",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"title": "New Beginnings",
"url": "https://music.amazon.ca/my/playlists/0725803e-5c68"
}
}
}
Update Playlist Tracks
PATCH
/playlists/{id}/tracks
Authorization Scope: [music::library]
Move one or more items in a specified playlist that belongs to the current Amazon Music user.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The playlist ID of the playlist to update. |
Body Parameters
Name |
Data Type |
Required |
Description |
entryIds
|
array of strings
|
Yes |
List of playlist entry IDs to be moved. |
entryIdAbove
|
string
|
Yes |
The playlist entry ID of the track which should now preceed the track(s) being moved. |
entryIdBelow
|
string
|
Yes |
The playlist entry ID of the track which should now come after the track(s) being moved. |
Important:
The entry ids are not the same as track IDs. They represent the playlist entry position. You can find them when calling GET /playlists/{id}/tracks in the edge array containing the tracks, the cursor parameter contains the entry id. The entry id is the part of the cursor following the colon.
i.e. cursor: <array index>:<entryID>
Example
curl --request PATCH 'https://api.music.amazon.dev/v1/playlists/a4808cb84a/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{"entryIds":["502fc762-fae3-4f5a-af2d-21cc9c8ea49d"], \
"entryIdAbove":"c9fe2bbf-4a44-4fc5-b9af-7740a2377d6e", \
"entryIdBelow":"c2a1696b-c6f7-4320-b93a-99742fcca4b1"}' \
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
moveTracks
|
Playlist
|
No |
Data about the updated Amazon Music playlist |
Example
{
"data": {
"moveTracks": {
"id": "a4808cb84a",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"title": "New Beginnings",
"url": "https://music.amazon.ca/my/playlists/0725803e-5c68"
}
}
}
Get Current User's Playlists
Authorization Scope: [music::library:read]
Get a list of the playlists owned by the current Amazon Music user. Optional parameters can be used to limit the number of playlists returned.
Learn more about pagination.
Query Parameters
Name |
Data Type |
Required |
Description |
limit
|
number
|
No |
The maximum number of playlists to return (default: 100). Minimum of 1, maximum of 100. |
cursor
|
string
|
No |
The cursor/token for the page to continue pagination results from. |
sortBy
|
PlaylistSortBy
|
No |
Specify the sort order of the returned List. Default = NAME |
PlaylistSortBy
enum
NAME | Ascending by Playlist name |
LAST_MODIFIED_DATE | Ascending by Playlist last modified date |
FOLLOWERS | Descending by number of followers for the Playlist |
Example
curl --request GET '<base url>/v1/me/playlists?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing a response collection of the current users playlists.
Name |
Data Type |
Required |
Description |
browseCategories
|
Response Collection
|
No |
Collection of playlists owned by the current user |
Example
{
"data": {
"user": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom",
"playlists": {
"pageInfo": {
"hasNextPage": false
},
"edgeCount": 2,
"edges": [
{
"cursor": "0:15e6a15f-4c2f-4b24-a2fd-286b37ad4fa3",
"node": {
"id": "15e6a15f-4c2f-4b24-a2fd-286b37ad4fa3",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 3450,
"images": [
{
"url": "https://images-na.ssl-images-amazon.com/images/Playlists.png",
"imageType": "PRIMARY"
}
],
"eligibility": {
"playback": {
"canPlayOnDemand": true,
"shuffleType": "INLINE"
},
"playbackSubscriptionTiers": [],
"isDownloadable": false,
"isPurchaseable": false,
"isPreviewable": false,
"isPrimeEligible": false
},
"title": "00 Rock",
"trackCount": 12,
"url": "https://music.amazon.ca/my/playlists/b2c6606b",
"visibility": "PRIVATE"
}
},
{
"cursor": "1:28a56e15-99ea-4e0b-989e-2ba8b19c1aae",
"node": {
"id": "28a56e15-99ea-4e0b-989e-2ba8b19c1aae",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 1084,
"images": [
{
"url": "https://m.media-amazon.com/images/I/81P1PrmwR5L.jpg"
}
],
"title": "311 Day",
"trackCount": 6,
"url": "https://music.amazon.ca/my/playlists/1e858b97"
}
}
]
}
}
}
}
Get User Playlists
GET
/users/{id}/playlists
Authorization Scope: [music::catalog]
Retrieve a list of public playlists owned by a specified Amazon Music user. Optional parameters can be used to limit the number of playlists returned.
Learn more about pagination.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The requested user’s Amazon Music ID. |
Query Parameters
Name |
Data Type |
Required |
Description |
limit
|
number
|
No |
The maximum number of playlists to return (default: 100). Minimum of 1, maximum of 100. |
cursor
|
string
|
No |
The cursor/token for the page to continue pagination results from. |
curl --request GET 'https://api.music.amazon.dev/v1/users/<userID>/playlists?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing a response collection of the current users playlists.
Name |
Data Type |
Required |
Description |
user
|
Response Collection
|
No |
Data about the requested Amazon Music user, including playlists |
Example
{
"data": {
"user": {
"id": "someuserid",
"playlists": {
"pageInfo": {
"hasNextPage": false
},
"edgeCount": 2,
"edges": [
{
"cursor": "0:15e6a15f-4c2f-4b24-a2fd-286b37ad4fa3",
"node": {
"id": "15e6a15f-4c2f-4b24-a2fd-286b37ad4fa3",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 0,
"images": [
{
"url": "https://images.i-amazon.com/images/Playlistspx.png"
}
],
"title": "Automation Playlist CA",
"trackCount": 0,
"url": "https://music.amazon.ca/my/playlists/b2c6606b"
}
},
{
"cursor": "1:28a56e15-99ea-4e0b-989e-2ba8b19c1aae",
"node": {
"id": "28a56e15-99ea-4e0b-989e-2ba8b19c1aae",
"curator": {
"id": "6ozjgidgbvjdv3j6dd5jm7ipom"
},
"duration": 1084,
"images": [
{
"url": "https://m.media-amazon.com/images/I/81P1PrmwR5L.jpg"
}
],
"title": "testAutomationPlaylist_CA_141",
"trackCount": 6,
"url": "https://music.amazon.ca/my/playlists/1e858b97-4025-4bc9"
}
}
]
}
}
}
}
Add Followed Playlist For Current User
PUT
/me/followed/playlists/{id}
Authorization Scope: [music::favorites:read]
Add the current user as a follower of a specified playlist.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The Amazon Music ID of the playlist to make the current user follow. |
Example
curl --request PUT <base url>/v1/me/followed/playlists/B01LS62KK2
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
followPlaylist
|
Response
|
No |
Data about the Amazon Music playlist that has been followed |
Example
{
"data": {
"followPlaylist": {
"playlist": {
"id": "B01LS62KK2",
"name": "CLASSIC ROCK HITS",
"url": "https://music.amazon.com/playlists/B01LS62KK2"
},
"followState": "FOLLOW"
}
}
}
Remove Followed Playlist From Current User
DELETE
/me/followed/playlists/{id}
Authorization Scope: [music::favorites]
Remove the specified playlist from the current Amazon Music user’s followed playlists.
Path Parameters
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
The catalog ID of the playlist to remove from the current user’s followed playlists. |
Example
curl --request DELETE <base url>/v1/me/followed/playlists/B01LS62KK2
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
unfollowPlaylist
|
Response
|
No |
Data about the Amazon Music playlist that has been unfollowed |
Example
{
"data": {
"unfollowPlaylist": {
"playlist": {
"id": "B01LS62KK2",
"name": "CLASSIC ROCK HITS",
"url": "https://music.amazon.com/playlists/B01LS62KK2"
},
"followState": "UNFOLLOW"
}
}
}