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
Update Playlist
Get Playlist Images
Get Multiple Playlists
Create Playlist
Delete Playlist
Delete Multiple Playlists [deprecated]
Get Playlist Tracks
Add Playlist Tracks
Delete Playlist Tracks
Update Playlist Tracks
Get Current User's Playlists
Get User Playlists
Add Followed Playlist For Current User
Remove Followed Playlist From Current User

Get Playlist

GET

/playlists/{id}

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

PUT

/playlists/{id}

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

GET

/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

POST

/playlists

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

DELETE

/playlists/{id}

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.

DELETE

/playlists

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.

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

GET

/me/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"
    }
  }
}