Amazon Music Web API
Web API Overview V2.0
Amazon Music Web API V2
Version 2 of the Amazon Music Web API is a redesigned, resource-oriented API for retrieving metadata about albums, artists, tracks, playlists, podcasts, stations, and more from the Amazon Music catalog, along with user library and playback data when the user grants permission.
Base URL
Use this URL wherever you encounter <base url>. All V2 endpoints are served under the /v2 base path.
An example request for a list of albums might appear as follows:
curl --location '<base url>/v2/albums?ids=B0064UPU4G%2CB091BHTFTZ' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
What is new in V2
V2 differs from V1 in several important ways. Review these behaviors before porting an existing V1 integration.
Different base host
V2 is served from a different host than V1. V2 requests go to https://api.music.amazon.com, whereas V1 is served from https://api.music.amazon.dev. If you are porting a V1 integration, update the host as well as the /v1 → /v2 path segment — changing only the path prefix will keep your requests pointed at the V1 host and they will not reach V2.
Unwrapped responses
V2 responses are unwrapped. The requested resource is returned at the top level of the response body — there is no data envelope. This differs from V1, where results are nested inside a data field.
[
{ "id": "B073J5NW51", "title": "Sound Awake" },
{ "id": "B07YVNQFHB", "title": "Asymmetry" }
]
Cursor pagination
Collection endpoints use cursor-based pagination via the first and after query parameters:
first— The number of items to return. Default page size is20; the maximum is100.after— The cursor to continue from, taken from the previous response.
When more results are available, the response includes a nextToken value. Pass it back as after to fetch the next page. When nextToken is absent, you have reached the end of the collection.
curl --location '<base url>/v2/albums/top?first=20&after=<nextToken>' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Sparse fieldsets
V2 lets you request only the fields you need using fields[<type>] query parameters. Each parameter takes a comma-separated list of field names for the named entity type, which reduces payload size and improves latency.
curl --location '<base url>/v2/albums?ids=B0064UPU4G&fields[album]=title,id&fields[artist]=name' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Polymorphic entities
Some collections return polymorphic entities. Each entity carries a _type discriminator field identifying its concrete type. Clients should switch on _type to interpret an entity, and should treat unknown _type values as opaque and skip them, so that new entity types added in the future do not break your integration.
Authentication
All V2 endpoints require a valid OAuth 2.0 bearer token issued by Login With Amazon (LWA). Every request must include two headers:
Authorization—Bearer <your auth token>, the token returned by LWA.x-api-key— your LWA Security Profile ID (looks likeamzn1.application.xxxxxxxxxx). This is not the Client ID (amzn1.application-oa2-client.xxx) used to acquire the token.
Endpoints declare the OAuth scopes they require, such as music::catalog for catalog metadata, music::library:read for a user's library, and music::history for playback history. Request the scopes appropriate to the endpoints you call.
For details on obtaining tokens and configuring a Security Profile, see Authentication.
Error handling
V2 returns errors using a consistent shape with an error object:
{
"error": {
"code": "NOT_FOUND",
"message": "The requested resource could not be found.",
"traceId": "1-63f1a2b3-c4d5e6f7a8b9c0d1e2f3a4b5"
}
}
Include the traceId when reporting an issue to your Amazon Music point-of-contact. Playback endpoints can return a 429 with the error code MAX_CONCURRENCY_REACHED ("Concurrent stream limit exceeded") when a user's concurrent stream limit is reached. For the full set of V2 error codes and their HTTP statuses, see the V2 Errors reference.
Reference
The V2 reference documents each resource domain:
