Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Amazon Music Web API

Web API User Library V2.0

User Library

Get current user's profile

GET
/v2/me
Authorization Scope: [music::profile:read]
Get detailed profile information about the current authenticated user, including identity fields (`id`, `name`, `handle`, `url`) and — when the partner opts in via sparse fieldsets — tier, visibility settings, country code, and avatar images.

Supports sparse fieldsets via query parameters:

  • fields[user] — Comma-separated user fields (e.g. tier,visibility,playbackVisibility,countryCode,images)
  • fields[image] — Comma-separated image fields (e.g. url,width,height)

Response 200

Successful response

Response Schema

_type
string
Discriminator value identifying this entity as a User
id
string
Unique user identifier
name
string
Display name of the user
handle
string
Public handle (username) chosen by the user
url
string [format=uri]
URL into AmazonMusic for this user profile
visibility
VisibilityType
Visibility setting that controls who can see this user's public profile.
playbackVisibility
VisibilityType
Visibility setting that controls who can see this user's playback activity.
countryCode
string
ISO 3166-1 alpha-2 country code of the music territory this user is currently authenticated against. Set by the service from the auth context for `me`-scoped responses; not present on third-party user lookups.
tier
enum (FREE|PRIME|UNLIMITED)
Subscription tier of the user.
images
Image[]
Avatar images for this user

Example

Current user's profile with full User fields

{
  "id": "B0DCXMPL01",
  "name": "Joaquin",
  "handle": "joaquin123",
  "url": "https://music.amazon.com/users/B0DCXMPL01",
  "visibility": "PUBLIC",
  "playbackVisibility": "PRIVATE",
  "countryCode": "US",
  "tier": "UNLIMITED",
  "images": [
    {
      "url": "https://m.media-amazon.com/images/I/user-profile-400.jpg",
      "width": 400,
      "height": 400
    },
    {
      "url": "https://m.media-amazon.com/images/I/user-profile-150.jpg",
      "width": 150,
      "height": 150
    }
  ]
}

Sparse Fieldsets Example

Sparse fieldsets — fields[user]=id,name,handle,visibility

{
  "id": "B0DCXMPL01",
  "name": "Joaquin",
  "handle": "joaquin123",
  "visibility": "PUBLIC"
}

Error Responses

Response Code Status Message
401 UNAUTHORIZED 401 Authentication required
404 NOT_FOUND 404 User not found

401 Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "traceId": "1-abc-def"
  }
}

Update current user's profile

PATCH
/v2/me
Authorization Scope: [music::profile]
Update mutable profile fields for the current authenticated user. All fields in the request body are optional; only the provided fields are written. Returns the user's updated profile reflecting the new server-side state.

Request Body

Request Schema

name
string
New display name for the user
visibility
VisibilityType
New profile visibility setting
playbackVisibility
VisibilityType
New playback visibility setting

Request Example

{
  "name": "Joaquin",
  "visibility": "PUBLIC",
  "playbackVisibility": "PRIVATE"
}

Response 200

Profile updated successfully

Response Schema

_type
string
Discriminator value identifying this entity as a User
id
string
Unique user identifier
name
string
Display name of the user
handle
string
Public handle (username) chosen by the user
url
string [format=uri]
URL into AmazonMusic for this user profile
visibility
VisibilityType
Visibility setting that controls who can see this user's public profile.
playbackVisibility
VisibilityType
Visibility setting that controls who can see this user's playback activity.
countryCode
string
ISO 3166-1 alpha-2 country code of the music territory this user is currently authenticated against. Set by the service from the auth context for `me`-scoped responses; not present on third-party user lookups.
tier
enum (FREE|PRIME|UNLIMITED)
Subscription tier of the user.
images
Image[]
Avatar images for this user

Example

{
  "id": "B0DCXMPL01",
  "name": "Joaquin",
  "handle": "joaquin123",
  "url": "https://music.amazon.com/users/B0DCXMPL01",
  "visibility": "PUBLIC",
  "playbackVisibility": "PRIVATE"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 visibility must be one of [PUBLIC, PRIVATE]
401 UNAUTHORIZED 401 Authentication required
404 NOT_FOUND 404 User not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "visibility must be one of [PUBLIC, PRIVATE]",
    "traceId": "1-abc-def"
  }
}

401 Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "traceId": "1-abc-def"
  }
}

Get recently played tracks

GET
/v2/me/player/recently-played
Authorization Scope: [music::history]
Retrieve tracks from the calling user's recently played history, ordered by most-recent playback first.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[track] — Comma-separated track fields (e.g. title,id,duration)
  • fields[album] — Comma-separated album fields (e.g. title,id)
  • fields[artist] — Comma-separated artist fields (e.g. name)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Track[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Recently played tracks for the calling user with full Track fields

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "isrc": "USRC11902727",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2020-04-10T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KPC3Q7",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "isrc": "USRC10500421",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2006-01-03T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B004S8NBPG",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP310"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[track]=title,id,duration,artists&fields[artist]=name

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP310"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Get recently played entities (artists, albums, playlists)

GET
/v2/me/player/recently-played-entities
Authorization Scope: [music::history]
Retrieve a heterogeneous feed of entities (artists, albums, and playlists) from the calling user's recently played history, ordered by most-recent playback first.

Each item is one of EntityArtist, EntityAlbum, or EntityPlaylist, identified by the _type discriminator. Partners should switch on _type to interpret each item; unknown values must be treated as opaque and skipped.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Use entityTypes to scope the response to a subset of types. Allowed values: ARTIST, ALBUM, PLAYLIST. When omitted, all three types are returned.

Supports sparse fieldsets via query parameters:

  • fields[artist] — Comma-separated artist fields (e.g. id,name,images)
  • fields[album] — Comma-separated album fields (e.g. id,title,releaseDate)
  • fields[playlist] — Comma-separated playlist fields (e.g. id,title,trackCount)
  • fields[image] — Comma-separated image fields (e.g. url,width,height)

Query Parameters

Name Data Type Required Description
entityTypes string (ARTIST|ALBUM|PLAYLIST)[] No Optional comma-separated list of entity types to include in the response. Allowed values are ARTIST, ALBUM, PLAYLIST.
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Entity[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Recently played entities — mixed artists, albums, and playlists

{
  "items": [
    {
      "_type": "Artist",
      "id": "B00G70DLAS",
      "name": "the-strokes",
      "url": "https://music.amazon.com/artists/B00G70DLAS",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/artist-the-strokes.jpg",
          "width": 600,
          "height": 600
        }
      ]
    },
    {
      "_type": "Album",
      "id": "B084KP4NBH",
      "title": "The New Abnormal",
      "releaseDate": "2020-04-10T00:00:00.000Z",
      "trackCount": 9,
      "url": "https://music.amazon.com/albums/B084KP4NBH"
    },
    {
      "_type": "Playlist",
      "id": "B0EXAMP701",
      "title": "Rainy Day Indie",
      "trackCount": 42,
      "url": "https://music.amazon.com/playlists/B0EXAMP701"
    }
  ],
  "nextToken": "B0EXAMP311"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[artist]=id,name&fields[album]=id,title&fields[playlist]=id,title

{
  "items": [
    {
      "_type": "Artist",
      "id": "B00G70DLAS",
      "name": "the-strokes"
    },
    {
      "_type": "Album",
      "id": "B084KP4NBH",
      "title": "The New Abnormal"
    },
    {
      "_type": "Playlist",
      "id": "B0EXAMP701",
      "title": "Rainy Day Indie"
    }
  ],
  "nextToken": "B0EXAMP311"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 entityTypes must be a subset of [ARTIST, ALBUM, PLAYLIST]
401 UNAUTHORIZED 401 Authentication required
404 NOT_FOUND 404 User not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "entityTypes must be a subset of [ARTIST, ALBUM, PLAYLIST]",
    "traceId": "1-abc-def"
  }
}

401 Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "traceId": "1-abc-def"
  }
}

Get liked tracks

GET
/v2/me/tracks/liked
Authorization Scope: [music::library:read]
Retrieve the calling user's liked tracks. Optionally filter by specific track IDs via the `trackIds` query parameter.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[track] — Comma-separated track fields (e.g. title,id,duration)
  • fields[album] — Comma-separated album fields (e.g. title,id)
  • fields[artist] — Comma-separated artist fields (e.g. name)

Query Parameters

Name Data Type Required Description
trackIds string No Comma-separated track IDs to filter results
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Track[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Liked tracks for the calling user with full Track fields

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "isrc": "USRC11902727",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2020-04-10T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KPC3Q7",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "isrc": "USRC10500421",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2006-01-03T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B004S8NBPG",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP320"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[track]=title,id,duration,artists&fields[artist]=name

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP320"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Set track like state

PUT
/v2/me/tracks/{id}/like-state
Authorization Scope: [music::favorites]
Save preference information for a track. Accepts one of three states: `LIKE`, `DISLIKE`, or `NEUTRAL` (which clears any prior like/dislike). Idempotent: setting the current state succeeds with the same payload as a state-changing call. A 200 response returns the track and confirms the resulting like state.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Request Body

Request Schema

likeState
enum (LIKE|DISLIKE|NEUTRAL)
The like state to set for the track

Request Example

{
  "likeState": "LIKE"
}

Response 200

Successful response

Response Schema

track
BaseTrack
likeState
enum (LIKE|DISLIKE|NEUTRAL)

Example

{
  "track": {
    "id": "B084KPC3Q7",
    "title": "Selfless",
    "duration": 222
  },
  "likeState": "LIKE"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Track not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Track not found",
    "traceId": "1-abc-def"
  }
}

Get library tracks

GET
/v2/me/tracks
Authorization Scope: [music::library:read]
Retrieve tracks from the calling user's library. Optionally filter by specific track IDs via the `trackIds` query parameter.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[track] — Comma-separated track fields (e.g. title,id,duration)
  • fields[album] — Comma-separated album fields (e.g. title,id)
  • fields[artist] — Comma-separated artist fields (e.g. name)

Query Parameters

Name Data Type Required Description
trackIds string No Comma-separated track IDs to filter results
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Track[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Library tracks with full Track fields populated

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "isrc": "USRC11902727",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2020-04-10T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KPC3Q7",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "isrc": "USRC10500421",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2006-01-03T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B004S8NBPG",
      "album": {
        "id": "B084KP4NBH",
        "title": "The New Abnormal"
      },
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP300"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[track]=title,id,duration,artists&fields[artist]=name

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "title": "Selfless",
      "duration": 222,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    },
    {
      "id": "B004S8NBPG",
      "title": "Metabolism",
      "duration": 181,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP300"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Save track to library

PUT
/v2/me/tracks/{id}
Authorization Scope: [music::library]
Save a track to the calling user's library. Idempotent: saving an already-saved track succeeds with the same payload as an initial save. A 200 response returns the track and confirms the resulting `saved: true` state.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

track
BaseTrack
saved
boolean
Whether the track is saved in the library

Example

{
  "track": {
    "id": "B084KPC3Q7",
    "title": "Selfless",
    "duration": 222
  },
  "saved": true
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Track not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Track not found",
    "traceId": "1-abc-def"
  }
}

Remove track from library

DELETE
/v2/me/tracks/{id}
Authorization Scope: [music::library]
Remove a track from the calling user's library. Idempotent: removing a not-saved track succeeds with the same payload as an initial removal. A 200 response returns the track and confirms the resulting `saved: false` state.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

track
BaseTrack
saved
boolean
Whether the track is saved in the library

Example

{
  "track": {
    "id": "B084KPC3Q7",
    "title": "Selfless",
    "duration": 222
  },
  "saved": false
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Track not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Track not found",
    "traceId": "1-abc-def"
  }
}

Get followed artists

GET
/v2/me/artists
Authorization Scope: [music::favorites:read]
Retrieve artists followed by the calling user. Optionally filter to a specific subset by passing a comma-separated list of artist IDs via the `artistIds` query parameter (maximum 100 IDs).

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[artist] — Comma-separated artist fields (e.g. name,id,images)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
artistIds string No Comma-separated artist IDs to filter results (max 100)
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Artist[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Followed artists with full Artist fields

{
  "items": [
    {
      "id": "B000X6FP38",
      "name": "Karnivool",
      "followerCount": 123456,
      "url": "https://music.amazon.com/artists/B000X6FP38",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B000X6FP38-1200.jpg",
          "width": 1200,
          "height": 1200,
          "imageType": "PRIMARY"
        }
      ]
    },
    {
      "id": "B001ARTST2",
      "name": "Periphery",
      "followerCount": 654321,
      "url": "https://music.amazon.com/artists/B001ARTST2",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B001ARTST2-1200.jpg",
          "width": 1200,
          "height": 1200,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG04"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[artist]=name,id,images&fields[image]=url

{
  "items": [
    {
      "id": "B000X6FP38",
      "name": "Karnivool",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B000X6FP38-1200.jpg"
        }
      ]
    },
    {
      "id": "B001ARTST2",
      "name": "Periphery",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B001ARTST2-1200.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG04"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Follow an artist

PUT
/v2/me/artists/{id}
Authorization Scope: [music::favorites]
Add the calling user as a follower of an artist. Idempotent: following an already-followed artist succeeds with the same payload as an initial follow. A 200 response confirms the resulting follow state; a 404 is returned when the artist id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

artist
BaseArtist
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "artist": {
    "id": "B000X6FP38",
    "name": "Karnivool"
  },
  "followState": "FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Artist not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Artist not found",
    "traceId": "1-abc-def"
  }
}

Unfollow an artist

DELETE
/v2/me/artists/{id}
Authorization Scope: [music::favorites]
Remove the calling user as a follower of an artist. Idempotent: unfollowing a not-followed artist succeeds with the same payload as an initial unfollow. A 200 response confirms the resulting follow state; a 404 is returned when the artist id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

artist
BaseArtist
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "artist": {
    "id": "B000X6FP38",
    "name": "Karnivool"
  },
  "followState": "NOT_FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Artist not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Artist not found",
    "traceId": "1-abc-def"
  }
}

Get saved podcast episodes

GET
/v2/me/podcasts/episodes
Authorization Scope: [music::library:read]
Retrieve podcast episodes saved by the calling user. Optionally filter to a specific subset by passing a comma-separated list of episode IDs via the `podcastEpisodeIds` query parameter (maximum 100 IDs).

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[podcastEpisode] — Comma-separated episode fields (e.g. title,id,duration,podcastShow)
  • fields[podcastShow] — Comma-separated show fields (e.g. title,id)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
podcastEpisodeIds string No Comma-separated podcast episode IDs to filter results (max 100)
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
PodcastEpisode[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Saved podcast episodes with full PodcastEpisode fields

{
  "items": [
    {
      "id": "B0EXAMP610",
      "title": "Episode 42 — The Halting Problem in Practice",
      "type": "FULL",
      "description": "Why undecidability shows up in production runbooks more often than you think.",
      "author": "Synthetic Studios",
      "seasonNumber": 1,
      "episodeNumber": 42,
      "duration": 2640,
      "releaseDate": "2025-04-12T00:00:00.000Z",
      "url": "https://music.amazon.com/podcasts/B0EXAMP600/episodes/B0EXAMP610",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP610-1400.jpg",
          "width": 1400,
          "height": 1400,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      },
      "podcastShow": {
        "id": "B0EXAMP600",
        "title": "Tech Frontiers Daily",
        "type": "EPISODIC",
        "author": "Synthetic Studios",
        "url": "https://music.amazon.com/podcasts/B0EXAMP600"
      }
    },
    {
      "id": "B0EXAMP611",
      "title": "Episode 43 — From Big-O to Bigger Outcomes",
      "type": "FULL",
      "description": "A field guide to translating algorithmic wins into product outcomes.",
      "author": "Synthetic Studios",
      "seasonNumber": 1,
      "episodeNumber": 43,
      "duration": 2820,
      "releaseDate": "2025-04-13T00:00:00.000Z",
      "url": "https://music.amazon.com/podcasts/B0EXAMP600/episodes/B0EXAMP611",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP611-1400.jpg",
          "width": 1400,
          "height": 1400,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      },
      "podcastShow": {
        "id": "B0EXAMP600",
        "title": "Tech Frontiers Daily",
        "type": "EPISODIC",
        "author": "Synthetic Studios",
        "url": "https://music.amazon.com/podcasts/B0EXAMP600"
      }
    }
  ],
  "nextToken": "B0EXAMP630"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[podcastEpisode]=title,id,duration,podcastShow&fields[podcastShow]=title,id

{
  "items": [
    {
      "id": "B0EXAMP610",
      "title": "Episode 42 — The Halting Problem in Practice",
      "duration": 2640,
      "podcastShow": {
        "id": "B0EXAMP600",
        "title": "Tech Frontiers Daily"
      }
    },
    {
      "id": "B0EXAMP611",
      "title": "Episode 43 — From Big-O to Bigger Outcomes",
      "duration": 2820,
      "podcastShow": {
        "id": "B0EXAMP600",
        "title": "Tech Frontiers Daily"
      }
    }
  ],
  "nextToken": "B0EXAMP630"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Save podcast episode to library

PUT
/v2/me/podcasts/episodes/{id}
Authorization Scope: [music::library]
Save a podcast episode to the calling user's library. Idempotent: saving an already-saved episode succeeds with the same payload as an initial save. A 200 response returns the episode and confirms the resulting `saved: true` state.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

podcastEpisode
BasePodcastEpisode
saved
boolean
Whether the episode is saved in the library

Example

{
  "podcastEpisode": {
    "id": "B0EXAMP610",
    "title": "Episode 42 — The Halting Problem in Practice",
    "duration": 2640
  },
  "saved": true
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Podcast episode not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Podcast episode not found",
    "traceId": "1-abc-def"
  }
}

Remove podcast episode from library

DELETE
/v2/me/podcasts/episodes/{id}
Authorization Scope: [music::library]
Remove a podcast episode from the calling user's library. Idempotent: removing a not-saved episode succeeds with the same payload as an initial removal. A 200 response returns the episode and confirms the resulting `saved: false` state.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

podcastEpisode
BasePodcastEpisode
saved
boolean
Whether the episode is saved in the library

Example

{
  "podcastEpisode": {
    "id": "B0EXAMP610",
    "title": "Episode 42 — The Halting Problem in Practice",
    "duration": 2640
  },
  "saved": false
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Podcast episode not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Podcast episode not found",
    "traceId": "1-abc-def"
  }
}

Get followed podcast shows

GET
/v2/me/podcasts/shows
Authorization Scope: [music::favorites:read]
Retrieve podcast shows followed by the calling user.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[podcastShow] — Comma-separated show fields (e.g. title,id,images)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
PodcastShow[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Followed podcast shows with full PodcastShow fields

{
  "items": [
    {
      "id": "B0EXAMP600",
      "title": "Tech Frontiers Daily",
      "type": "EPISODIC",
      "description": "Daily conversations about software, systems, and the people who build them.",
      "author": "Synthetic Studios",
      "url": "https://music.amazon.com/podcasts/B0EXAMP600",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP600-1400.jpg",
          "width": 1400,
          "height": 1400,
          "imageType": "PRIMARY"
        },
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP600-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B0EXAMP601",
      "title": "Algorithm Avenue",
      "type": "SERIAL",
      "description": "A serialised tour of the algorithms that quietly run the modern internet.",
      "author": "Synthetic Studios",
      "url": "https://music.amazon.com/podcasts/B0EXAMP601",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP601-1400.jpg",
          "width": 1400,
          "height": 1400,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP640"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[podcastShow]=title,id,author,images&fields[image]=url

{
  "items": [
    {
      "id": "B0EXAMP600",
      "title": "Tech Frontiers Daily",
      "author": "Synthetic Studios",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP600-640.jpg"
        }
      ]
    },
    {
      "id": "B0EXAMP601",
      "title": "Algorithm Avenue",
      "author": "Synthetic Studios",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP601-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP640"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Follow a podcast show

PUT
/v2/me/podcasts/shows/{id}
Authorization Scope: [music::favorites]
Add the calling user as a follower of a podcast show. Idempotent: following an already-followed show succeeds with the same payload as an initial follow. A 200 response confirms the resulting follow state; a 404 is returned when the show id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

podcastShow
BasePodcastShow
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "podcastShow": {
    "id": "B0EXAMP600",
    "title": "Tech Frontiers Daily"
  },
  "followState": "FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Podcast show not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Podcast show not found",
    "traceId": "1-abc-def"
  }
}

Unfollow a podcast show

DELETE
/v2/me/podcasts/shows/{id}
Authorization Scope: [music::favorites]
Remove the calling user as a follower of a podcast show. Idempotent: unfollowing a not-followed show succeeds with the same payload as an initial unfollow. A 200 response confirms the resulting follow state; a 404 is returned when the show id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

podcastShow
BasePodcastShow
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "podcastShow": {
    "id": "B0EXAMP600",
    "title": "Tech Frontiers Daily"
  },
  "followState": "NOT_FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Podcast show not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Podcast show not found",
    "traceId": "1-abc-def"
  }
}

Get account preferences

GET
/v2/me/preferences
Authorization Scope: [music::profile:read]
Retrieve the calling user's account-level preferences. Returns whether explicit language is permitted in playback content for this user. The value is sourced from the auth context (set during the auth flow from the user's AmazonMusic account preferences) — no downstream call is made.

Response 200

Successful response

Response Schema

isExplicitLanguageAllowed
boolean
Whether explicit language is permitted in playback content for the calling user. `true` allows explicit content; `false` blocks it. Mirrors the `allowedParentalControls.hasExplicitLanguage` setting on the user's AmazonMusic account.

Example

{
  "isExplicitLanguageAllowed": true
}

Error Responses

Response Code Status Message
401 UNAUTHORIZED 401 Authentication required

401 Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "traceId": "1-abc-def"
  }
}

Set account preferences

PUT
/v2/me/preferences
Authorization Scope: [music::profile]
Update the calling user's account-level preferences. Currently supports the explicit-language preference. A 200 response confirms the applied state.

Request Body

Request Schema

isExplicitLanguageAllowed
boolean
Whether explicit language is permitted in playback content for the calling user. `true` allows explicit content; `false` blocks it. Mirrors the `allowedParentalControls.hasExplicitLanguage` setting on the user's AmazonMusic account.

Request Example

{
  "isExplicitLanguageAllowed": true
}

Response 200

Successful response

Response Schema

isExplicitLanguageAllowed
boolean
Whether explicit language is permitted in playback content for the calling user. `true` allows explicit content; `false` blocks it. Mirrors the `allowedParentalControls.hasExplicitLanguage` setting on the user's AmazonMusic account.

Example

{
  "isExplicitLanguageAllowed": true
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 isExplicitLanguageAllowed must be a boolean
401 UNAUTHORIZED 401 Authentication required

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "isExplicitLanguageAllowed must be a boolean",
    "traceId": "1-abc-def"
  }
}

401 Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "traceId": "1-abc-def"
  }
}

Get followed users

GET
/v2/me/users
Authorization Scope: [music::favorites:read]
Retrieve AmazonMusic users followed by the calling user.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[user] — Comma-separated user fields (e.g. name,handle,images)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
User[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Followed users with full User fields

{
  "items": [
    {
      "id": "B0EXAMPL01",
      "name": "Mira Hayashi",
      "handle": "mira-hayashi",
      "url": "https://music.amazon.com/users/B0EXAMPL01",
      "visibility": "PUBLIC",
      "playbackVisibility": "PUBLIC",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL01-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PROFILE"
        }
      ]
    },
    {
      "id": "B0EXAMPL02",
      "name": "Daniel Okafor",
      "handle": "d-okafor",
      "url": "https://music.amazon.com/users/B0EXAMPL02",
      "visibility": "PUBLIC",
      "playbackVisibility": "PRIVATE",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL02-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PROFILE"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[user]=name,handle,images&fields[image]=url

{
  "items": [
    {
      "id": "B0EXAMPL01",
      "name": "Mira Hayashi",
      "handle": "mira-hayashi",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL01-640.jpg"
        }
      ]
    },
    {
      "id": "B0EXAMPL02",
      "name": "Daniel Okafor",
      "handle": "d-okafor",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL02-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Follow a user

PUT
/v2/me/users/{id}
Authorization Scope: [music::favorites]
Add the calling user as a follower of another AmazonMusic user. Idempotent: following an already-followed user succeeds with the same payload as an initial follow. A 200 response confirms the resulting follow state; a 404 is returned when the user id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

user
BaseUser
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "user": {
    "id": "B0EXAMPL01",
    "name": "Mira Hayashi",
    "handle": "mira-hayashi"
  },
  "followState": "FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 User not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "traceId": "1-abc-def"
  }
}

Unfollow a user

DELETE
/v2/me/users/{id}
Authorization Scope: [music::favorites]
Remove the calling user as a follower of another AmazonMusic user. Idempotent: unfollowing a not-followed user succeeds with the same payload as an initial unfollow. A 200 response confirms the resulting follow state; a 404 is returned when the user id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

user
BaseUser
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "user": {
    "id": "B0EXAMPL01",
    "name": "Mira Hayashi",
    "handle": "mira-hayashi"
  },
  "followState": "NOT_FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 User not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found",
    "traceId": "1-abc-def"
  }
}

Get followers

GET
/v2/me/followers
Authorization Scope: [music::favorites:read]
Retrieve AmazonMusic users who follow the calling user.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[user] — Comma-separated user fields (e.g. name,handle,images)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
User[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Followers with full User fields

{
  "items": [
    {
      "id": "B0EXAMPL04",
      "name": "Priya Mahajan",
      "handle": "priya-m",
      "url": "https://music.amazon.com/users/B0EXAMPL04",
      "visibility": "PUBLIC",
      "playbackVisibility": "PUBLIC",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL04-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PROFILE"
        }
      ]
    },
    {
      "id": "B0EXAMPL05",
      "name": "Theo Lambert",
      "handle": "t-lambert",
      "url": "https://music.amazon.com/users/B0EXAMPL05",
      "visibility": "PUBLIC",
      "playbackVisibility": "PRIVATE",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL05-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PROFILE"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG05"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[user]=name,handle,images&fields[image]=url

{
  "items": [
    {
      "id": "B0EXAMPL04",
      "name": "Priya Mahajan",
      "handle": "priya-m",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL04-640.jpg"
        }
      ]
    },
    {
      "id": "B0EXAMPL05",
      "name": "Theo Lambert",
      "handle": "t-lambert",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMPL05-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG05"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Get owned playlists

GET
/v2/me/playlists/owned
Authorization Scope: [music::library:read]
Retrieve playlists owned by the calling user. This is the "creator" view — playlists the partner authored, distinct from the playlists the partner follows (see `GET /v2/me/playlists/followed`).

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports an optional sortBy query parameter to control the order of results, plus sparse fieldsets via:

  • fields[playlist] — Comma-separated playlist fields (e.g. title,id,trackCount)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after
sortBy PlaylistSortBy No Field to sort by

Response 200

Successful response

Response Schema

items
Playlist[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Owned playlists with full Playlist fields

{
  "items": [
    {
      "id": "B0PLAYLST1",
      "title": "Late Night Coding",
      "description": "Synthwave for shipping at 2am.",
      "visibility": "PRIVATE",
      "trackCount": 24,
      "duration": 5760,
      "url": "https://music.amazon.com/playlists/B0PLAYLST1",
      "owner": {
        "id": "B0EXAMPL01",
        "name": "Mira Hayashi",
        "handle": "mira-hayashi"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST1-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    },
    {
      "id": "B0PLAYLST2",
      "title": "Sunday Reset",
      "description": "Acoustic mornings.",
      "visibility": "PUBLIC",
      "trackCount": 12,
      "duration": 2880,
      "url": "https://music.amazon.com/playlists/B0PLAYLST2",
      "owner": {
        "id": "B0EXAMPL01",
        "name": "Mira Hayashi",
        "handle": "mira-hayashi"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST2-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG02"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[playlist]=title,id,trackCount&fields[image]=url

{
  "items": [
    {
      "id": "B0PLAYLST1",
      "title": "Late Night Coding",
      "trackCount": 24
    },
    {
      "id": "B0PLAYLST2",
      "title": "Sunday Reset",
      "trackCount": 12
    }
  ],
  "nextToken": "B0NEXTPG02"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Get followed playlists

GET
/v2/me/playlists/followed
Authorization Scope: [music::favorites:read]
Retrieve playlists followed by the calling user. Optionally filter to a specific subset by passing a comma-separated list of playlist IDs via the `playlistIds` query parameter (maximum 100 IDs).

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[playlist] — Comma-separated playlist fields (e.g. title,id,images)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
playlistIds string No Comma-separated playlist IDs to filter results (max 100)
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Playlist[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Followed playlists with full Playlist fields

{
  "items": [
    {
      "id": "B0PLAYLST3",
      "title": "Indie Discoveries",
      "description": "Curated weekly drops from the indie scene.",
      "visibility": "PUBLIC",
      "trackCount": 50,
      "duration": 12000,
      "url": "https://music.amazon.com/playlists/B0PLAYLST3",
      "owner": {
        "id": "B0EXAMPL02",
        "name": "Daniel Okafor",
        "handle": "d-okafor"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST3-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    },
    {
      "id": "B0PLAYLST4",
      "title": "Mood: Focus",
      "description": "Long-form ambient for deep work.",
      "visibility": "PUBLIC",
      "trackCount": 80,
      "duration": 19200,
      "url": "https://music.amazon.com/playlists/B0PLAYLST4",
      "owner": {
        "id": "B0EXAMPL03",
        "name": "Sam Rivera",
        "handle": "s-rivera"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST4-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG03"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[playlist]=title,id,trackCount,images&fields[image]=url

{
  "items": [
    {
      "id": "B0PLAYLST3",
      "title": "Indie Discoveries",
      "trackCount": 50,
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST3-640.jpg"
        }
      ]
    },
    {
      "id": "B0PLAYLST4",
      "title": "Mood: Focus",
      "trackCount": 80,
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0PLAYLST4-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG03"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Follow a playlist

PUT
/v2/me/playlists/{id}
Authorization Scope: [music::favorites]
Add the calling user as a follower of a playlist. Idempotent: following an already-followed playlist succeeds with the same payload as an initial follow. A 200 response confirms the resulting follow state; a 404 is returned when the playlist id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

playlist
BasePlaylist
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "playlist": {
    "id": "B0PLAYLST3",
    "title": "Indie Discoveries"
  },
  "followState": "FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Playlist not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Playlist not found",
    "traceId": "1-abc-def"
  }
}

Unfollow a playlist

DELETE
/v2/me/playlists/{id}
Authorization Scope: [music::favorites]
Remove the calling user as a follower of a playlist. Idempotent: unfollowing a not-followed playlist succeeds with the same payload as an initial unfollow. A 200 response confirms the resulting follow state; a 404 is returned when the playlist id does not resolve.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

playlist
BasePlaylist
followState
enum (FOLLOWING|NOT_FOLLOWING)

Example

{
  "playlist": {
    "id": "B0PLAYLST3",
    "title": "Indie Discoveries"
  },
  "followState": "NOT_FOLLOWING"
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Playlist not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Playlist not found",
    "traceId": "1-abc-def"
  }
}

Get library albums

GET
/v2/me/albums
Authorization Scope: [music::library:read]
Retrieve albums saved in the calling user's library. Optionally filter to specific `albumIds`, and order results with `sortBy` (Relevance, Name, or DateAdded). Paginated with a forward-only cursor (`first` up to 100, then `after`). Supports sparse fieldsets via the `fields[album]` query parameter.

Query Parameters

Name Data Type Required Description
albumIds string[] No Album IDs to filter results
first integer No Number of items to return
after string No Cursor to start after
sortBy string (Relevance|Name|DateAdded) No Sort order for library albums

Response 200

Successful response

Response Schema

items
BaseAlbum[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example (default)

Library albums response

{
  "items": [
    {
      "id": "B0B97YW7G7",
      "title": "Periphery III: Select Difficulty",
      "releaseDate": "2016-07-22T00:00:00.000Z"
    }
  ],
  "nextToken": "abc123"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[album]=title,id

{
  "items": [
    {
      "id": "B0B97YW7G7",
      "title": "Periphery III: Select Difficulty"
    }
  ],
  "nextToken": "abc123"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Save album to library

PUT
/v2/me/albums/{id}
Authorization Scope: [music::library]
Save an album to the calling user's library by id. Idempotent — saving an album already in the library is a no-op that still returns 200 with the album. The declared 404 is returned only when the id does not resolve to a catalog album. Requires the `music::library` scope.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

album._type
string
Discriminator value identifying this entity as an Album
album.id
string
Unique album identifier
album.title
string
Album title
album.shortTitle
string
Short title of the album
album.audioQualities
array
Audio qualities available for this Album (SD is available by default)
album.audioQualities[]
enum (SD|HD|UHD|ATMOS|360RA)
album.globalAsin
string
Global unique identifier for the album
album.duration
number
Album duration in seconds
album.releaseDate
string
Date this album was released
album.label
string
Label associated with this album
album.trackCount
integer
Number of tracks in the album
album.url
string [format=uri]
URL into AmazonMusic for this album

Example (default)

Saved album

{
  "album": {
    "id": "B0B97YW7G7",
    "title": "Periphery III: Select Difficulty",
    "releaseDate": "2016-07-22T00:00:00.000Z"
  }
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Album not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Album not found",
    "traceId": "1-abc-def"
  }
}

Remove album from library

DELETE
/v2/me/albums/{id}
Authorization Scope: [music::library]
Remove an album from the calling user's library by id. Idempotent — removing an album that is not in the library is a no-op that still returns 200. The declared 404 is returned only when the id does not resolve to a catalog album. Requires the `music::library` scope.

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Response 200

Successful response

Response Schema

album._type
string
Discriminator value identifying this entity as an Album
album.id
string
Unique album identifier
album.title
string
Album title
album.shortTitle
string
Short title of the album
album.audioQualities
array
Audio qualities available for this Album (SD is available by default)
album.audioQualities[]
enum (SD|HD|UHD|ATMOS|360RA)
album.globalAsin
string
Global unique identifier for the album
album.duration
number
Album duration in seconds
album.releaseDate
string
Date this album was released
album.label
string
Label associated with this album
album.trackCount
integer
Number of tracks in the album
album.url
string [format=uri]
URL into AmazonMusic for this album

Example (default)

Removed album

{
  "album": {
    "id": "B0B97YW7G7",
    "title": "Periphery III: Select Difficulty",
    "releaseDate": "2016-07-22T00:00:00.000Z"
  }
}

Error Responses

Response Code Status Message
404 NOT_FOUND 404 Album not found

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Album not found",
    "traceId": "1-abc-def"
  }
}
Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us