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
Get Current Track
Get Next Track
Get Previous Track
Get Playback Queue
Get Active Sessions
Refresh Playback Session
Queue Next Track
Queue Last Track
Set Playback Mode to Loop
Set Playback Mode to Shuffle
Report Events

Create New Session

POST

/playback/sessions

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:

Name	Data Type	Required	Description
playback	InitialPlaybackSessionResponse	Yes	Playback session object

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

{
  "data": {
    ...
  }
}

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:

Name	Data Type	Required	Description
playback	InitialPlaybackSessionResponse	Yes	Playback session object

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

POST

/v1/playback/event

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.