Amazon Music Web API
Web API Podcast 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.
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.
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.
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.
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"
}
}
}