> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/tools/spotify.md).

# spotify

### Usage Instructions

Integrate Spotify into your workflow. Search for tracks, albums, artists, and playlists. Manage playlists, access your library, control playback, browse podcasts and audiobooks.

### Tools

#### `spotify_search`

Search for tracks, albums, artists, or playlists on Spotify. Returns matching results based on the query.

**Input**

| Parameter | Type   | Required | Description                                                                                |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `query`   | string | Yes      | Search query (e.g., "Bohemian Rhapsody", "artist:Queen", "genre:rock")                     |
| `type`    | string | No       | Type of results: track, album, artist, playlist, or comma-separated (e.g., "track,artist") |
| `limit`   | number | No       | Maximum number of results to return (1-50)                                                 |
| `offset`  | number | No       | Index of the first result to return for pagination                                         |
| `market`  | string | No       | ISO 3166-1 alpha-2 country code to filter results (e.g., "US", "GB")                       |

**Output**

| Parameter | Type  | Description             |
| --------- | ----- | ----------------------- |
| `tracks`  | array | List of matching tracks |

#### `spotify_get_track`

Get detailed information about a specific track on Spotify by its ID.

**Input**

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `trackId` | string | Yes      | The Spotify ID of the track                            |
| `market`  | string | No       | ISO 3166-1 alpha-2 country code for track availability |

**Output**

| Parameter      | Type    | Description                            |
| -------------- | ------- | -------------------------------------- |
| `id`           | string  | Spotify track ID                       |
| `name`         | string  | Track name                             |
| `artists`      | array   | List of artists                        |
| `album`        | object  | Album information                      |
| `duration_ms`  | number  | Track duration in milliseconds         |
| `explicit`     | boolean | Whether the track has explicit content |
| `popularity`   | number  | Popularity score (0-100)               |
| `preview_url`  | string  | URL to 30-second preview               |
| `external_url` | string  | Spotify URL                            |
| `uri`          | string  | Spotify URI for the track              |

#### `spotify_get_tracks`

Get detailed information about multiple tracks on Spotify by their IDs (up to 50).

**Input**

| Parameter  | Type   | Required | Description                                            |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| `trackIds` | string | Yes      | Comma-separated list of Spotify track IDs (max 50)     |
| `market`   | string | No       | ISO 3166-1 alpha-2 country code for track availability |

**Output**

| Parameter | Type  | Description    |
| --------- | ----- | -------------- |
| `tracks`  | array | List of tracks |

#### `spotify_get_album`

Get detailed information about an album on Spotify by its ID, including track listing.

**Input**

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `albumId` | string | Yes      | The Spotify ID of the album                            |
| `market`  | string | No       | ISO 3166-1 alpha-2 country code for track availability |

**Output**

| Parameter      | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `id`           | string | Spotify album ID                           |
| `name`         | string | Album name                                 |
| `artists`      | array  | List of artists                            |
| `album_type`   | string | Type of album (album, single, compilation) |
| `total_tracks` | number | Total number of tracks                     |
| `release_date` | string | Release date                               |
| `label`        | string | Record label                               |
| `popularity`   | number | Popularity score (0-100)                   |
| `genres`       | array  | List of genres                             |
| `image_url`    | string | Album cover image URL                      |
| `tracks`       | array  | List of tracks on the album                |
| `external_url` | string | Spotify URL                                |

#### `spotify_get_albums`

Get details for multiple albums by their IDs.

**Input**

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `albumIds` | string | Yes      | Comma-separated album IDs (max 20) |
| `market`   | string | No       | ISO country code for market        |

**Output**

| Parameter | Type | Description    |
| --------- | ---- | -------------- |
| `albums`  | json | List of albums |

#### `spotify_get_album_tracks`

Get the tracks from an album.

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `albumId` | string | Yes      | The Spotify album ID              |
| `limit`   | number | No       | Number of tracks to return (1-50) |
| `offset`  | number | No       | Index of first track to return    |

**Output**

| Parameter | Type   | Description            |
| --------- | ------ | ---------------------- |
| `tracks`  | json   | List of tracks         |
| `total`   | number | Total number of tracks |
| `next`    | string | URL for next page      |

#### `spotify_get_saved_albums`

Get the user

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `limit`   | number | No       | Number of albums to return (1-50) |
| `offset`  | number | No       | Index of first album to return    |
| `market`  | string | No       | ISO country code for market       |

**Output**

| Parameter | Type   | Description          |
| --------- | ------ | -------------------- |
| `albums`  | json   | List of saved albums |
| `total`   | number | Total saved albums   |
| `next`    | string | URL for next page    |

#### `spotify_save_albums`

Save albums to the user

**Input**

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `albumIds` | string | Yes      | Comma-separated album IDs (max 20) |

**Output**

| Parameter | Type    | Description               |
| --------- | ------- | ------------------------- |
| `success` | boolean | Whether albums were saved |

#### `spotify_remove_saved_albums`

Remove albums from the user

**Input**

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `albumIds` | string | Yes      | Comma-separated album IDs (max 20) |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether albums were removed |

#### `spotify_check_saved_albums`

Check if albums are saved in library.

**Input**

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `albumIds` | string | Yes      | Comma-separated album IDs (max 20) |

**Output**

| Parameter | Type | Description                      |
| --------- | ---- | -------------------------------- |
| `results` | json | Array of booleans for each album |

#### `spotify_get_artist`

Get detailed information about an artist on Spotify by their ID.

**Input**

| Parameter  | Type   | Required | Description                  |
| ---------- | ------ | -------- | ---------------------------- |
| `artistId` | string | Yes      | The Spotify ID of the artist |

**Output**

| Parameter      | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `id`           | string | Spotify artist ID                         |
| `name`         | string | Artist name                               |
| `genres`       | array  | List of genres associated with the artist |
| `popularity`   | number | Popularity score (0-100)                  |
| `followers`    | number | Number of followers                       |
| `image_url`    | string | Artist image URL                          |
| `external_url` | string | Spotify URL                               |

#### `spotify_get_artists`

Get details for multiple artists by their IDs.

**Input**

| Parameter   | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `artistIds` | string | Yes      | Comma-separated artist IDs (max 50) |

**Output**

| Parameter | Type | Description     |
| --------- | ---- | --------------- |
| `artists` | json | List of artists |

#### `spotify_get_artist_albums`

Get albums by an artist on Spotify. Can filter by album type.

**Input**

| Parameter        | Type   | Required | Description                                                                     |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `artistId`       | string | Yes      | The Spotify ID of the artist                                                    |
| `include_groups` | string | No       | Filter by album type: album, single, appears\_on, compilation (comma-separated) |
| `limit`          | number | No       | Maximum number of albums to return (1-50)                                       |
| `offset`         | number | No       | Index of the first album to return                                              |
| `market`         | string | No       | ISO 3166-1 alpha-2 country code                                                 |

**Output**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `albums`  | array | Artist      |

#### `spotify_get_artist_top_tracks`

Get the top 10 most popular tracks by an artist on Spotify.

**Input**

| Parameter  | Type   | Required | Description                                                  |
| ---------- | ------ | -------- | ------------------------------------------------------------ |
| `artistId` | string | Yes      | The Spotify ID of the artist                                 |
| `market`   | string | No       | ISO 3166-1 alpha-2 country code (required for this endpoint) |

**Output**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `tracks`  | array | Artist      |

#### `spotify_follow_artists`

Follow one or more artists.

**Input**

| Parameter   | Type   | Required | Description                                   |
| ----------- | ------ | -------- | --------------------------------------------- |
| `artistIds` | string | Yes      | Comma-separated artist IDs to follow (max 50) |

**Output**

| Parameter | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `success` | boolean | Whether artists were followed successfully |

#### `spotify_unfollow_artists`

Unfollow one or more artists.

**Input**

| Parameter   | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `artistIds` | string | Yes      | Comma-separated artist IDs to unfollow (max 50) |

**Output**

| Parameter | Type    | Description                                  |
| --------- | ------- | -------------------------------------------- |
| `success` | boolean | Whether artists were unfollowed successfully |

#### `spotify_get_followed_artists`

Get the user

**Input**

| Parameter | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| `limit`   | number | No       | Number of artists to return (1-50)                           |
| `after`   | string | No       | Cursor for pagination (last artist ID from previous request) |

**Output**

| Parameter | Type   | Description                      |
| --------- | ------ | -------------------------------- |
| `artists` | json   | List of followed artists         |
| `total`   | number | Total number of followed artists |
| `next`    | string | Cursor for next page             |

#### `spotify_check_following`

Check if the user follows artists or users.

**Input**

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `type`    | string | Yes      | Type to check: "artist" or "user"           |
| `ids`     | string | Yes      | Comma-separated artist or user IDs (max 50) |

**Output**

| Parameter | Type | Description                   |
| --------- | ---- | ----------------------------- |
| `results` | json | Array of booleans for each ID |

#### `spotify_get_show`

Get details for a podcast show.

**Input**

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `showId`  | string | Yes      | The Spotify show ID         |
| `market`  | string | No       | ISO country code for market |

**Output**

| Parameter        | Type    | Description               |
| ---------------- | ------- | ------------------------- |
| `id`             | string  | Show ID                   |
| `name`           | string  | Show name                 |
| `description`    | string  | Show description          |
| `publisher`      | string  | Publisher name            |
| `total_episodes` | number  | Total episodes            |
| `explicit`       | boolean | Contains explicit content |
| `languages`      | json    | Languages                 |
| `image_url`      | string  | Cover image URL           |
| `external_url`   | string  | Spotify URL               |

#### `spotify_get_shows`

Get details for multiple podcast shows.

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `showIds` | string | Yes      | Comma-separated show IDs (max 50) |
| `market`  | string | No       | ISO country code for market       |

**Output**

| Parameter | Type | Description   |
| --------- | ---- | ------------- |
| `shows`   | json | List of shows |

#### `spotify_get_show_episodes`

Get episodes from a podcast show.

**Input**

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `showId`  | string | Yes      | The Spotify show ID                 |
| `limit`   | number | No       | Number of episodes to return (1-50) |
| `offset`  | number | No       | Index of first episode to return    |
| `market`  | string | No       | ISO country code for market         |

**Output**

| Parameter  | Type   | Description       |
| ---------- | ------ | ----------------- |
| `episodes` | json   | List of episodes  |
| `total`    | number | Total episodes    |
| `next`     | string | URL for next page |

#### `spotify_get_saved_shows`

Get the user

**Input**

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `limit`   | number | No       | Number of shows to return (1-50) |
| `offset`  | number | No       | Index of first show to return    |

**Output**

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| `shows`   | json   | List of saved shows |
| `total`   | number | Total saved shows   |
| `next`    | string | URL for next page   |

#### `spotify_save_shows`

Save podcast shows to the user

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `showIds` | string | Yes      | Comma-separated show IDs (max 50) |

**Output**

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `success` | boolean | Whether shows were saved |

#### `spotify_remove_saved_shows`

Remove podcast shows from the user

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `showIds` | string | Yes      | Comma-separated show IDs (max 50) |

**Output**

| Parameter | Type    | Description                |
| --------- | ------- | -------------------------- |
| `success` | boolean | Whether shows were removed |

#### `spotify_check_saved_shows`

Check if shows are saved in library.

**Input**

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `showIds` | string | Yes      | Comma-separated show IDs (max 50) |

**Output**

| Parameter | Type | Description                     |
| --------- | ---- | ------------------------------- |
| `results` | json | Array of booleans for each show |

#### `spotify_get_episode`

Get details for a podcast episode.

**Input**

| Parameter   | Type   | Required | Description                 |
| ----------- | ------ | -------- | --------------------------- |
| `episodeId` | string | Yes      | The Spotify episode ID      |
| `market`    | string | No       | ISO country code for market |

**Output**

| Parameter      | Type    | Description               |
| -------------- | ------- | ------------------------- |
| `id`           | string  | Episode ID                |
| `name`         | string  | Episode name              |
| `description`  | string  | Episode description       |
| `duration_ms`  | number  | Duration in ms            |
| `release_date` | string  | Release date              |
| `explicit`     | boolean | Contains explicit content |
| `show`         | json    | Parent show info          |
| `image_url`    | string  | Cover image URL           |
| `external_url` | string  | Spotify URL               |

#### `spotify_get_episodes`

Get details for multiple podcast episodes.

**Input**

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `episodeIds` | string | Yes      | Comma-separated episode IDs (max 50) |
| `market`     | string | No       | ISO country code for market          |

**Output**

| Parameter  | Type | Description      |
| ---------- | ---- | ---------------- |
| `episodes` | json | List of episodes |

#### `spotify_get_saved_episodes`

Get the user

**Input**

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `limit`   | number | No       | Number of episodes to return (1-50) |
| `offset`  | number | No       | Index of first episode to return    |
| `market`  | string | No       | ISO country code for market         |

**Output**

| Parameter  | Type   | Description            |
| ---------- | ------ | ---------------------- |
| `episodes` | json   | List of saved episodes |
| `total`    | number | Total saved episodes   |
| `next`     | string | URL for next page      |

#### `spotify_save_episodes`

Save podcast episodes to the user

**Input**

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `episodeIds` | string | Yes      | Comma-separated episode IDs (max 50) |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether episodes were saved |

#### `spotify_remove_saved_episodes`

Remove podcast episodes from the user

**Input**

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `episodeIds` | string | Yes      | Comma-separated episode IDs (max 50) |

**Output**

| Parameter | Type    | Description                   |
| --------- | ------- | ----------------------------- |
| `success` | boolean | Whether episodes were removed |

#### `spotify_check_saved_episodes`

Check if episodes are saved in library.

**Input**

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `episodeIds` | string | Yes      | Comma-separated episode IDs (max 50) |

**Output**

| Parameter | Type | Description                        |
| --------- | ---- | ---------------------------------- |
| `results` | json | Array of booleans for each episode |

#### `spotify_get_audiobook`

Get details for an audiobook.

**Input**

| Parameter     | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| `audiobookId` | string | Yes      | The Spotify audiobook ID    |
| `market`      | string | No       | ISO country code for market |

**Output**

| Parameter        | Type   | Description     |
| ---------------- | ------ | --------------- |
| `id`             | string | Audiobook ID    |
| `name`           | string | Audiobook name  |
| `authors`        | json   | Authors         |
| `narrators`      | json   | Narrators       |
| `publisher`      | string | Publisher       |
| `description`    | string | Description     |
| `total_chapters` | number | Total chapters  |
| `languages`      | json   | Languages       |
| `image_url`      | string | Cover image URL |
| `external_url`   | string | Spotify URL     |

#### `spotify_get_audiobooks`

Get details for multiple audiobooks.

**Input**

| Parameter      | Type   | Required | Description                            |
| -------------- | ------ | -------- | -------------------------------------- |
| `audiobookIds` | string | Yes      | Comma-separated audiobook IDs (max 50) |
| `market`       | string | No       | ISO country code for market            |

**Output**

| Parameter    | Type | Description        |
| ------------ | ---- | ------------------ |
| `audiobooks` | json | List of audiobooks |

#### `spotify_get_audiobook_chapters`

Get chapters from an audiobook.

**Input**

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `audiobookId` | string | Yes      | The Spotify audiobook ID            |
| `limit`       | number | No       | Number of chapters to return (1-50) |
| `offset`      | number | No       | Index of first chapter to return    |
| `market`      | string | No       | ISO country code for market         |

**Output**

| Parameter  | Type   | Description       |
| ---------- | ------ | ----------------- |
| `chapters` | json   | List of chapters  |
| `total`    | number | Total chapters    |
| `next`     | string | URL for next page |

#### `spotify_get_saved_audiobooks`

Get the user

**Input**

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `limit`   | number | No       | Number of audiobooks to return (1-50) |
| `offset`  | number | No       | Index of first audiobook to return    |

**Output**

| Parameter    | Type   | Description              |
| ------------ | ------ | ------------------------ |
| `audiobooks` | json   | List of saved audiobooks |
| `total`      | number | Total saved audiobooks   |
| `next`       | string | URL for next page        |

#### `spotify_save_audiobooks`

Save audiobooks to the user

**Input**

| Parameter      | Type   | Required | Description                            |
| -------------- | ------ | -------- | -------------------------------------- |
| `audiobookIds` | string | Yes      | Comma-separated audiobook IDs (max 50) |

**Output**

| Parameter | Type    | Description                   |
| --------- | ------- | ----------------------------- |
| `success` | boolean | Whether audiobooks were saved |

#### `spotify_remove_saved_audiobooks`

Remove audiobooks from the user

**Input**

| Parameter      | Type   | Required | Description                            |
| -------------- | ------ | -------- | -------------------------------------- |
| `audiobookIds` | string | Yes      | Comma-separated audiobook IDs (max 50) |

**Output**

| Parameter | Type    | Description                     |
| --------- | ------- | ------------------------------- |
| `success` | boolean | Whether audiobooks were removed |

#### `spotify_check_saved_audiobooks`

Check if audiobooks are saved in library.

**Input**

| Parameter      | Type   | Required | Description                            |
| -------------- | ------ | -------- | -------------------------------------- |
| `audiobookIds` | string | Yes      | Comma-separated audiobook IDs (max 50) |

**Output**

| Parameter | Type | Description                          |
| --------- | ---- | ------------------------------------ |
| `results` | json | Array of booleans for each audiobook |

#### `spotify_get_playlist`

Get detailed information about a playlist on Spotify by its ID.

**Input**

| Parameter    | Type   | Required | Description                                            |
| ------------ | ------ | -------- | ------------------------------------------------------ |
| `playlistId` | string | Yes      | The Spotify ID of the playlist                         |
| `market`     | string | No       | ISO 3166-1 alpha-2 country code for track availability |

**Output**

| Parameter       | Type    | Description                           |
| --------------- | ------- | ------------------------------------- |
| `id`            | string  | Spotify playlist ID                   |
| `name`          | string  | Playlist name                         |
| `description`   | string  | Playlist description                  |
| `public`        | boolean | Whether the playlist is public        |
| `collaborative` | boolean | Whether the playlist is collaborative |
| `owner`         | object  | Playlist owner information            |
| `image_url`     | string  | Playlist cover image URL              |
| `total_tracks`  | number  | Total number of tracks                |
| `snapshot_id`   | string  | Playlist snapshot ID for versioning   |
| `external_url`  | string  | Spotify URL                           |

#### `spotify_get_playlist_tracks`

Get the tracks in a Spotify playlist.

**Input**

| Parameter    | Type   | Required | Description                                            |
| ------------ | ------ | -------- | ------------------------------------------------------ |
| `playlistId` | string | Yes      | The Spotify ID of the playlist                         |
| `limit`      | number | No       | Maximum number of tracks to return (1-100)             |
| `offset`     | number | No       | Index of the first track to return                     |
| `market`     | string | No       | ISO 3166-1 alpha-2 country code for track availability |

**Output**

| Parameter | Type  | Description                    |
| --------- | ----- | ------------------------------ |
| `tracks`  | array | List of tracks in the playlist |

#### `spotify_get_playlist_cover`

Get a playlist

**Input**

| Parameter    | Type   | Required | Description             |
| ------------ | ------ | -------- | ----------------------- |
| `playlistId` | string | Yes      | The Spotify playlist ID |

**Output**

| Parameter | Type | Description          |
| --------- | ---- | -------------------- |
| `images`  | json | List of cover images |

#### `spotify_get_user_playlists`

Get the current user

**Input**

| Parameter | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| `limit`   | number | No       | Maximum number of playlists to return (1-50) |
| `offset`  | number | No       | Index of the first playlist to return        |

**Output**

| Parameter   | Type  | Description |
| ----------- | ----- | ----------- |
| `playlists` | array | User        |

#### `spotify_create_playlist`

Create a new playlist for the current user on Spotify.

**Input**

| Parameter       | Type    | Required | Description                                                                |
| --------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `name`          | string  | Yes      | Name for the new playlist                                                  |
| `description`   | string  | No       | Description for the playlist                                               |
| `public`        | boolean | No       | Whether the playlist should be public                                      |
| `collaborative` | boolean | No       | Whether the playlist should be collaborative (requires public to be false) |

**Output**

\| Parameter | Type | Description | | --------- | ---- | -------- | ----------- | | `id` | string | Spotify playlist ID | | `name` | string | Playlist name | | `description` | string | Playlist description | | `public` | boolean | Whether the playlist is public | | `collaborative` | boolean | Whether collaborative | | `snapshot_id` | string | Playlist snapshot ID | | `external_url` | string | Spotify URL |

#### `spotify_update_playlist`

Update a playlist

**Input**

| Parameter     | Type    | Required | Description                           |
| ------------- | ------- | -------- | ------------------------------------- |
| `playlistId`  | string  | Yes      | The Spotify playlist ID               |
| `name`        | string  | No       | New name for the playlist             |
| `description` | string  | No       | New description for the playlist      |
| `public`      | boolean | No       | Whether the playlist should be public |

**Output**

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `success` | boolean | Whether update succeeded |

#### `spotify_add_playlist_cover`

Upload a custom cover image for a playlist. Image must be JPEG and under 256KB.

**Input**

| Parameter     | Type   | Required | Description                           |
| ------------- | ------ | -------- | ------------------------------------- |
| `playlistId`  | string | Yes      | The Spotify playlist ID               |
| `imageBase64` | string | Yes      | Base64-encoded JPEG image (max 256KB) |

**Output**

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `success` | boolean | Whether upload succeeded |

#### `spotify_add_tracks_to_playlist`

Add one or more tracks to a Spotify playlist.

**Input**

| Parameter    | Type   | Required | Description                                                                |
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `playlistId` | string | Yes      | The Spotify ID of the playlist                                             |
| `uris`       | string | Yes      | Comma-separated Spotify URIs (e.g., "spotify:track:xxx,spotify:track:yyy") |
| `position`   | number | No       | Position to insert tracks (0-based). If omitted, tracks are appended.      |

**Output**

| Parameter     | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| `snapshot_id` | string | New playlist snapshot ID after modification |

#### `spotify_remove_tracks_from_playlist`

Remove one or more tracks from a Spotify playlist.

**Input**

| Parameter    | Type   | Required | Description                                                                          |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------ |
| `playlistId` | string | Yes      | The Spotify ID of the playlist                                                       |
| `uris`       | string | Yes      | Comma-separated Spotify URIs to remove (e.g., "spotify:track:xxx,spotify:track:yyy") |

**Output**

| Parameter     | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| `snapshot_id` | string | New playlist snapshot ID after modification |

#### `spotify_reorder_playlist_items`

Move tracks to a different position in a playlist.

**Input**

| Parameter       | Type   | Required | Description                                  |
| --------------- | ------ | -------- | -------------------------------------------- |
| `playlistId`    | string | Yes      | The Spotify playlist ID                      |
| `range_start`   | number | Yes      | Start index of items to reorder              |
| `insert_before` | number | Yes      | Index to insert items before                 |
| `range_length`  | number | No       | Number of items to reorder                   |
| `snapshot_id`   | string | No       | Playlist snapshot ID for concurrency control |

**Output**

| Parameter     | Type   | Description              |
| ------------- | ------ | ------------------------ |
| `snapshot_id` | string | New playlist snapshot ID |

#### `spotify_replace_playlist_items`

Replace all items in a playlist with new tracks.

**Input**

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `playlistId` | string | Yes      | The Spotify playlist ID                |
| `uris`       | string | Yes      | Comma-separated Spotify URIs (max 100) |

**Output**

| Parameter     | Type   | Description              |
| ------------- | ------ | ------------------------ |
| `snapshot_id` | string | New playlist snapshot ID |

#### `spotify_follow_playlist`

Follow (save) a playlist.

**Input**

| Parameter    | Type    | Required | Description                                      |
| ------------ | ------- | -------- | ------------------------------------------------ |
| `playlistId` | string  | Yes      | The Spotify playlist ID                          |
| `public`     | boolean | No       | Whether the playlist will be in public playlists |

**Output**

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `success` | boolean | Whether follow succeeded |

#### `spotify_unfollow_playlist`

Unfollow (unsave) a playlist.

**Input**

| Parameter    | Type   | Required | Description             |
| ------------ | ------ | -------- | ----------------------- |
| `playlistId` | string | Yes      | The Spotify playlist ID |

**Output**

| Parameter | Type    | Description                |
| --------- | ------- | -------------------------- |
| `success` | boolean | Whether unfollow succeeded |

#### `spotify_check_playlist_followers`

Check if users follow a playlist.

**Input**

| Parameter    | Type   | Required | Description                               |
| ------------ | ------ | -------- | ----------------------------------------- |
| `playlistId` | string | Yes      | The Spotify playlist ID                   |
| `userIds`    | string | Yes      | Comma-separated user IDs to check (max 5) |

**Output**

| Parameter | Type | Description                     |
| --------- | ---- | ------------------------------- |
| `results` | json | Array of booleans for each user |

#### `spotify_get_current_user`

Get the current user

**Input**

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

**Output**

| Parameter      | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| `id`           | string | Spotify user ID                    |
| `display_name` | string | Display name                       |
| `email`        | string | Email address                      |
| `country`      | string | Country code                       |
| `product`      | string | Subscription level (free, premium) |
| `followers`    | number | Number of followers                |
| `image_url`    | string | Profile image URL                  |
| `external_url` | string | Spotify profile URL                |

#### `spotify_get_user_profile`

Get a user

**Input**

| Parameter | Type   | Required | Description         |
| --------- | ------ | -------- | ------------------- |
| `userId`  | string | Yes      | The Spotify user ID |

**Output**

| Parameter      | Type   | Description         |
| -------------- | ------ | ------------------- |
| `id`           | string | User ID             |
| `display_name` | string | Display name        |
| `followers`    | number | Number of followers |
| `image_url`    | string | Profile image URL   |
| `external_url` | string | Spotify URL         |

#### `spotify_get_top_tracks`

Get the current user

**Input**

| Parameter    | Type   | Required | Description                                                                        |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------- |
| `time_range` | string | No       | Time range: short\_term (\~4 weeks), medium\_term (\~6 months), long\_term (years) |
| `limit`      | number | No       | Number of tracks to return (1-50)                                                  |
| `offset`     | number | No       | Index of the first track to return                                                 |

**Output**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `tracks`  | array | User        |

#### `spotify_get_top_artists`

Get the current user

**Input**

| Parameter    | Type   | Required | Description                                                                        |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------- |
| `time_range` | string | No       | Time range: short\_term (\~4 weeks), medium\_term (\~6 months), long\_term (years) |
| `limit`      | number | No       | Number of artists to return (1-50)                                                 |
| `offset`     | number | No       | Index of the first artist to return                                                |

**Output**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `artists` | array | User        |

#### `spotify_get_saved_tracks`

Get the current user

**Input**

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `limit`   | number | No       | Number of tracks to return (1-50)  |
| `offset`  | number | No       | Index of the first track to return |
| `market`  | string | No       | ISO 3166-1 alpha-2 country code    |

**Output**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `tracks`  | array | User        |

#### `spotify_save_tracks`

Save tracks to the current user

**Input**

| Parameter  | Type   | Required | Description                                        |
| ---------- | ------ | -------- | -------------------------------------------------- |
| `trackIds` | string | Yes      | Comma-separated Spotify track IDs to save (max 50) |

**Output**

| Parameter | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `success` | boolean | Whether the tracks were saved successfully |

#### `spotify_remove_saved_tracks`

Remove tracks from the user

**Input**

| Parameter  | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `trackIds` | string | Yes      | Comma-separated track IDs to remove (max 50) |

**Output**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `success` | boolean | Whether tracks were removed successfully |

#### `spotify_check_saved_tracks`

Check if one or more tracks are saved in the user

**Input**

| Parameter  | Type   | Required | Description                                 |
| ---------- | ------ | -------- | ------------------------------------------- |
| `trackIds` | string | Yes      | Comma-separated track IDs to check (max 50) |

**Output**

| Parameter    | Type    | Description                          |
| ------------ | ------- | ------------------------------------ |
| `results`    | json    | Array of track IDs with saved status |
| `all_saved`  | boolean | Whether all tracks are saved         |
| `none_saved` | boolean | Whether no tracks are saved          |

#### `spotify_get_recently_played`

Get the user

**Input**

| Parameter | Type   | Required | Description                                                       |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| `limit`   | number | No       | Number of tracks to return (1-50)                                 |
| `after`   | number | No       | Unix timestamp in milliseconds. Returns items after this cursor.  |
| `before`  | number | No       | Unix timestamp in milliseconds. Returns items before this cursor. |

**Output**

| Parameter | Type  | Description            |
| --------- | ----- | ---------------------- |
| `items`   | array | Recently played tracks |

#### `spotify_get_new_releases`

Get a list of new album releases featured in Spotify.

**Input**

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `country` | string | No       | ISO 3166-1 alpha-2 country code (e.g., "US", "GB") |
| `limit`   | number | No       | Number of releases to return (1-50)                |
| `offset`  | number | No       | Index of first release to return                   |

**Output**

| Parameter | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `albums`  | json   | List of new releases         |
| `total`   | number | Total number of new releases |
| `next`    | string | URL for next page            |

#### `spotify_get_categories`

Get a list of browse categories used to tag items in Spotify.

**Input**

| Parameter | Type   | Required | Description                                        |
| --------- | ------ | -------- | -------------------------------------------------- |
| `country` | string | No       | ISO 3166-1 alpha-2 country code (e.g., "US", "GB") |
| `locale`  | string | No       | Locale code (e.g., "en\_US", "es\_MX")             |
| `limit`   | number | No       | Number of categories to return (1-50)              |

**Output**

| Parameter    | Type   | Description                |
| ------------ | ------ | -------------------------- |
| `categories` | json   | List of browse categories  |
| `total`      | number | Total number of categories |

#### `spotify_get_markets`

Get the list of markets where Spotify is available.

**Input**

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

**Output**

| Parameter | Type | Description               |
| --------- | ---- | ------------------------- |
| `markets` | json | List of ISO country codes |

#### `spotify_get_playback_state`

Get the current playback state including device, track, and progress.

**Input**

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `market`  | string | No       | ISO 3166-1 alpha-2 country code |

**Output**

| Parameter                | Type    | Description                       |
| ------------------------ | ------- | --------------------------------- |
| `is_playing`             | boolean | Whether playback is active        |
| `device`                 | object  | Active device information         |
| `progress_ms`            | number  | Progress in milliseconds          |
| `currently_playing_type` | string  | Type of content playing           |
| `shuffle_state`          | boolean | Whether shuffle is enabled        |
| `repeat_state`           | string  | Repeat mode (off, track, context) |
| `track`                  | object  | Currently playing track           |

#### `spotify_get_currently_playing`

Get the user

**Input**

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `market`  | string | No       | ISO country code for market |

**Output**

| Parameter     | Type    | Description                    |
| ------------- | ------- | ------------------------------ |
| `is_playing`  | boolean | Whether playback is active     |
| `progress_ms` | number  | Current position in track (ms) |
| `track`       | json    | Currently playing track        |

#### `spotify_get_devices`

Get the user

**Input**

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

**Output**

| Parameter | Type  | Description                |
| --------- | ----- | -------------------------- |
| `devices` | array | Available playback devices |

#### `spotify_get_queue`

Get the user

**Input**

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

**Output**

| Parameter           | Type | Description              |
| ------------------- | ---- | ------------------------ |
| `currently_playing` | json | Currently playing track  |
| `queue`             | json | Upcoming tracks in queue |

#### `spotify_play`

Start or resume playback on Spotify. Can play specific tracks, albums, or playlists.

**Input**

| Parameter     | Type   | Required | Description                                                                      |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `device_id`   | string | No       | Device ID to play on. If not provided, plays on active device.                   |
| `context_uri` | string | No       | Spotify URI of album, artist, or playlist to play (e.g., "spotify:album:xxx")    |
| `uris`        | string | No       | Comma-separated track URIs to play (e.g., "spotify:track:xxx,spotify:track:yyy") |
| `offset`      | number | No       | Position in context to start playing (0-based index)                             |
| `position_ms` | number | No       | Position in track to start from (in milliseconds)                                |

**Output**

| Parameter | Type    | Description                           |
| --------- | ------- | ------------------------------------- |
| `success` | boolean | Whether playback started successfully |

#### `spotify_pause`

Pause playback on Spotify.

**Input**

| Parameter   | Type   | Required | Description                                                |
| ----------- | ------ | -------- | ---------------------------------------------------------- |
| `device_id` | string | No       | Device ID to pause. If not provided, pauses active device. |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether playback was paused |

#### `spotify_skip_next`

Skip to the next track on Spotify.

**Input**

| Parameter   | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `device_id` | string | No       | Device ID. If not provided, uses active device. |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether skip was successful |

#### `spotify_skip_previous`

Skip to the previous track on Spotify.

**Input**

| Parameter   | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `device_id` | string | No       | Device ID. If not provided, uses active device. |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether skip was successful |

#### `spotify_seek`

Seek to a position in the currently playing track.

**Input**

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `position_ms` | number | Yes      | Position in milliseconds to seek to |
| `device_id`   | string | No       | Device ID to target                 |

**Output**

| Parameter | Type    | Description                 |
| --------- | ------- | --------------------------- |
| `success` | boolean | Whether seek was successful |

#### `spotify_add_to_queue`

Add a track to the user

**Input**

| Parameter   | Type   | Required | Description                                                 |
| ----------- | ------ | -------- | ----------------------------------------------------------- |
| `uri`       | string | Yes      | Spotify URI of the track to add (e.g., "spotify:track:xxx") |
| `device_id` | string | No       | Device ID. If not provided, uses active device.             |

**Output**

| Parameter | Type    | Description                      |
| --------- | ------- | -------------------------------- |
| `success` | boolean | Whether track was added to queue |

#### `spotify_set_volume`

Set the playback volume on Spotify.

**Input**

| Parameter        | Type   | Required | Description                                     |
| ---------------- | ------ | -------- | ----------------------------------------------- |
| `volume_percent` | number | Yes      | Volume level (0 to 100)                         |
| `device_id`      | string | No       | Device ID. If not provided, uses active device. |

**Output**

| Parameter | Type    | Description            |
| --------- | ------- | ---------------------- |
| `success` | boolean | Whether volume was set |

#### `spotify_set_repeat`

Set the repeat mode for playback.

**Input**

| Parameter   | Type   | Required | Description                               |
| ----------- | ------ | -------- | ----------------------------------------- |
| `state`     | string | Yes      | Repeat mode: "off", "track", or "context" |
| `device_id` | string | No       | Device ID to target                       |

**Output**

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `success` | boolean | Whether repeat mode was set successfully |

#### `spotify_set_shuffle`

Turn shuffle on or off.

**Input**

| Parameter   | Type    | Required | Description                        |
| ----------- | ------- | -------- | ---------------------------------- |
| `state`     | boolean | Yes      | true for shuffle on, false for off |
| `device_id` | string  | No       | Device ID to target                |

**Output**

| Parameter | Type    | Description                          |
| --------- | ------- | ------------------------------------ |
| `success` | boolean | Whether shuffle was set successfully |

#### `spotify_transfer_playback`

Transfer playback to a different device.

**Input**

| Parameter   | Type    | Required | Description                                |
| ----------- | ------- | -------- | ------------------------------------------ |
| `device_id` | string  | Yes      | Device ID to transfer playback to          |
| `play`      | boolean | No       | Whether to start playing on the new device |

**Output**

| Parameter | Type    | Description                     |
| --------- | ------- | ------------------------------- |
| `success` | boolean | Whether transfer was successful |

### Notes

* Category: `tools`
* Type: `spotify`