> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# spotify-catalog
> Spotify Catalog - search, browse, and manage albums, artists, tracks, playlists, shows, and audiobooks
**Server path:** `/spotify-catalog` | **Type:** Application | **PCID required:** Yes
## Tools
| Tool | Description |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------- |
| [`spotify_catalog_add_items_to_playlist`](#spotify_catalog_add_items_to_playlist) | Add Items to Playlist |
| [`spotify_catalog_change_playlist_details`](#spotify_catalog_change_playlist_details) | Change Playlist Details |
| [`spotify_catalog_get_a_chapter`](#spotify_catalog_get_a_chapter) | Get a Chapter |
| [`spotify_catalog_get_a_show`](#spotify_catalog_get_a_show) | Get Show |
| [`spotify_catalog_get_a_shows_episodes`](#spotify_catalog_get_a_shows_episodes) | Get Show Episodes |
| [`spotify_catalog_get_an_album`](#spotify_catalog_get_an_album) | Get Album |
| [`spotify_catalog_get_an_albums_tracks`](#spotify_catalog_get_an_albums_tracks) | Get Album Tracks |
| [`spotify_catalog_get_an_artist`](#spotify_catalog_get_an_artist) | Get Artist |
| [`spotify_catalog_get_an_artists_albums`](#spotify_catalog_get_an_artists_albums) | Get Artist's Albums |
| [`spotify_catalog_get_an_audiobook`](#spotify_catalog_get_an_audiobook) | Get an Audiobook |
| [`spotify_catalog_get_an_episode`](#spotify_catalog_get_an_episode) | Get Episode |
| [`spotify_catalog_get_audiobook_chapters`](#spotify_catalog_get_audiobook_chapters) | Get Audiobook Chapters |
| [`spotify_catalog_get_playlist`](#spotify_catalog_get_playlist) | Get Playlist |
| [`spotify_catalog_get_playlist_cover`](#spotify_catalog_get_playlist_cover) | Get Playlist Cover Image |
| [`spotify_catalog_get_playlists_items`](#spotify_catalog_get_playlists_items) | Get Playlist Items |
| [`spotify_catalog_get_track`](#spotify_catalog_get_track) | Get Track |
| [`spotify_catalog_remove_items_playlist`](#spotify_catalog_remove_items_playlist) | Remove Playlist Items |
| [`spotify_catalog_reorder_or_replace_playlists_items`](#spotify_catalog_reorder_or_replace_playlists_items) | Update Playlist Items |
| [`spotify_catalog_search`](#spotify_catalog_search) | Search for Item |
| [`spotify_catalog_upload_custom_playlist_cover`](#spotify_catalog_upload_custom_playlist_cover) | Add Custom Playlist Cover Image |
***
## spotify\_catalog\_add\_items\_to\_playlist
Add Items to Playlist
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `position` | integer | No | — | The position to insert the items, a zero-based index. For example, to insert the items in the first position: `position=0`; to insert the items in the third position: `position=2`. If omitted, the items will be appended to the playlist. Items are added in the order they are listed in the query string or request body. |
| `uris` | string | No | — | A comma-separated list of Spotify URIs to add, can be track or episode URIs. For example:\
`uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ`\
A maximum of 100 items can be added in one request. \
***Note**: it is likely that passing a large number of item URIs as a query parameter will exceed the maximum length of the request URI. When adding a large number of items, it is recommended to pass them in the request body, see below.* |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"position": {
"type": "integer",
"description": "The position to insert the items, a zero-based index. For example, to insert the items in the first position: `position=0`; to insert the items in the third position: `position=2`. If omitted, the items will be appended to the playlist. Items are added in the order they are listed in the query string or request body."
},
"uris": {
"type": "string",
"description": "A comma-separated list of [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids) to add, can be track or episode URIs. For example:
`uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ`
A maximum of 100 items can be added in one request.
_**Note**: it is likely that passing a large number of item URIs as a query parameter will exceed the maximum length of the request URI. When adding a large number of items, it is recommended to pass them in the request body, see below._"
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_change\_playlist\_details
Change Playlist Details
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `collaborative` | boolean | No | — | If `true`, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. \
***Note**: You can only set `collaborative` to `true` on non-public playlists.* |
| `description` | string | No | — | Value for playlist description as displayed in Spotify Clients and in the Web API. |
| `name` | string | No | — | The new name for the playlist, for example `"My New Playlist Title"` |
| `public` | boolean | No | — | The playlist's public/private status (if it should be added to the user's profile or not): `true` the playlist will be public, `false` the playlist will be private, `null` the playlist status is not relevant. For more about public/private status, see Working with Playlists |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"collaborative": {
"type": "boolean",
"description": "If `true`, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client.
_**Note**: You can only set `collaborative` to `true` on non-public playlists._"
},
"description": {
"type": "string",
"description": "Value for playlist description as displayed in Spotify Clients and in the Web API."
},
"name": {
"type": "string",
"description": "The new name for the playlist, for example `\"My New Playlist Title\"`"
},
"public": {
"type": "boolean",
"description": "The playlist's public/private status (if it should be added to the user's profile or not): `true` the playlist will be public, `false` the playlist will be private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](/documentation/web-api/concepts/playlists)"
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_get\_a\_chapter
Get a Chapter
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the chapter. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the chapter."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_a\_show
Get Show
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `id` | string | Yes | — | The Spotify ID for the show. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the show."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_a\_shows\_episodes
Get Show Episodes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the show. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `limit` | integer | No | — | The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. |
| `offset` | integer | No | — | The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the show."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"limit": {
"type": "integer",
"description": "The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50."
},
"offset": {
"type": "integer",
"description": "The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_album
Get Album
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID of the album. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the album."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_albums\_tracks
Get Album Tracks
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID of the album. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `limit` | integer | No | — | The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. |
| `offset` | integer | No | — | The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the album."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"limit": {
"type": "integer",
"description": "The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50."
},
"offset": {
"type": "integer",
"description": "The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_artist
Get Artist
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------- |
| `id` | string | Yes | — | The Spotify ID of the artist. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the artist."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_artists\_albums
Get Artist's Albums
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID of the artist. |
| `include_groups` | string | No | — | A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned. \
Valid values are:\
- `album`\
- `single`\
- `appears_on`\
- `compilation`\
For example: `include_groups=album,single`. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `limit` | integer | No | — | The maximum number of items to return. Default: 5. Minimum: 1. Maximum: 10. |
| `offset` | integer | No | — | The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the artist."
},
"include_groups": {
"type": "string",
"description": "A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned.
Valid values are:
- `album`
- `single`
- `appears_on`
- `compilation`
For example: `include_groups=album,single`."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"limit": {
"type": "integer",
"description": "The maximum number of items to return. Default: 5. Minimum: 1. Maximum: 10."
},
"offset": {
"type": "integer",
"description": "The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_audiobook
Get an Audiobook
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the audiobook. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the audiobook."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_an\_episode
Get Episode
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the episode. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the episode."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_audiobook\_chapters
Get Audiobook Chapters
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the audiobook. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `limit` | integer | No | — | The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. |
| `offset` | integer | No | — | The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the audiobook."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"limit": {
"type": "integer",
"description": "The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50."
},
"offset": {
"type": "integer",
"description": "The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_get\_playlist
Get Playlist
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `fields` | string | No | — | Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist''s description and URI: `fields=description,uri`. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: `fields=tracks.items(added_at,added_by.id)`. Use multiple parentheses to drill down into nested objects, for example: `fields=tracks.items(track(name,href,album(name,href)))`. Fields can be excluded by prefixing them with an exclamation mark, for example: `fields=tracks.items(track(name,href,album(!name,href)))` |
| `additional_types` | string | No | — | A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`.\
***Note**: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future.*\
In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"fields": {
"type": "string",
"description": "Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist''s description and URI: `fields=description,uri`. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: `fields=tracks.items(added_at,added_by.id)`. Use multiple parentheses to drill down into nested objects, for example: `fields=tracks.items(track(name,href,album(name,href)))`. Fields can be excluded by prefixing them with an exclamation mark, for example: `fields=tracks.items(track(name,href,album(!name,href)))`"
},
"additional_types": {
"type": "string",
"description": "A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`.
_**Note**: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future._
In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object."
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_get\_playlist\_cover
Get Playlist Cover Image
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ------------------------------- |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_get\_playlists\_items
Get Playlist Items
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `fields` | string | No | — | Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit:\
`fields=total,limit`\
A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder:\
`fields=items(added_at,added_by.id)`\
Use multiple parentheses to drill down into nested objects, for example:\
`fields=items(track(name,href,album(name,href)))`\
Fields can be excluded by prefixing them with an exclamation mark, for example:\
`fields=items.track.album(!external_urls,images)` |
| `limit` | integer | No | — | The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. |
| `offset` | integer | No | — | The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items. |
| `additional_types` | string | No | — | A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`.\
***Note**: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future.*\
In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"fields": {
"type": "string",
"description": "Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit:
`fields=total,limit`
A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder:
`fields=items(added_at,added_by.id)`
Use multiple parentheses to drill down into nested objects, for example:
`fields=items(track(name,href,album(name,href)))`
Fields can be excluded by prefixing them with an exclamation mark, for example:
`fields=items.track.album(!external_urls,images)`"
},
"limit": {
"type": "integer",
"description": "The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50."
},
"offset": {
"type": "integer",
"description": "The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items."
},
"additional_types": {
"type": "string",
"description": "A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`.
_**Note**: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future._
In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object."
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_get\_track
Get Track
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | — | The Spotify ID for the track. |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the track."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## spotify\_catalog\_remove\_items\_playlist
Remove Playlist Items
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `items` | object\[] | Yes | — | An array of objects containing Spotify URIs of the tracks or episodes to remove. For example: `{ "items": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }`. A maximum of 100 objects can be sent at once. |
| `snapshot_id` | string | No | — | The playlist's snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Spotify URI"
}
}
},
"description": "An array of objects containing [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids) of the tracks or episodes to remove. For example: `{ \"items\": [{ \"uri\": \"spotify:track:4iV5W9uYEdYUVa79Axb7Rh\" },{ \"uri\": \"spotify:track:1301WleyT98MSxVHPZCA6M\" }] }`. A maximum of 100 objects can be sent at once."
},
"snapshot_id": {
"type": "string",
"description": "The playlist's snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist."
}
},
"required": [
"PCID",
"playlist_id",
"items"
]
}
```
***
## spotify\_catalog\_reorder\_or\_replace\_playlists\_items
Update Playlist Items
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `uris` | string | No | — | A comma-separated list of Spotify URIs to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ`\
A maximum of 100 items can be set in one request. |
| `insert_before` | integer | No | — | The position where the items should be inserted.\
To reorder the items to the end of the playlist, simply set *insert\_before* to the position after the last item.\
Examples:\
To reorder the first item to the last position in a playlist with 10 items, set *range\_start* to 0, and *insert\_before* to 10.\
To reorder the last item in a playlist with 10 items to the start of the playlist, set *range\_start* to 9, and *insert\_before* to 0. |
| `range_length` | integer | No | — | The amount of items to be reordered. Defaults to 1 if not set.\
The range of items to be reordered begins from the *range\_start* position, and includes the *range\_length* subsequent items.\
Example:\
To move the items at index 9-10 to the start of the playlist, *range\_start* is set to 9, and *range\_length* is set to 2. |
| `range_start` | integer | No | — | The position of the first item to be reordered. |
| `snapshot_id` | string | No | — | The playlist's snapshot ID against which you want to make the changes. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"uris": {
"type": "string",
"description": "A comma-separated list of [Spotify URIs](/documentation/web-api/concepts/spotify-uris-ids) to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ`
A maximum of 100 items can be set in one request."
},
"insert_before": {
"type": "integer",
"description": "The position where the items should be inserted.
To reorder the items to the end of the playlist, simply set _insert_before_ to the position after the last item.
Examples:
To reorder the first item to the last position in a playlist with 10 items, set _range_start_ to 0, and _insert_before_ to 10.
To reorder the last item in a playlist with 10 items to the start of the playlist, set _range_start_ to 9, and _insert_before_ to 0."
},
"range_length": {
"type": "integer",
"description": "The amount of items to be reordered. Defaults to 1 if not set.
The range of items to be reordered begins from the _range_start_ position, and includes the _range_length_ subsequent items.
Example:
To move the items at index 9-10 to the start of the playlist, _range_start_ is set to 9, and _range_length_ is set to 2."
},
"range_start": {
"type": "integer",
"description": "The position of the first item to be reordered."
},
"snapshot_id": {
"type": "string",
"description": "The playlist's snapshot ID against which you want to make the changes."
}
},
"required": [
"PCID",
"playlist_id"
]
}
```
***
## spotify\_catalog\_search
Search for Item
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | string | Yes | — | Your search query. You can narrow down your search using field filters. The available filters are `album`, `artist`, `track`, `year`, `upc`, `tag:hipster`, `tag:new`, `isrc`, and `genre`. Each field filter only applies to certain result types. The `artist` and `year` filters can be used while searching albums, artists and tracks. You can filter on a single `year` or a range (e.g. 1955-1960).\
The `album` filter can be used while searching albums and tracks.\
The `genre` filter can be used while searching artists and tracks.\
The `isrc` and `track` filters can be used while searching tracks.\
The `upc`, `tag:new` and `tag:hipster` filters can only be used while searching albums. The `tag:new` filter will return albums released in the past two weeks and `tag:hipster` can be used to return only albums with the lowest 10% popularity.\
|
| `type` | string\[] | Yes | — | A comma-separated list of item types to search across. Search results include hits from all the specified item types. For example: `q=abacab&type=album,track` returns both albums and tracks matching "abacab". |
| `market` | string | No | — | An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.\
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.\
***Note**: If neither market or user country are provided, the content is considered unavailable for the client.*\
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/). |
| `limit` | integer | No | — | The maximum number of results to return in each item type. |
| `offset` | integer | No | — | The index of the first result to return. Use with limit to get the next page of search results. |
| `include_external` | string | No | — | If `include_external=audio` is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"q": {
"type": "string",
"description": "Your search query. You can narrow down your search using field filters. The available filters are `album`, `artist`, `track`, `year`, `upc`, `tag:hipster`, `tag:new`, `isrc`, and `genre`. Each field filter only applies to certain result types. The `artist` and `year` filters can be used while searching albums, artists and tracks. You can filter on a single `year` or a range (e.g. 1955-1960).
The `album` filter can be used while searching albums and tracks.
The `genre` filter can be used while searching artists and tracks.
The `isrc` and `track` filters can be used while searching tracks.
The `upc`, `tag:new` and `tag:hipster` filters can only be used while searching albums. The `tag:new` filter will return albums released in the past two weeks and `tag:hipster` can be used to return only albums with the lowest 10% popularity.
"
},
"type": {
"type": "array",
"items": {
"type": "string",
"enum": [
"album",
"artist",
"playlist",
"track",
"show",
"episode",
"audiobook"
]
},
"description": "A comma-separated list of item types to search across. Search results include hits from all the specified item types. For example: `q=abacab&type=album,track` returns both albums and tracks matching \"abacab\"."
},
"market": {
"type": "string",
"description": "An [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
_**Note**: If neither market or user country are provided, the content is considered unavailable for the client._
Users can view the country that is associated with their account in the [account settings](https://www.spotify.com/account/overview/)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in each item type."
},
"offset": {
"type": "integer",
"description": "The index of the first result to return. Use with limit to get the next page of search results."
},
"include_external": {
"type": "string",
"description": "If `include_external=audio` is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response.",
"enum": [
"audio"
]
}
},
"required": [
"PCID",
"q",
"type"
]
}
```
***
## spotify\_catalog\_upload\_custom\_playlist\_cover
Add Custom Playlist Cover Image
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | --------------------------------------------------------------- |
| `playlist_id` | string | Yes | — | The Spotify ID of the playlist. |
| `body` | string | No | — | Base64 encoded JPEG image data, maximum payload size is 256 KB. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"playlist_id": {
"type": "string",
"description": "The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) of the playlist."
},
"body": {
"type": "string",
"description": "Base64 encoded JPEG image data, maximum payload size is 256 KB."
}
},
"required": [
"PCID",
"playlist_id"
]
}
```