Amazon Music Web API
Web API Views Overview V2.0
Web API V2 Using the Views APIs
The Views APIs return ready-to-render, composed pages of Amazon Music content — a home page, recently played, podcast home, a user's library, and views scoped to a specific album, artist, playlist, or podcast show. Rather than assembling a screen from many resource calls, you fetch a View and render the groups it returns.
Structure of a view
A View has:
id— a stable identifier for the view.entity— an optional seed entity (present only on seeded views; see below).content.entityGroups[]— the ordered list of groups that compose the view.
An EntityGroup has:
id— a stable identifier for the group. Use it as thegroupIdon a See-All request to page deeper into this group.title— a human-readable label (for example, "Playlists for You").viewType— a layout hint. Confirmed values areGRID,LIST, andSTACK.content.entities[]— a page of polymorphic entities in the group.content.nextPageToken— the cursor for paging this group's entities.
{
"id": "B0EXAMP700",
"content": {
"entityGroups": [
{
"id": "B0EXAMP710",
"title": "Playlists for You",
"viewType": "GRID",
"content": {
"entities": [
{ "_type": "Playlist", "id": "B0EXAMP100", "title": "Indie Rock Essentials" }
],
"nextPageToken": "B0EXAMP720"
}
}
],
"nextPageToken": "B0EXAMP730"
}
}
Switch on _type — the forward-compatibility contract
Every entity inside a group carries a _type discriminator naming its concrete type. Confirmed values are Track, Album, Artist, Playlist, PodcastShow, and PodcastEpisode.
The reference states the contract plainly: switch on _type to interpret the rest of the entity payload, and treat unknown _type values as opaque and skip that entity. Following this rule is what keeps your integration working when Amazon Music introduces new entity types in the future — a _type you do not recognize must be ignored, not treated as an error.
Seeded and unseeded views
Views come in two shapes:
- Unseeded (editorial) views compose recommendations or library content with no seed entity. These are the Home view (
/v2/views/home), Recently Played (/v2/views/recent), Podcast home (/v2/views/podcasts), the Library view (/v2/views/library), and its sub-views (/v2/views/library/albums,/artists,/playlists,/podcasts,/songs). - Seeded views are scoped to a specific entity, which is returned under the top-level
entityfield alongside the related groups. These are the album-scoped (/v2/views/albums/{id}), artist-scoped (/v2/views/artists/{id}), playlist-scoped (/v2/views/playlists/{id}), and podcast-show-scoped (/v2/views/podcasts/shows/{id}) views.
{
"id": "B0EXAMP740",
"entity": {
"_type": "Album",
"id": "B073J5NW51",
"title": "Sound Awake"
},
"content": { "entityGroups": [ /* related groups */ ] }
}
See-All: paging within a group
The top-level first/after parameters page across the entityGroups array. To page deeper into a single group — a "See All" — call that view's group endpoint with the group's groupId, which is an opaque token taken from a prior view response. For example, GET /v2/views/home/{groupId} returns one EntityGroup whose entities array you page independently with first/after. See Pagination for cursor mechanics.
Scopes
Views require different OAuth scopes depending on the content:
music::catalog— editorial and catalog-seeded views (home, podcast home, and the album-, artist-, playlist-, and podcast-show-scoped views).music::history— the Recently Played view.music::library:read— the Library view and all of its sub-views.
Request the scope appropriate to the views you call. The Views reference documents 17 view endpoints, each declaring the scope it requires.
