Amazon Music Web API

Web API Browse V1.0

Important: These Amazon Music APIs are currently in a closed Beta. To join the waitlist, select 'Music Developers' in the contact us form here.

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.

Browse

Browse the Amazon Music catalog based on the current user’s listening preferences.

Get Top Tracks
Get Top Playlists
Get New Podcast Episodes
Get All Categories
Get Category
Get Albums By Category
Get Playlists By Category
Get Tracks By Category

Get Top Tracks

GET

/browse/tracks/top

Authorization Scope: [music::catalog]

Get a list of Top Tracks featured on Amazon Music, based on analysis of the current user’s listening history. Optional parameters can be used to limit the number of tracks returned.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	The maximum number of tracks to return (default: 20). Minimum of 1, maximum of 20.
cursor	string	No	The cursor/token for the page to continue pagination results from.

Example

curl --request GET '<base url>/v1/browse/tracks/top?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of top tracks for this user.

Name	Data Type	Required	Description
topTracks	Response Collection	No	Collection of top tracks for this user

Example

{
  "data": {
    "topTracks": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "c881b6f5-d1c3-4a78-81f8-b8efec7fcf78.2"
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "B0785GTW4T",
            "title": "Beggin' [Explicit]",
            "url": "https://music.amazon.com/albums/B077XF8X4W/?trackAsin=B0785GTW4T"
          }
        },
        {
          "node": {
            "id": "B08ZCM5758",
            "title": "Heat Waves",
            "url": "https://music.amazon.com/albums/B08ZCTL3QB/?trackAsin=B08ZCM5758"
          }
        }
      ]
    }
  }
}

Get Top Playlists

GET

/browse/playlists/top

Authorization Scope: [music::catalog]

Get a list of Top Playlists featured on Amazon Music, based on analysis of the current user’s listening history. 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.

Example

curl --request GET '<base url>/v1/browse/playlists/top?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of top playlists for this user.

Name	Data Type	Required	Description
topPlaylists	Response Collection	No	Collection of top playlists for this user

Example

{
  "data": {
    "topPlaylists": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "ef4002a0-5752-4d3f-9ed9-41e8980397c2.2"
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "B00J9PVXBM",
            "duration": 4893,
            "images": [
              {
                "height": 1280,
                "width": 2560,
                "url": "https://m.media-amazon.com/images/I/71JmZ24jF4L.jpg"
              }
            ],
            "title": "Happy Modern Pop",
            "trackCount": 25,
            "url": "https://music.amazon.com/playlists/B00J9PVXBM"
          }
        },
        {
          "node": {
            "id": "B0B2239T2L",
            "duration": 22860,
            "images": [
              {
                "height": 500,
                "width": 500,
                "url": "https://m.media-amazon.com/images/I/51p-JxIHgtL.jpg"
              }
            ],
            "title": "Pride Hits",
            "trackCount": 115,
            "url": "https://music.amazon.com/playlists/B0B2239T2L"
          }
        }
      ]
    }
  }
}

Get New Podcast Episodes

GET

/browse/podcasts/episodes/new

Authorization Scope: [music::catalog]

Get a list of new podcast episodes based on analysis of the current user’s listening history and follows. Optional parameters can be used to limit the number of episodes returned.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	The maximum number of episodes to return (default: 100). Minimum of 1, maximum of 100.
cursor	string	No	The cursor/token for the page to continue pagination results from.

Example

curl --request GET '<base url>/v1/browse/podcasts/episodes/new?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of new podcast episodes for this user.

Name	Data Type	Required	Description
newPodcastEpisodes	Response Collection	No	Collection of new podcast epesodes for this user

Example

{
  "data": {
    "newPodcastEpisodes": {
      "pageInfo": {
        "hasNextPage": false
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "0c1dc966-2345-4530-b388-e33bc06f4401",
            "title": "MURDERED: Billy Stafford",
            "url": "https://music.amazon.com/podcasts/d6e/episodes/Crime-JunkieMURDERED: Billy Stafford"
          }
        },
        {
          "node": {
            "id": "17d202dc-7d25-4ebf-af62-850e79024486",
            "title": "Full Body Chills IS BACK!",
            "url": "https://music.amazon.com/podcasts/946e/episodes/Crime-JunkieFull Body Chills IS BACK!"
          }
        }
      ]
    }
  }
}

Get All Categories

GET

/browse/categories

Authorization Scope: [music::catalog]

Get a list of categories used to tag items in Amazon Music. Optional parameters can be used to limit the number of categories returned.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	The maximum number of categories to return (default: 100). Minimum of 1, maximum of 100.
cursor	string	No	The cursor/token for the page to continue pagination results from.

Example

curl --request GET '<base url>/v1/browse/browse/categories?limit=2' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of Amazon Music categories.

Name	Data Type	Required	Description
browseCategories	Response Collection	No	Collection of browse categories

Example

{
  "data": {
    "browseCategories": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "3:vx0YEGc1"
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "cpdRsfJP",
            "name": "Technoid"
          },
          "cursor": "2:cpdRsfJP"
        },
        {
          "node": {
            "id": "vx0YEGc1",
            "name": "Latin Urban"
          },
          "cursor": "3:vx0YEGc1"
        }
      ]
    }
  }
}

Get Category

GET

/browse/categories/{id}

Authorization Scope: [music::catalog]

Get a single category used to tag items in Amazon Music.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID for the category to retrieve.

Example

curl --request GET '<base url>/v1/browse/browse/categories/2iB4IU25' \
--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
category	Category	No	Data about the Amazon Music category

Example

"category": {
            "id": "2iB4IU25",
            "name": "Heavy Metal",
            "url": "https://music.amazon.com/genres/2iB4IU25",
            "categoryType": "GENRE"
        }

Get Albums By Category

GET

/browse/categories/{id}/albums

Authorization Scope: [music::catalog]

Get a list of Amazon Music albums tagged with a specified category. Optional parameters can be used to limit the number of albums returned.

Learn more about pagination.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID for the category to retrieve.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	The maximum number of albums to return (default: 100). Minimum of 1, maximum of 100.
cursor	string	No	The cursor/token for the page to continue pagination results from.

Example

curl --request GET '<base url>/v1/browse/browse/categories/2iB4IU25/albums' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of albums in the specified category.

Name	Data Type	Required	Description
albums	Response Collection	No	Collection of albums in the specified category

Example

(Some lines omitted for brevity)

{
  "data": {
    "category": {
      "id": "E9UEPoEH",
      "name": "Sacred Steel",
      "albums": {
        "pageInfo": {
          "hasNextPage": false
        },
        "edgeCount": 2,
        "edges": [
          {
            "node": {
              "id": "B003R490PW",
              "title": "We Walk This Road",
              "url": "https://music.amazon.com/albums/B003R490PW"
            }
          },
          {
            "node": {
              "id": "B00DRA5QC2",
              "title": "Lickety Split",
              "url": "https://music.amazon.com/albums/B00DRA5QC2"
            }
          },
		  ...
        ]
      }
    }
  }
}

Get Playlists By Category

GET

/browse/categories/{id}/playlists

Authorization Scope: [music::catalog]

Get a list of Amazon Music playlists tagged with a specified category. 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 Amazon Music catalog ID for the category to retrieve.

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.

Example

curl --request GET '<base url>/v1/browse/browse/categories/2iB4IU25/playlists' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of playlists in the specified category.

Name	Data Type	Required	Description
playlists	Response Collection	No	Collection of playlists in the specified category

Example

(Some lines omitted for brevity)

{
  "data": {
    "category": {
      "id": "hZiJ3FwS",
      "name": "Rock",
      "url": "https://music.amazon.com/genres/hZiJ3FwS",
      "playlists": {
        "pageInfo": {
          "hasNextPage": true
        },
        "edgeCount": 2,
        "edges": [
          {
            "node": {
              "id": "B00KO8YSNS",
              "duration": 12456,
              "images": [
                {
                  "height": 1280,
                  "width": 2560,
                  "url": "https://m.media-amazon.com/images/I/71VfjyvQ+pL.jpg"
                }
              ],
              "title": "50 Great '80s Songs",
              "trackCount": 50,
              "url": "https://music.amazon.com/playlists/B00KO8YSNS"
            }
          },
          {
            "node": {
              "id": "B00KNI5EVO",
              "duration": 24389,
              "images": [
                {
                  "height": 500,
                  "width": 500,
                  "url": "https://m.media-amazon.com/images/I/51+VJ8i9qML.jpg"
                }
              ],
              "title": "REDISCOVER THE '90s: Alternative",
              "trackCount": 100,
              "url": "https://music.amazon.com/playlists/B00KNI5EVO"
            }
          },
		  ...
        ]
      }
    }
  }
}

Get Tracks By Category

GET

/browse/categories/{id}/tracks

Authorization Scope: [music::catalog]

Get a list of Amazon Music tracks tagged with a specified category. Optional parameters can be used to limit the number of tracks returned.

Learn more about pagination.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID for the category to retrieve.

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.

Example

curl --request GET '<base url>/v1/browse/browse/categories/2iB4IU25/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Responses

Amazon Music response object containing a response collection of tracks in the specified category.

Name	Data Type	Required	Description
playlists	Response Collection	No	Collection of tracks in the specified category

Example

(Some lines omitted for brevity)

{
  "data": {
    "category": {
      "id": "E9UEPoEH",
      "name": "Sacred Steel",
      "tracks": {
        "pageInfo": {
          "hasNextPage": true,
          "token": "tztok-v2_iosmAqq9RWIFJZXCZvgM5OnQj0NR8UsA2BMCfq-3hR4VYAfZb16fzIeuiCNaZzZp"
        },
        "edgeCount": 50,
        "edges": [
          {
            "node": {
              "id": "B07PPVYNQZ",
              "title": "Baptise Me",
              "url": "https://music.amazon.com/albums/B07PMV5LV8/?trackAsin=B07PPVYNQZ"
            }
          },
          {
            "node": {
              "id": "B00DRA5QX6",
              "title": "Amped Up",
              "url": "https://music.amazon.com/albums/B00DRA5QC2/?trackAsin=B00DRA5QX6"
            }
          },
          ...
        ]
      }
    }
  }
}