Amazon Music Web API

Web API Podcast 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.

Podcast

Get and manage podcast related meta-data.

Get Podcast Show
Get Multiple Podcast Shows
Get Podcast Episode
Get Multiple Podcast Episodes
Add Podcast Episode to Current User's Library
Delete Podcast Episode From Current User's Library
Add Followed Podcast Show For Current User
Remove Followed Podcast Show From Current User

Get Podcast Show

GET

/podcasts/shows/{id}

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for one podcast show by ID. This includes a list of podcast episodes, as well as the title of the podcast, the author, and more. Optional parameters can be used to limit the number of podcast episodes returned.

Learn more about pagination.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The ID of the podcast show to be retrieved.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	The maximum number of podcast 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/podcasts/shows/B077DT8KHW?limit=2'
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing a podcast show and a collection or episodes:

Name	Data Type	Required	Description
podcastShow	podcastShow	No	Data about the Amazon Music podcast show

Example

(Some lines omitted for brevity)

{
  "data": {
    "podcastShow": {
      "id": "63825c25-4a0b-4389-a1cc-c72e5dc8bb7b",
      "title": "The Line",
      "description": "<p>In 2018, a group of Navy SEALs broke ranks ...</p>",
      "episodes": {
        "pageInfo": {
          "hasNextPage": true,
          "token": "7:7a0dc6a4-0ab8-46d5-9395-872a22110268"
        },
        "edgeCount": 2,
        "edges": [
          {
            "cursor": "0:4c580caf-3b61-4311-a9c5-2c006651aa23",
            "node": {
              "id": "4c580caf-3b61-4311-a9c5-2c006651aa23",
              "title": "Introducing \"The Line\"",
              "url": "https://music.amazon.com/podcasts/63825c25-4a0b-4389-a1cc-c72e5dc8bb7b/episodes/4c580caf-3b61-4311-a9c5-2c006651aa23/The-LineIntroducing \"The Line\""
            }
          },
          {
            "cursor": "1:9386b374-cbd3-484f-b4ca-9fefaecf9849",
            "node": {
              "id": "9386b374-cbd3-484f-b4ca-9fefaecf9849",
              "title": "We Have a Problem",
              "url": "https://music.amazon.com/podcasts/63825c25/episodes/9386b374-cbd3-/The-LineWe Have a Problem"
            }
          }
        ]
      },
      "author": "Apple TV+ / Jigsaw Productions",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/S/834609238.jpeg"
        }
      ],
      "url": "https://music.amazon.com/podcasts/63825c25-4a0b/The-Line"
    }
  }
}

Get Multiple Podcast Shows

GET

/podcasts/shows

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for multiple podcast shows identified by comma-separated catalog IDs. This includes the individual podcast episodes, as well as the title of the podcast, the author, and more. Optional parameters can be used to limit the number of podcast episodes returned.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
ids	string	Yes	A comma-separated list of the IDs of the podcast shows to be retrieved. There is a maximum limit of 100 IDs.
limit	number	No	The maximum number of podcast 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/podcasts/shows?ids=e8a3c6e3-3d78-4c83-a61d-a95e70acacb0,6d261659-cc8d-478c-b052-19dfeb25dcf5'
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing an array of podcast shows:

Name	Data Type	Required	Description
podcastShows	PodcastShow[]	No	An array of podcast shows

Example

(Some lines omitted for brevity)

{
    "data": {
        "podcastShows": [
            {
                "id": "e8a3c6e3-3d78-4c83-a61d-a95e70acacb0",
                "title": "Suspect",
                "description": "\<p>Suspect is an investigative series... </p>\n    ",
                "episodes": {
                    "pageInfo": {
                        "hasNextPage": true,
                        "token": "1:28032844-b4af-406f-9528-9622dc186591"
                    },
                    "edgeCount": 2,
                    "edges": [
                        {
                            "cursor": "0:883a091d-865f-428d-a23a-6a4251f0fa45",
                            "node": {
                                "id": "883a091d-865f-428d-a23a-6a4251f0fa45",
                                "title": "Introducing: Suspect",
                                "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/episodes/883a091d-865f-428d-a23a-6a4251f0fa45/SuspectIntroducing:-Suspect"
                            }
                        },
                        {
                            "cursor": "1:28032844-b4af-406f-9528-9622dc186591",
                            "node": {
                                "id": "28032844-b4af-406f-9528-9622dc186591",
                                "title": "The Halloween Party | 1",
                                "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/episodes/28032844-b4af-406f-9528-9622dc186591/SuspectThe-Halloween Party | 1"
                            }
                        }
                    ]
                },
                "author": "Wondery | Campside",
                "images": [
                    {
                        "height": null,
                        "width": null,
                        "url": "https://m.media-amazon.com/images/S/486163326.jpeg",
                        "imageType": "PRIMARY"
                    }
                ],
                "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/Suspect"
            },
            {
                "id": "6d261659-cc8d-478c-b052-19dfeb25dcf5",
                "title": "MrBallen Podcast: Strange, Dark & Mysterious Stories",
                "description": "\n      <p>The Strange, Dark and Mysterious delivered in podcast format. </p>\n    ",
                "episodes": {
                    "pageInfo": {
                        "hasNextPage": true,
                        "token": "77:d87ec063-028f-40a7-a052-f14ffa144325"
                    },
                    "edgeCount": 2,
                    "edges": [
                        {
                            "cursor": "78:04cbe42e-ac3c-4cfc-a915-743579f3b0b9",
                            "node": {
                                "id": "04cbe42e-ac3c-4cfc-a915-743579f3b0b9",
                                "title": "Episode 78 -- \"Dungeons & Dragons\" (PODCAST EXCLUSIVE EPISODE)",
                                "url": "https://music.amazon.com/podcasts/6d261659-cc8d-478c-b052-19dfeb25dcf5/episodes/04cbe42e-ac3c-4cfc-a915-743579f3b0b9/MrBallen-Podcast: Strange, Dark & Mysterious StoriesEpisode 78 -- \"Dungeons & Dragons\" (PODCAST EXCLUSIVE EPISODE)"
                            }
                        },
                        {
                            "cursor": "77:d87ec063-028f-40a7-a052-f14ffa144325",
                            "node": {
                                "id": "d87ec063-028f-40a7-a052-f14ffa144325",
                                "title": "Episode 77 -- \"Caught in 4K\"",
                                "url": "https://music.amazon.com/podcasts/6d261659-cc8d-478c-b052-19dfeb25dcf5/episodes/d87ec063-028f-40a7-a052-f14ffa144325/MrBallen-Podcast: Strange, Dark & Mysterious StoriesEpisode 77 -- \"Caught in 4K\""
                            }
                        }
                    ]
                },
                "author": "MrBallen",
                "images": [
                    {
                        "height": null,
                        "width": null,
                        "url": "https://m.media-amazon.com/images/S/985721874.jpeg",
                        "imageType": "PRIMARY"
                    }
                ],
                "url": "https://music.amazon.com/podcasts/6d261659-cc8d-478c-b052-19dfeb25dcf5/MrBallen-Podcast: Strange, Dark & Mysterious Stories"
            }
        ]
    },
    "extensions": {}
}

Get Podcast Episode

GET

/podcasts/episodes/{id}

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for an individual episode of a podcast by ID. This includes the title of the episode, the podcast, the episode number, and more.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The ID of the episode to be retrieved.

Example

curl --request GET '<base url>/v1/podcasts/episodes/15bfa46b-7af1-49b3-9375-8977627c43ab'
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing the podcast episode:

Name	Data Type	Required	Description
podcastEpisode	PodcastEpisode	No	Data about the Amazon Music podcast episode

Example

{
  "data": {
    "podcastEpisode": {
      "id": "15bfa46b-7af1-49b3-9375-8977627c43ab",
      "title": "A Righteous Thing",
      "type": "FULL",
      "description": "\n        <p>What makes a SEAL? ....</p>\n      ",
      "podcast": {
        "id": "63825c25-4a0b-4389-a1cc-c72e5dc8bb7b",
        "title": "The Line",
        "url": "https://music.amazon.com/podcasts/63825c25-4a0b-4389-a1cc-c72e5dc8bb7b/The-Line"
      },
      "episodeNumber": 2,
      "images": [
        {
          "url": "https://m.media-amazon.com/images/834609238.jpeg"
        }
      ],
      "duration": 2309,
      "releaseDate": "2021-04-06T22:00:00Z",
      "url": "https://music.amazon.com/podcasts/63825c25-4a0b-4389-a1cc-c72e5dc8bb7b/episodes/15bfa46b-7af1-49b3-9375-8977627c43ab/The-LineA Righteous Thing"
    }
  }
}

Get Multiple Podcast Episodes

GET

/podcasts/episodes

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for multiple episodes of a podcast identified by comma-separated catalog IDs. This includes the title of the episode, the podcast, the episode number, and more.

Learn more about pagination.

Query Parameters

Name	Data Type	Required	Description
ids	string	Yes	A comma-separated list of the IDs of the episodes to be retrieved. There is a maximum limit of 50 IDs.

Example

curl --request GET '<base url>/v1/podcasts/episodes?ids=883a091d-865f-428d-a23a-6a4251f0fa45,28032844-b4af-406f-9528-9622dc186591'
--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
podcastEpisodes	PodcastEpisode[]	No	Data about the Amazon Music podcast episodes

Example

{
    "data": {
        "podcastEpisodes": [
            {
                "id": "883a091d-865f-428d-a23a-6a4251f0fa45",
                "title": "Introducing: Suspect",
                "type": "BONUS",
                "description": "\n  <p>An apartment complex hosts ...</p>\n",
                "podcast": {
                    "id": "e8a3c6e3-3d78-4c83-a61d-a95e70acacb0",
                    "title": "Suspect",
                    "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/Suspect"
                },
                "author": null,
                "seasonNumber": 1,
                "episodeNumber": null,
                "images": [
                    {
                        "height": null,
                        "width": null,
                        "url": "https://m.media-amazon.com/images/486163326.jpeg",
                        "imageType": "PRIMARY"
                    }
                ],
                "duration": 161,
                "releaseDate": "2021-08-17T13:15:00Z",
                "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/episodes/883a091d-865f-428d-a23a-6a4251f0fa45/SuspectIntroducing:-Suspect"
            },
            {
                "id": "28032844-b4af-406f-9528-9622dc186591",
                "title": "The Halloween Party | 1",
                "type": "FULL",
                "description": "\n<p>The residents of the Valley View apartments ...</p>\n",
                "podcast": {
                    "id": "e8a3c6e3-3d78-4c83-a61d-a95e70acacb0",
                    "title": "Suspect",
                    "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/Suspect"
                },
                "author": null,
                "seasonNumber": 1,
                "episodeNumber": 1,
                "images": [
                    {
                        "height": null,
                        "width": null,
                        "url": "https://m.media-amazon.com/images/486163326.jpeg",
                        "imageType": "PRIMARY"
                    }
                ],
                "duration": 2061,
                "releaseDate": "2021-08-31T07:05:00Z",
                "url": "https://music.amazon.com/podcasts/e8a3c6e3-3d78-4c83-a61d-a95e70acacb0/episodes/28032844-b4af-406f-9528-9622dc186591/SuspectThe-Halloween Party | 1"
            }
        ]
    },
    "extensions": {}
}

Add Podcast Episode to Current User's Library

PUT

/me/podcasts/episodes/{id}

Authorization Scope: [music::library]

Save a podcast episode to the current Amazon Music user’s library.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music ID of the podcast episode.

Example

curl --request PUT '<base url>/v1//me/podcasts/episodes/53f57edd-ce46-47e5-bda5-b61b772d83b3'
--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
savePodcastEpisode	Response	No	Data about the saved podcast episode and an indicator of its save state

Example

{
  "data": {
    "savePodcastEpisode": {
      "podcastEpisode": {
        "id": "53f57edd-ce46-47e5-bda5-b61b772d83b3",
        "title": "Disgraceland Presents River Phoenix (Hollywoodland Episode): Religious Cults, Street Kids, Speedballs and Viper Rooms",
        "url": "https://music.amazon.com/podcasts/8bfa8155-888b-4553-acd3-8f22d43b4c9e/episodes/53f57edd-ce46-47e5-bda5-b61b772d83b3/DISGRACELANDDisgraceland-Presents River Phoenix (Hollywoodland Episode): Religious Cults, Street Kids, Speedballs and Viper Rooms"
      },
      "saveState": "SAVED"
    }
  }
}

Delete Podcast Episode From Current User's Library

DELETE

/me/podcasts/episodes/{id}

Authorization Scope: [music::library]

Remove a saved podcast episode from the current Amazon Music user’s library.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID of the podcast episode to remove.

Example

curl --request DELETE '<base url>/v1//me/podcasts/episodes/53f57edd-ce46-47e5-bda5-b61b772d83b3'
--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
removePodcastEpisode	Response	No	Data about the removed podcast episode

Example

{
  "data": {
    "removePodcastEpisode": {
      "podcastEpisode": {
        "id": "53f57edd-ce46-47e5-bda5-b61b772d83b3",
        "title": "Disgraceland Presents River Phoenix (Hollywoodland Episode): Religious Cults, Street Kids, Speedballs and Viper Rooms",
        "url": "https://music.amazon.com/podcasts/8bfa8155-888b-4553-acd3-8f22d43b4c9e/episodes/53f57edd-ce46-47e5-bda5-b61b772d83b3/DISGRACELANDDisgraceland-Presents River Phoenix (Hollywoodland Episode): Religious Cults, Street Kids, Speedballs and Viper Rooms"
      },
      "saveState": "REMOVED"
    }
  }
}

Add Followed Podcast Show For Current User

PUT

/me/followed/podcasts/shows/{id}

Authorization Scope: [music::favorites]

Add a specified podcast show to the current user's list of followed shows.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The ID of the podcast to follow.

Example

curl --request PUT <base url>/v1/me/followed/podcasts/shows/8bfa8155-888b-4553-acd3-8f22d43b4c9e
--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
followPodcastShow	Response	No	Data about the followed podcast show

Example

{
  "data": {
    "followPodcastShow": {
      "podcastShow": {
        "id": "8bfa8155-888b-4553-acd3-8f22d43b4c9e",
        "title": "DISGRACELAND",
        "url": "https://music.amazon.com/podcasts/8bfa8155-888b-4553-acd3-8f22d43b4c9e/DISGRACELAND"
      },
      "followState": "FOLLOW"
    }
  }
}

Remove Followed Podcast Show From Current User

DELETE

/me/followed/podcasts/shows/{id}

Authorization Scope: [music::favorites]

Remove the current user as a follower of a specified podcast.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The ID of the podcast to un-follow.

Example

curl --request DELETE <base url>/v1/me/followed/podcasts/shows/8bfa8155-888b-4553-acd3-8f22d43b4c9e
--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
unfollowPodcastShow	Response	No	Data about the unfollowed podcast show

Example

{
  "data": {
    "unfollowPodcastShow": {
      "podcastShow": {
        "id": "8bfa8155-888b-4553-acd3-8f22d43b4c9e",
        "title": "DISGRACELAND",
        "url": "https://music.amazon.com/podcasts/8bfa8155-888b-4553-acd3-8f22d43b4c9e/DISGRACELAND"
      },
      "followState": "UNFOLLOW"
    }
  }
}