Amazon Music Web API

Web API Playlist V1.0

Playlist

Methods for retrieving meta-data from playlists and updating playlists.

Get Playlist

GET
/playlists/{id}
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}
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
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
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
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 Multiple Playlists

DELETE
/playlists
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
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
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
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.

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

NAMEAscending by Playlist name
LAST_MODIFIED_DATEAscending by Playlist last modified date
FOLLOWERSDescending 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
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}
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}
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"
    }
  }
}