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
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. |
| 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 |
Category
| 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
| id |
| asin |
| artistId |
| artistName |
| categoryId |
| name |
ArtistFieldType
Types used for searching artists
CategoryType
Enum
EntityType
| Album |
| Artist |
| Category |
| Playlist |
| PodcastEpisode |
| PodcastShow |
| Track |
| User |
ImageType
| BACKGROUND |
| PRIMARY |
| PROFILE |
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
| id |
| asin |
| name |
| artistId |
| artistName |
| categoryId |
| trackId |
Selections
Types used for allowed selections in playParams
SortByType
Used for sorting search results
| relevance |
| release |
| popularity |
TrackFieldType
Types used for searching tracks
| id |
| asin |
| albumId |
| albumName |
| artistId |
| artistName |
| categoryId |
| name |
| isrc |
UserTier
The subscription tier for a customer
VisibilityType
ViewType
| LIST |
| GRID |
| TABLE |
| STACK |
| TEXT |
