Amazon Music Web API

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

Web API Object Schema

This is the object schema for the Amazon Music Web API.

Primary Entity Types
General Base Types
- Connection
- Edges
- Node
- Entity
- PageInfo
- Response
- Response Collection
Primitives
Enumerations

Primary Entity Types

Action

Name	Data Type	Required	Description
isAllowed	bool	Yes	Specifies whether a playback action is allowed (true or false).
disableType	string	No	Optional string describing the reason for why an action is not allowed: 'NO_MORE_SKIPS' \| 'NEED_AMAZON_MUSIC_SUBSCRIPTION_FOR_AD_FREE_PLAYBACK' \| 'NEED_AMAZON_MUSIC_UNLIMITED_CATALOG_ACCESS' \| 'NEED_AMAZON_MUSIC_SUBSCRIPTION_TO_SHUFFLE_NON_STATION' \| 'FEATURE_NOT_AVAILABLE'
remainingSkips	number	No	Remaining number of skip actions (usually reset to the default of 6 for Prime customers after 60 minutes).

Actions

Name	Data Type	Required	Description
next	Action	No	Specifies if the customer may skip to the next track in the playback queue.
previous	Action	No	Specifies if the customer may skip to the previous track in the queue.
scrubForward	Action	No	Specifies if the customer may scrub forward within the current track.
scrubBackward	Action	No	Specifies if the customer may scrub forward within the current track.
loopAll	Action	No	Specifies if the customer may switch to 'LOOP_ALL' loop mode.
loopOne	Action	No	Specifies if the customer may switch to 'LOOP_ONE' loop mode.
shuffle	Action	No	Specifies if the customer may switch to 'SHUFFLE_ON' shuffle mode.
rate	Action	No	Specifies if the customer may select a playback speed factor different from 1.0.
queueMutations	Action	No	Specifies if the customer may add or remove tracks from their current playback queue.
queueView	Action	No	Specifies if the customer may see upcoming tracks in the queue.

Album

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this album.
url	string	No	The Amazon Music url for this album.
globalAsin	string	No	Globally unique identifier for this album.
localAsin	string	No	musicTerritory localized identifier for this album.
title	string	No	The title of this album.
shortTitle	string	No	The shortened title for this album
duration	double	No	The duration of this album in seconds.
release	Release	No	Release date information for this album.
releaseDate	string	No	The date the album was first released.
musicTerritory	musicTerritory	No	Localized territory identifier for this album.
market	Market	No	Market this album is referenced from
availableMarkets	market[]	No	An array of markets this album is available in.
artists	artist[]	No	Array of Artists associated with this album
eligibility	Eligibility	No	The eligibility associated with this album.
parentalSettings	ParentalSettings	No	Parental settings associated with this album
tracks	track[]	No	The tracks associated with this album.
trackCount	double	No	The number of tracks within this album.
images	Image[]	No	Array of Images associated with this album.
label	string	No	Label associated with this Album

Artist

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this artist.
url	string	No	The Amazon Music url for this artist.
globalAsin	string	No	Globally unique identifier for this artist.
localAsin	string	No	musicTerritory localized identifier for this artist.
followerCount	double	No	The count of followers for this artist.
related	Artist connection	No	A list of related artists
images	Image[]	No	Images associated with this artist.
musicTerritory	musicTerritory	No	musicTerritory localized identifier for this artist.
market	Market	No	Market this Asset is referenced from
name	string	No	The name of this Artist.
albums	albums connection	No	A connection list of albums for this artist
tracks	tracks connection	No	A connection list of tracks for this artist

InitialPlaybackSessionResponse

Name	Data Type	Required	Description
pageInfo	PageInfo	No	Object used for pagination. Inspect the 'hasNextPage' property to check if the playback queue has additional tracks.
entities	PlaybackData[]	No	Data associated with this playback object.
metadata	PlaybackMetadata[]	No	Metadata associated with this playback object.

PlaybackData

Name	Data Type	Required	Description
sessionId	string	Yes	Identifier associated with this playback session.
entityReferenceId	string	No	Identifier associated with this particular playback entity within the playqueue.
metricId	string	No	Identifier required for event reporting.
actions	Actions	No	A collection of Action objects specifying which are currently allowed and which are not.
track	Track	No	An object describing the current playqueue track.

PlaybackDataResponse

Name	Data Type	Required	Description
pageInfo	PageInfo	No	Object used for pagination. Inspect the 'hasNextPage' property to check if the playback queue has additional tracks.
entities	PlaybackData[]	Yes	Data associated with this playback object.

PlaybackMetadata

Name	Data Type	Required	Description
loopMode	string	Yes	Describing the playback queue loop mode: 'LOOP_ALL' \| 'LOOP_ONE' \| 'LOOP_OFF'
shuffleMode	string	Yes	Describing the playback queue shuffle mode: 'SHUFFLE_ON' \| 'SHUFFLE_OFF'
playbackState	string	Yes	The current playback state: 'PLAYING' \| 'STOPPED'

PlaybackSession

Name	Data Type	Required	Description
sessionId	string	Yes	Identifier associated with this playback session.
entityReferenceId	string	No	Identifier associated with the current playback entity within the playqueue.
track	Track	No	An object describing the current playqueue track.
metadata	PlaybackMetadata	No	Metadata associated with the current playback object.

PlaybackSessionResponse

Name	Data Type	Required	Description
sessions	PlaybackSession[]	Yes	List of active playback session for the current user.

Playlist

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this playlist.
url	string	No	The Amazon Music URL for this playlist.
title	string	No	The title of this playlist.
description	string	No	The description of this playlist.
duration	double	No	The duration of this playlist in seconds.
eligibility	Eligibility	No	The eligibility associated with this playlist.
tracks	Track Connection	No	The tracks associated with this playlist.
trackCount	double	No	The number of tracks within this playlist.
visibility	VisibilityType	No	The visible state of this playlist to the public.
curator	User	No	The owner and creator of this playlist.
images	Image[]	No	Array of images associated with this playlist.

PlayParams

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this playable.
containerId	string	No	Identifier associated with this playable's container.
selections	Selections[]	No	Array of allowed selections.

PlaybackEventStart

Name	Data Type	Required	Description
type	string	Yes	The type of playback event: 'start'.
clientTimestampInMilliseconds	integer	Yes	The client's current time in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)
initialPlaybackDelayMilliseconds	integer	Yes	Time between when a customer expects to hear music (or stop hearing music) and when playback actually starts (or stops).
deviceTimezone	string	Yes	The device timezone, measured in UTC offset hours. For example, `-08:00` is the timezone of California.
playbackCurrentSpeed	double	Yes	Current playback speed factor. For example, `1.0` describes regular playback, and `1.25` is 25% faster.
playbackStartAbsoluteOffsetMilliseconds	integer	Yes	Absolute offset in milliseconds from where the playback starts within a track. The value can range from `0` to the total duration of a track.

PlaybackEventStop

Name	Data Type	Required	Description
type	string	Yes	The type of playback event: 'stop'.
clientTimestampInMilliseconds	integer	Yes	The client's current time in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)
initialPlaybackDelayMilliseconds	integer	Yes	Time between when a customer expects to hear music (or stop hearing music) and when playback actually starts (or stops).
deviceTimezone	string	Yes	The device timezone, measured in UTC offset hours. For example, `-08:00` is the timezone of California.
playbackCurrentSpeed	double	Yes	Current playback speed factor. For example, `1.0` describes regular playback, and `1.25` is 25% faster.
durationSeconds	integer	Yes	Playback duration in seconds since the start of the track or since the last interruption.
entityProgressSeconds	integer	Yes	The current absolute playback position within this track. If the track does not complete, report the farthest point in the progress bar.
rebufferCount	integer	Yes	Number of times, playback was interrupted since the last start event due to rebuffering.
terminationReason	string	Yes	Reason for why playback was terminated. Valid values are: `userStop`, `userNext`, `userPrev`, `trackFinished`, `trackScrub`, `systemStop`

PodcastShow

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this podcast.
url	string	No	The Amazon Music URL for this podcast.
title	string	No	The title of this podcast.
type	string	No	The type of podcast.
description	string	No	The description of this podcast.
episodes	Podcast Episode Connection	No	Episodes related to this podcast.
author	string	No	The author of this podcast.
images	Image[]	No	Array of images associated with this podcast.

PodcastEpisode

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this podcast episode.
url	string	No	The Amazon Music URL for this podcast episode.
title	string	No	The title of this podcast episode.
type	string	No	The type of podcast episode.
description	string	No	The description of this podcast episode.
podcast	PodcastShow	No	The podcast episode this is associated with.
author	string	No	The author of this podcast episode.
seasonNumber	double	No	The season for this podcast episode.
episodeNumber	double	No	The number of this podcast episode.
images	Image[]	No	Array of images associated with this podcast episode.
duration	double	No	The duration of this podcast episode in seconds.
releaseDate	string	No	The date this podcast episode was made available on Amazon Music.

Station

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this station.
url	string	No	The Amazon Music url for this station.
name	string	No	The name of this station.
parentalSettings	ParentalSettings	No	Parental settings associated with this station.
images	Image[]	No	Array of images associated with this station.

Track

Name	Data Type	Required	Description
id	string	No	Identifier associated with this track.
url	string	No	The Amazon Music URL for this track.
mediaType	mediaType	No	MediaType affiliated with this track.
globalAsin	string	No	Globally unique identifier for this track.
localAsin	string	No	musicTerritory localized identifier for this track.
title	double	No	The title of this track.
shortTitle	string	No	The shortened title of this track
duration	double	No	The duration of this track in seconds.
release	Release	No	Release date information relative to this track.
isrc	string	No	The ISRC code associated with this track.
artists	Artist[]	No	An array of artists associated with this track
album	Album	No	The album associated with this track
musicTerritory	musicTerritory	No	musicTerritory localized identifier for this track.
market	Market	No	Market this track is referenced from.
availableMarkets	Market[]	No	The list of markets this track is available in.
eligibility	Eligibility[]	No	The eligibility associated with this track.
parentalSettings	ParentalSettings	No	Parental settings associated with this track.
previewUrl	string	No	Sample playback URL for this track if supported.
images	Image[]	No	An array of images associated with this track.
label	string	No	Label associated with this track.
dmid	string	No	Unique internal identifier of this track.
audioVideoTimestamps	AudioVideoTimestamps	No	Timestamp mapping for each second between audio and video with confidence score

User

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this user.
url	string	No	The Amazon Music URL for this user.
name	string	No	The name of this user.
images	Image[]	No	Array of images associated with this user.
tier	UserTier	No	The subscription tier of this user
visibility	VisibilityType	No	The visibility of this user
playbackVisibility	VisibilityType	No	The playback visibility of this user
playlists	Playlist Connection	No	The playlists accociated with this user
tracks	Track Connection	No	The tracks accociated with this user
podcastEpisodes	Podcast Episode Connection	No	The podcast episodes accociated with this user
followers	User Connection	No	The followers accociated with this user
followedUsers	User Connection	No	The other users this user is following
followedPlaylists	Playlist Connection	No	The playlists this user is following
recentTrackPlayback	Track Connection	No	The recent tracks this user has played
followedPodcastShows	Podcast Connection	No	Podcast shows this user is following
recentEntitiesPlayback	Entities Connection	No	List of entities recently played by this user

ViewView

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this view.
title	string	No	The name of this view.
entity	Entity	No	The entity-type of this view (e.g. Artist).
images	Image[]	No	A background image.
content	ViewContent	No	List of entity groups with pagination tokens

ViewContent

Name	Data Type	Required	Description
entityGroups	EntityGroup[]	Yes	Array of EntityGroup objects
nextPageToken	string	No	A token to be used for pagination.

EntityGroup

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this container
title	string	No	Title of container
viewType	ViewType	Yes	A rendering type which determines the recommended layout of the container
content	EntityGroupContent	Yes	The list of entity groups with pagination tokens

EntityGroupContent

Name	Data Type	Required	Description
entities	EntityGroup[]	Yes	Array of EntityGroup objects
nextPageToken	string	No	A token to be used for pagination.

ViewView

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this view.
title	string	No	The name of this view.
entity	Entity	No	The entity-type of this view (e.g. Artist).
images	Image[]	No	A background image.
content	ViewContent	No	List of entity groups with pagination tokens

ViewContent

Name	Data Type	Required	Description
entityGroups	EntityGroup[]	Yes	Array of EntityGroup objects
nextPageToken	string	No	A token to be used for pagination.

EntityGroup

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this container
title	string	No	Title of container
viewType	ViewType	Yes	A rendering type which determines the recommended layout of the container
content	EntityGroupContent	Yes	The list of entity groups with pagination tokens

EntityGroupContent

Name	Data Type	Required	Description
entities	EntityGroup[]	Yes	Array of EntityGroup objects
nextPageToken	string	No	A token to be used for pagination.

General Base Types

Connection

The Connection base type is a generalized form of a collection container for pageable lists of entities. These will be found as return values for functions returning lists such as Get Current User's Albums. Connections contain an array of the specialized type along with a count of the items and a PageInfo object used for pagination.

Name	Data Type	Required	Description
edges	Edge[]	Yes	Array of Edges for the specialized object type
edgeCount	double	No	The count of items in the edge Array
pageInfo	pageinfo	No	Information used for Pagination

Edges

An Array of Nodes. Nodes are a generalized base object of the entity returned in a Connection.

Name	Data Type	Required	Description
node	node	Yes	Generalized base object of the entity returned in a Connection

Node

A Node (also known as an Edge) is a generalized type for entity objects returned in pageable Connection lists. They typically contain a limited subset of data representing the type. It may be necessary to use GET on the resource in question to get full details of the object.

Name	Data Type	Required	Description
id	string	Yes	Key identifier for the specialised object
cursor	string	No	Used for pagination. Identifies the current position within a list

Entity

Generalized type to describe entities. May have other properties depending on the specialized object.

Name	Data Type	Required	Description
id	string	No	Identifier associated with this type.
url	string	No	The Amazon Music url for this entity.

PageInfo

Information used for pagination.

Name	Data Type	Required	Description
hasNextPage	Boolean	Yes	Flag indicating if the paginated result has a next page.
token	string	No	Token pointing to the next page.

Response

The generic response type for all rerturned data within the API.

Name	Data Type	Required	Description
data	object	No	The data returned from the query. Typically an array of entities or a response collection
errors	map	No	A collection of key-value pairs describing the error

Response Collection

A generalized object for a returned collection. It is used in responses that return pageable lists. Trypically contains header information including the ID and name of the parent of the collection, along with Connections containing the lists of specialized returned objects.

Name	Data Type	Required	Description
[header type]	base object	No	This header will be named after the reference or perent for this query, For example, it may be titled 'artist' for a list of albums related to that artist
id	string	No	The Amazon ID for this entity
name	string	No	The name of this entity
[connection type]	connection	No	The name of this connection object is based on the collection type returned. For example, it would be 'albums' if a list of albums is being returned

Primitives

AudioVideoTimestamps

Name	Data Type	Required	Description
audioTimestamps	double[]	Yes	An array of audio timestamps in seconds
audioToVideoConfidence	double[]	Yes	An array of confidence scores of the mapping between audio and video seconds
videoTimestamps	double[]	Yes	An array of video timestamps in seconds
videoToAudioConfidence	double[]	Yes	Confidence scores of the mapping between video and audio seconds

Name	Data Type	Required	Description
id	string	Yes	Identifier associated with this category.
url	string	No	The Amazon Music url for this category.
name	string	No	The name of this category.
images	Image[]	No	Array of images associated with this category.
albums	SearchAlbumResults	No	A search result list of albums in this category.
tracks	SearchTrackResults	No	A search result list of tracks in this category.
playlists	SearchPlaylistResults	No	A search result list of playlists in this category.
subcategories	Category[]	No	An array of sub categories in this category.
categoryType	CategoryType	No	The category type of this category.

Eligibility

Name	Data Type	Required	Description
isDownloadable	boolean	No	Flag indicating if this asset is available for download.
isPurchaseable	string	No	Flag indicating if this asset is available for purchase.
isPreviewable	boolean	No	Flag indicating if this asset is previewable.
isPrimeEligible	boolean	No	Flag indicating if this asset is Prime eligible on retail website.

Image

Name	Data Type	Required	Description
width	double	No	Width of the image in pixels.
height	double	No	Height of the image in pixels.
aspectRatio	double	No	Aspect ratio of the image.
url	string	Yes	URL of the image.
imageType	ImageType	Yes	The type of image. Describes its intended use.
description	string	No	Description of the image.

Market

Name	Data Type	Required	Description
id	string	Yes	Two digit ISO 3166-1 country code.
name	string	Yes	Name of the country.

musicTerritory

Name	Data Type	Required	Description
code	string	Yes	Two digit ISO 3166-1 country code.
territoryName	string	No	Name of the country.

ParentalSettings

Name	Data Type	Required	Description
isKidFriendly	Boolean	Yes	Flag indicating if the content is kid friendly.
hasExplicitLanguage	Boolean	Yes	Flag indicating explicit content.

Release

Name	Data Type	Required	Description
streetDate	string	No	The date this asset became available.
localOriginalReleaseDate	string	No	The date this asset became available relative to its musicTerritory

SaveTrackResponse

Name	Data Type	Required	Description
track	track	No	Basic information about the track whose save state was changed
saveState	string	No	The save state of the track can be SAVED or REMOVED

Enumerations

AlbumFieldType

Types used for searching albums

asin

artistId

artistName

categoryId

name

ArtistFieldType

Types used for searching artists

asin

name

CategoryType

Enum

GENRE

EntityType

Album

Artist

ImageType

BACKGROUND

PRIMARY

PROFILE

MediaType

VIDEO

AUDIO

PlaylistSortBy

enum

NAME	Ascending by Playlist name
LAST_MODIFIED_DATE	Ascending by Playlist last modified date
FOLLOWERS	Descending by number of followers for the Playlist

SearchPlaylistFieldType

Types used for searching playlists

asin

name

artistId

artistName

categoryId

trackId

Selections

Types used for allowed selections in playParams

PLAY

SHUFFLE

STATION

SortByType

Used for sorting search results

relevance

release

popularity

TrackFieldType

Types used for searching tracks

asin

albumId

albumName

artistId

artistName

categoryId

name

isrc

UserTier

The subscription tier for a customer

FREE

PRIME

UNLIMITED

VisibilityType

PUBLIC

PRIVATE

ViewType

LIST

GRID

TABLE

STACK

TEXT