Amazon Music Web API

Playback V2.0 Overview

Important: These Amazon Music APIs are currently in a closed Beta. Please check back soon for updates.

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 V2 Playback API Concepts

The V2 Playback APIs are queue-centric: you create a playback queue for some content, navigate and mutate that queue, and report playback events back to Amazon Music. All playback endpoints require the music::playback scope.

The queue lifecycle

The playback endpoints group into a lifecycle:

Discover — GET /v2/playback/queues/active lists the caller's active queues.
Create — POST /v2/playback/queues/new creates a queue for the requested content and returns the initial entries needed to begin playback.
Navigate — GET /v2/playback/queues/{id}/current (current entity), .../next, .../previous, .../view (the queue view), and .../entities/{entityReferenceId} (entities at a position).
Mutate — POST /v2/playback/queues/{id}/next (insert an item to play next), POST .../last (add to the end), PUT .../loop (loop mode), and PUT .../shuffle (shuffle mode).
Report events — POST /v2/playback/events (a single event) and POST /v2/playback/events/batch (multiple events).

Handling 206 — queue restoration

Treat 206 as a first-class response, not an edge case. Five navigation endpoints can return 206: GET .../current, GET .../next, GET .../previous, GET .../view, and GET .../entities/{entityReferenceId}.

The reference describes a 206 this way:

Queue was restored before returning results. The queue ID and content may differ from the original queue. Requested sparse fieldsets are still honored in the response.

In other words, when Amazon Music restores a queue, the response you receive may carry a different queue ID and different content than the queue you asked about, while any sparse fieldsets you requested still apply. Clients must handle 206 and adopt the returned queue ID for subsequent calls, rather than continuing to use the ID they sent:

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "entity": { "entityReferenceId": "b6ab22c5-ac87-4011-b1ca-233f604d9c4e" }
  }
}

Queue and event enums

Loop mode (PUT /v2/playback/queues/{id}/loop, and queueState.loopMode): LOOP_ALL, LOOP_ONE, LOOP_OFF.
Shuffle mode (PUT /v2/playback/queues/{id}/shuffle, and queueState.shuffleMode): SHUFFLE_ON, SHUFFLE_OFF.
Playback state (queueState.playbackState, and the required event.playbackState on reported events): PLAYING (playback has started or resumed) and STOPPED (playback has ended, by user action or because the track finished).
Takeover strategy (options.takeOverType on reported events): AUTO attempts a normal report and falls back to taking over the stream on hitting the concurrent-stream limit; FORCE immediately takes over the stream from other devices.

Reporting playback events

Report a start (PLAYING) and stop (STOPPED) event for each track so Amazon Music can advance the queue correctly and attribute streaming. Each event echoes back the metricId string that was returned on the queue entity — pass it back unchanged. Event reporting can return 429 MAX_CONCURRENCY_REACHED when the account's concurrent-stream limit is reached; see Errors.

Streaming and DRM

When you request playback information (via fields[playableEntity]), each entity carries a playbackInformation object describing how to stream it, including url, protocol, format (for example, ENCRYPTED_OPUS_FLAC), expiredAt, licenseUrl, and licenseHeaders. Because a licence expires (expiredAt), clients must detect expiry and re-acquire streaming information rather than reusing stale values.

This page does not restate the DRM or format details — see the shared DRM Playback and Audio Formats pages for the streaming and licence-acquisition model and the available audio formats.

Polymorphic queue entities

Queue entities carry the same _type discriminator used throughout V2 (for example, Track). Switch on _type to interpret an entity and skip unknown values — see Using the Views APIs for the full forward-compatibility contract.