Amazon Music Web API

Web API Playlists V2.0

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.

Playlists

Get multiple playlists
Create a playlist
Delete multiple playlists (deprecated)
Get top playlists
Get playlist by ID
Update a playlist
Delete a playlist
Get playlist cover images
Get tracks in a playlist
Add tracks to a playlist
Reorder tracks in a playlist
Remove tracks from a playlist

Get multiple playlists

GET

/v2/playlists

Authorization Scope: [music::catalog]

Retrieve information for multiple playlists identified by their AmazonMusic IDs. Pass a comma-separated list of playlist IDs via the `ids` query parameter; maximum 100 IDs per request. IDs that cannot be resolved are omitted from the response.

Query Parameters

Name	Data Type	Required	Description
ids	string[]	Yes	Comma-separated list of playlist IDs (max 100)

Response 200

Successful response

Response Schema

(array)

Playlist[]

List of requested playlists

Example

[
  {
    "id": "B0EXAMP100",
    "title": "Indie Rock Essentials",
    "description": "Editorial mix of indie rock standouts.",
    "visibility": "PUBLIC",
    "trackCount": 42,
    "duration": 9240,
    "url": "https://music.amazon.com/playlists/B0EXAMP100",
    "owner": {
      "id": "B0EXAMP200",
      "name": "Amazon Music Editorial"
    },
    "images": [
      {
        "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg",
        "width": 640,
        "height": 640,
        "imageType": "PRIMARY"
      }
    ],
    "parentalSettings": {
      "hasExplicitLanguage": false
    }
  },
  {
    "id": "B0EXAMP101",
    "title": "Rock Deep Cuts",
    "description": "Lesser-known tracks from rock mainstays.",
    "visibility": "PUBLIC",
    "trackCount": 36,
    "duration": 8100,
    "url": "https://music.amazon.com/playlists/B0EXAMP101",
    "owner": {
      "id": "B0EXAMP200",
      "name": "Amazon Music Editorial"
    },
    "images": [
      {
        "url": "https://m.media-amazon.com/images/I/B0EXAMP101-640.jpg",
        "width": 640,
        "height": 640,
        "imageType": "PRIMARY"
      }
    ],
    "parentalSettings": {
      "hasExplicitLanguage": false
    }
  }
]

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	ids parameter is required and must contain 1-100 comma-separated IDs

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "ids parameter is required and must contain 1-100 comma-separated IDs",
    "traceId": "1-abc-def"
  }
}

Create a playlist

POST

/v2/playlists

Authorization Scope: [music::library]

Create a new playlist for the calling user. `title` is required; `description`, `visibility` (defaults to `PRIVATE`), and an optional `trackAsins` seed list may be provided. Returns the newly created playlist.

Request Body

Request Schema

title

string [minLength=1]

Title for the new playlist

description

string

Description for the new playlist

visibility

PlaylistVisibility

trackAsins

array

Optional list of track ASINs to seed the playlist with

trackAsins[]

string

Request Example

{
  "title": "Indie Rock Essentials",
  "description": "Editorial mix of indie rock standouts.",
  "visibility": "PUBLIC",
  "trackAsins": [
    "B084KPC3Q7",
    "B004S8NBPG"
  ]
}

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.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.

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "description": "Editorial mix of indie rock standouts.",
  "visibility": "PUBLIC",
  "trackCount": 2,
  "duration": 403,
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	title is required

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "title is required",
    "traceId": "1-abc-def"
  }
}

Delete multiple playlists (deprecated)

DELETE

/v2/playlists

Authorization Scope: [music::library]

Delete one or more playlists owned by the calling user.

Deprecated. Use DeletePlaylist (DELETE /v2/playlists/{id}) to remove a single playlist instead.

Request Body

Request Schema

ids

array

Playlist IDs to delete

ids[]

string

Request Example

{
  "ids": [
    "B0EXAMP100",
    "B0EXAMP101"
  ]
}

Response 200

Successful response

Response Schema

deletedPlaylists

array

IDs of playlists that were successfully deleted

deletedPlaylists[]

string

Example

{
  "deletedPlaylists": [
    "B0EXAMP100",
    "B0EXAMP101"
  ]
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	ids is required and must contain at least 1 playlist ID

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "ids is required and must contain at least 1 playlist ID",
    "traceId": "1-abc-def"
  }
}

Get top playlists

GET

/v2/playlists/top

Authorization Scope: [music::catalog]

Retrieve a list of top AmazonMusic playlists, ordered by popularity.

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
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

Top playlists with full Playlist fields populated

{
  "items": [
    {
      "id": "B0EXAMP100",
      "title": "Indie Rock Essentials",
      "description": "Editorial mix of indie rock standouts.",
      "visibility": "PUBLIC",
      "trackCount": 42,
      "duration": 9240,
      "url": "https://music.amazon.com/playlists/B0EXAMP100",
      "owner": {
        "id": "B0EXAMP200",
        "name": "Amazon Music Editorial"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B0EXAMP101",
      "title": "Rock Deep Cuts",
      "description": "Lesser-known tracks from rock mainstays.",
      "visibility": "PUBLIC",
      "trackCount": 36,
      "duration": 8100,
      "url": "https://music.amazon.com/playlists/B0EXAMP101",
      "owner": {
        "id": "B0EXAMP200",
        "name": "Amazon Music Editorial"
      },
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP101-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP250"
}

Sparse Fieldsets Example

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

{
  "items": [
    {
      "id": "B0EXAMP100",
      "title": "Indie Rock Essentials",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg"
        }
      ]
    },
    {
      "id": "B0EXAMP101",
      "title": "Rock Deep Cuts",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP101-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP250"
}

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 playlist by ID

GET

/v2/playlists/{id}

Authorization Scope: [music::catalog]

Retrieve detailed information about a specific playlist, including owner, cover images, and the first page of tracks.

Supports sparse fieldsets via query parameters:

fields[playlist] — Comma-separated playlist fields (e.g. title,id,tracks)
fields[image] — Comma-separated image fields (e.g. url)
fields[user] — Comma-separated owner fields (e.g. name)

Path Parameters

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

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.countryCode

string

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

Full playlist response with owner, images, and first page of tracks

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "description": "Editorial mix of indie rock standouts.",
  "visibility": "PUBLIC",
  "trackCount": 42,
  "duration": 9240,
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  },
  "images": [
    {
      "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg",
      "width": 640,
      "height": 640,
      "imageType": "PRIMARY"
    }
  ],
  "parentalSettings": {
    "hasExplicitLanguage": false
  },
  "tracks": {
    "items": [
      {
        "id": "B084KPC3Q7",
        "title": "Selfless",
        "duration": 222
      },
      {
        "id": "B004S8NBPG",
        "title": "Metabolism",
        "duration": 181
      }
    ],
    "nextToken": "B0EXAMP410"
  }
}

Sparse Fieldsets Example

Sparse fieldsets — fields[playlist]=title,id,owner&fields[user]=name

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	Invalid field 'nonexistent' for type 'playlist'
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid field 'nonexistent' for type 'playlist'",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Update a playlist

PATCH

/v2/playlists/{id}

Authorization Scope: [music::library]

Partially update an owned playlist. Omitted fields are left unchanged; at least one of `title`, `description`, or `visibility` must be provided. Returns the updated playlist.

Path Parameters

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

Request Body

Request Schema

title

string

New playlist title

description

string

New playlist description

visibility

PlaylistVisibility

Request Example

{
  "title": "Indie Rock Essentials (Updated)",
  "description": "Refreshed editorial mix of indie rock standouts.",
  "visibility": "PRIVATE"
}

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.countryCode

string

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials (Updated)",
  "description": "Refreshed editorial mix of indie rock standouts.",
  "visibility": "PRIVATE",
  "trackCount": 42,
  "duration": 9240,
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	At least one of title, description, or visibility must be provided
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "At least one of title, description, or visibility must be provided",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Delete a playlist

DELETE

/v2/playlists/{id}

Authorization Scope: [music::library]

Delete a playlist owned by the calling user. The caller must own the playlist; attempting to delete a playlist owned by another user is rejected. Returns the deleted playlist id and an `isDeleted` confirmation flag.

Path Parameters

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

Response 200

Successful response

Response Schema

string

Unique playlist identifier

isDeleted

boolean

Whether the playlist was successfully deleted

Example

{
  "id": "B0EXAMP100",
  "isDeleted": true
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	id path parameter is required
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "id path parameter is required",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Get playlist cover images

GET

/v2/playlists/{id}/images

Authorization Scope: [music::catalog]

Retrieve the cover images for the given playlist. Each image is returned with its URL, pixel dimensions (`width`, `height`), and `imageType`, so clients can select the best size for the target surface.

Path Parameters

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

Response 200

Successful response

Response Schema

string

Unique playlist identifier

images

Image[]

Cover images for this playlist

Example

{
  "id": "B0EXAMP100",
  "images": [
    {
      "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg",
      "width": 640,
      "height": 640,
      "imageType": "PRIMARY"
    }
  ]
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	id path parameter is required
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "id path parameter is required",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Get tracks in a playlist

GET

/v2/playlists/{id}/tracks

Authorization Scope: [music::catalog]

Retrieve the paginated list of tracks in the given playlist, in playlist order.

Each item carries an entryId identifying that track's entry (slot) in the playlist, alongside the track's own id. The two differ: adding the same track twice produces two entries with distinct entryId values. Pass entryId values — not track IDs — to the endpoints that remove or reorder playlist entries.

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,album)
fields[album] — Comma-separated album fields (e.g. title,id)
fields[artist] — Comma-separated artist fields (e.g. name)

Path Parameters

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

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

PlaylistTrack[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Tracks for playlist B0EXAMP100 with full PlaylistTrack fields populated

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "entryId": "fd5c53f7-1673-4f6b-9556-be9b59e2bb59",
      "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",
      "entryId": "9b1c0a54-2f83-4d17-8c6e-71a5d3e0b842",
      "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": "B0EXAMP410"
}

Sparse Fieldsets Example

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

{
  "items": [
    {
      "id": "B084KPC3Q7",
      "entryId": "fd5c53f7-1673-4f6b-9556-be9b59e2bb59",
      "title": "Selfless",
      "duration": 222,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    },
    {
      "id": "B004S8NBPG",
      "entryId": "9b1c0a54-2f83-4d17-8c6e-71a5d3e0b842",
      "title": "Metabolism",
      "duration": 181,
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP410"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	first parameter must be between 1 and 100
404	NOT_FOUND	404	Playlist not found

400 Example

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

404 Example

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

Add tracks to a playlist

POST

/v2/playlists/{id}/tracks

Authorization Scope: [music::library]

Append one or more tracks to the given playlist. By default, tracks already present in the playlist are skipped; set `addDuplicateTracks: true` to allow duplicates.

Path Parameters

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

Request Body

Request Schema

trackIds

array

Track IDs (ASINs) to append to the playlist

trackIds[]

string

addDuplicateTracks

boolean [default=false]

When true, allow adding tracks already present in the playlist

Request Example

{
  "trackIds": [
    "B084KPC3Q7",
    "B004S8NBPG"
  ],
  "addDuplicateTracks": true
}

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.countryCode

string

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "trackCount": 44,
  "duration": 9643,
  "visibility": "PUBLIC",
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	trackIds is required and must contain at least 1 track ID
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "trackIds is required and must contain at least 1 track ID",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Reorder tracks in a playlist

PATCH

/v2/playlists/{id}/tracks

Authorization Scope: [music::library]

Move one or more tracks to a new position in the given playlist. Specify a target anchor with either `entryIdAbove` or `entryIdBelow` (exactly one).

Path Parameters

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

Request Body

Request Schema

entryIds

array

Playlist entry IDs to move

entryIds[]

string

entryIdAbove

string

Entry ID that ends up immediately *above* the moved entries — they are placed in the slot directly after it.

entryIdBelow

string

Entry ID that ends up immediately *below* the moved entries — they are placed in the slot directly before it.

Request Example (moveAbove)

Move selected entries above an anchor

{
  "entryIds": [
    "fd5c53f7-1673-4f6b-9556-be9b59e2bb59",
    "9b1c0a54-2f83-4d17-8c6e-71a5d3e0b842"
  ],
  "entryIdAbove": "3e7f8d21-64b9-4a05-9f13-c2d80ae5761b"
}

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.countryCode

string

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "trackCount": 42,
  "duration": 9240,
  "visibility": "PUBLIC",
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	Exactly one of entryIdAbove or entryIdBelow must be provided
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Exactly one of entryIdAbove or entryIdBelow must be provided",
    "traceId": "1-abc-def"
  }
}

404 Example

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

Remove tracks from a playlist

POST

/v2/playlists/{id}/tracks/delete

Authorization Scope: [music::library]

Remove one or more tracks from the given playlist, identified by playlist entry IDs.

Modeled as a POST action endpoint rather than DELETE with a request body because RFC 7231 §4.3.5 leaves DELETE-body semantics undefined and some HTTP clients, proxies, and API gateways silently strip bodies on DELETE requests.

Path Parameters

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

Request Body

Request Schema

entryIds

array

Playlist entry IDs to remove

entryIds[]

string

Request Example

{
  "entryIds": [
    "fd5c53f7-1673-4f6b-9556-be9b59e2bb59",
    "9b1c0a54-2f83-4d17-8c6e-71a5d3e0b842"
  ]
}

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a Playlist

string

Unique playlist identifier

title

string

Playlist title

description

string

Playlist description

visibility

PlaylistVisibility

trackCount

integer

Number of tracks in the playlist

duration

number

Total duration of all tracks in seconds

url

string [format=uri]

URL into AmazonMusic for this playlist

owner._type

string

Discriminator value identifying this entity as a User

owner.id

string

Unique user identifier

owner.name

string

Display name of the user

owner.handle

string

Public handle (username) chosen by the user

owner.url

string [format=uri]

URL into AmazonMusic for this user profile

owner.visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

owner.playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

owner.countryCode

string

owner.tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

owner.images

Image[]

Avatar images for this user

images

Image[]

Cover images for this playlist

tracks

BaseTrack[]

Tracks in this playlist (paginated)

Example

{
  "id": "B0EXAMP100",
  "title": "Indie Rock Essentials",
  "trackCount": 40,
  "duration": 8837,
  "visibility": "PUBLIC",
  "url": "https://music.amazon.com/playlists/B0EXAMP100",
  "owner": {
    "id": "B0EXAMP200",
    "name": "Amazon Music Editorial"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	entryIds is required and must contain at least 1 entry ID
404	NOT_FOUND	404	Playlist not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "entryIds is required and must contain at least 1 entry ID",
    "traceId": "1-abc-def"
  }
}

404 Example

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