Developer Konsole
Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

Amazon Music Web API

Playback V1.0

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

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.