Amazon Music Web API
Playback 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.
Web Playback
API endpoints for retreiving and updating track objects for playback. For an explanation of the basics of playback, see the playback overview.
Create New Session
Intialize a new session and playback queue. Either playbackParams.id or .containerIds must be provided.
Request Parameters
Name |
Data Type |
Required |
Description |
body.playParams.id
|
string
|
No |
The MVN ID of the item for playback |
body.playParams.containerIds
|
string
|
No |
An array of strings of MVN IDs defining the container context of the current playback item. It can be a list of tracks or a single container such as a playlist or album. |
body.playbackOptions.shuffleMode
|
string
|
No |
Enable or disable shuffle mode for playback. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF'. |
body.playbackOptions.loopMode
|
string
|
No |
Enable or disable shuffle mode for playback. Allowed values are 'LOOP_ON' and 'LOOP_OFF'. |
body.playbackOptions.startAsStation
|
bool
|
No |
Start a station based on the requested track. If this parameter is set, shuffleMode will be ignored. |
body.playbackOptions.playbackContinuationMode
|
bool
|
No |
An optional parameter specifying whether to stop playback at the end of the queue or to continue. |
body.limit
|
number
|
No |
This sets the size of the playback queue. Must be a number between 1 and 10 inclusive. |
Example
curl --request GET '<base url>/v1/playback/sessions' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing:
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
"playbackInformation": {
"url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
"x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
"x-amz-music-asin": "B0BS2S4WXN",
"x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
"x-amz-music-device-type": "A3DNCSDVBULX7K",
"x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
"x-amz-music-customer-id": "ASWQDKQ3AFS23",
"x-amz-music-drm-type": "WIDEVINE"
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Get Current Track
GET
/v1/playback/sessions/{sessionId}/current
Retrieves a playback object for the current track.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Example
curl --request PUT '<base url>/v1/me' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data \
'{
"name": "New Name",
"visibility": "PUBLIC",
"playbackVisibility": "PUBLIC"
}'
Response
Amazon Music response object containing:
Name |
Data Type |
Required |
Description |
playback
|
Playback
|
No |
Playback object for the requested track |
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://...",
"playbackInformation": {
"url": "https://...",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
...
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Get Next Track
GET
/v1/playback/sessions/{sessionId}/next
Retrieves a playback object for the next track in the queue.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Query Parameters
Name |
Data Type |
Required |
Description |
body.limit
|
number
|
No |
This sets the size of the playback queue. Must be a number between 1 and 10 inclusive. |
Example
curl --request GET '<base url>/v1/me/library/tracks' \
--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 |
playback
|
Playback
|
No |
Playback object for the requested track |
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
"playbackInformation": {
"url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
"x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
"x-amz-music-asin": "B0BS2S4WXN",
"x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
"x-amz-music-device-type": "A3DNCSDVBULX7K",
"x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
"x-amz-music-customer-id": "ASWQDKQ3AFS23",
"x-amz-music-drm-type": "WIDEVINE"
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Get Previous Track
GET
/v1/playback/sessions/{sessionId}/previous
Retrieves a playback object for the previous track in the queue.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Query Parameters
Name |
Data Type |
Required |
Description |
body.limit
|
number
|
No |
This sets the size of the playback queue. Must be a number between 1 and 10 inclusive. |
Example
curl --request GET '<base url>/v1/me/followers' \
--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 |
playback
|
Playback
|
No |
Playback object for the requested track |
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
"playbackInformation": {
"url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
"x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
"x-amz-music-asin": "B0BS2S4WXN",
"x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
"x-amz-music-device-type": "A3DNCSDVBULX7K",
"x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
"x-amz-music-customer-id": "ASWQDKQ3AFS23",
"x-amz-music-drm-type": "WIDEVINE"
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Get Playback Queue
GET
/v1/playback/sessions/{sessionId}/queue
Get the current user’s list of followed users. Optional parameters can be used to limit the number of followed users to return.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Query Parameters
Name |
Data Type |
Required |
Description |
limit
|
number
|
No |
The maximum number of users 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/playback/sessions/<sessionId>/queue' \
--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 |
user
|
User
|
No |
Data about the current Amazon Music user, including followed users |
Example
Get Active Sessions
GET
/v1/playback/sessions/active
Retrieve all playback sessions across all devices.
Example
curl --request GET '<base url>/v1/playback/sessions/active' \
--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 |
playback
|
Playback
|
No |
Playback object for the requested track |
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
"playbackInformation": {
"url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
"x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
"x-amz-music-asin": "B0BS2S4WXN",
"x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
"x-amz-music-device-type": "A3DNCSDVBULX7K",
"x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
"x-amz-music-customer-id": "ASWQDKQ3AFS23",
"x-amz-music-drm-type": "WIDEVINE"
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Refresh Playback Session
GET
/v1/playback/sessions/{sessionId}/entities/{entityReferenceId}
Used to retrieve an inactive playback session as long as it has been active within the last 30 days. Can also be used to refresh the data inside the queue of the current session.
Path Parameters
Name |
Data Type |
Required |
Description |
entityReferenceId
|
string
|
Yes |
The ID of the session to retrieve (from Playback object). |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Example
curl --request GET '<base url>/v1/playback/sessions/<sessionId>/entities/<entityReferenceId> \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Response
Amazon Music response object containing:
Example
(Some lines omitted for brevity)
{
"data": {
"entities": [
{
"sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
"entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
...
"actions": {
"next": {
"isAllowed": false,
"remainingSkips": 0,
"disableType": "NO_MORE_SKIPS"
},
"previous": {
"isAllowed": false,
"disableType": "FEATURE_NOT_AVAILABLE"
},
...
"shuffle": {
"isAllowed": false
}
},
"track": {
"id": "B0BS2S4WXN",
"type": "Track",
"mediaType": "AUDIO",
"url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
"playbackInformation": {
"url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
"protocol": "DASH",
"format": "ENCRYPTED_OPUS_FLAC",
"licenseHeaders": {
"x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
"x-amz-music-asin": "B0BS2S4WXN",
"x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
"x-amz-music-device-type": "A3DNCSDVBULX7K",
"x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
"x-amz-music-customer-id": "ASWQDKQ3AFS23",
"x-amz-music-drm-type": "WIDEVINE"
}
},
"title": "Flowers",
"subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
"isrc": "USSM12209777",
...
]
}
}
]
}
}
Queue Next Track
POST
/v1/playback/sessions/{sessionId}/queue/next
Insert a track into the playback queue immediately after the current track.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Request Parameters
Name |
Data Type |
Required |
Description |
body.playParams.id
|
string
|
Yes |
The MVN ID of the item for playback. |
body.playParams.containerIds
|
string
|
Yes |
An array of strings of MVN IDs defining the container context of the current playback item. It can be a list of tracks or a single container such as a playlist or album. |
body.entityReferenceId
|
string
|
No |
The MVN ID of the item in the queue after which this new track will be inserted. |
Example
curl --request PUT <base url>/v1/playback/sessions/<sessionId>/queue/next
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
HTTP status 200 on success.
Client is required to retrigger get next track from current position since the next position may have changed.
Queue Last Track
POST
/v1/playback/sessions/{sessionId}/queue/last
Add a track to the end of the playback queue.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Request Parameters
Name |
Data Type |
Required |
Description |
body.playParams.id
|
string
|
Yes |
The MVN ID of the item for playback |
body.playParams.containerIds
|
string
|
Yes |
An array of strings of MVN IDs defining the container context of the current playback item. It can be a list of tracks or a single container such as a playlist or album. |
Example
curl --request POST <base url>/v1/playback/sessions/<sessionId>/queue/last
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
HTTP status 200 on success.
Client may need to retrigger get next track from current position since the next position may have changed.
Set Playback Mode to Loop
PUT
/v1/playback/sessions/{sessionId}/loop
Set the playback queue to loop the current track.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Request Parameters
Name |
Data Type |
Required |
Description |
body.loopMode
|
string
|
Yes |
Enable or disable loop mode. Allowed values are 'LOOP_ONE', 'LOOP_ALL', and 'LOOP_OFF' |
Example
curl --request PUT <base url>/v1/playback/sessions/<sessionId>/loop
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
HTTP status 200 on success.
Client is required to retrigger get next track from current position since the next position may have changed.
Set Playback Mode to Shuffle
PUT
/v1/playback/sessions/{sessionId}/shuffle
Set the playback queue to shuffle the current track.
Path Parameters
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
The ID of the current session (from Playback object). |
Request Parameters
Name |
Data Type |
Required |
Description |
body.shuffleMode
|
string
|
Yes |
Enable or disable shuffle mode. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF' |
Example
curl --request PUT <base url>/v1/playback/sessions/<sessionId>/shuffle
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
HTTP status 200 on success.
Client is required to retrigger get next track from current position since the next position may have changed.
Report Events
Report playback events to the Amazon Music service.
This endpoint supports three concurrency handling scenarios that can be used to resolve playback conflicts. By default, when there is a concurrency error the backend will take over the existing stream to start a new playback session. The AUTO option will return an error to the client. The client can then decide how to resolve the conflict, either by displaying a prompt to take over the session or by stopping playback. FORCE will force the backend to take over the existing stream if there is a concurrency error.
Body Parameters
Name |
Data Type |
Required |
Description |
body.metricId
|
string
|
Yes |
The metric ID to report (from Playback). |
body.event
|
object
|
Yes |
The event object (from Playback). |
body.options.takeOverType
|
object
|
No |
Allowed values are 'AUTO' and 'FORCE'. |
Example
curl --request PUT <base url>/v1/playback/event
--header 'x-api-key: <your security profile ID>'
--header 'Authorization: Bearer <your auth token>'
Responses
HTTP status 200 on success.