Console développeur
Merci de votre visite. Cette page est disponible en anglais uniquement.

Amazon Music Web API

Web API Podcast V1.0

Podcast

Get and manage podcast related meta-data.

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