> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Spotify

The Spotify connector lets your AI agent act in each user's Spotify account. Each user signs in to Spotify once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 47 tools.

**Authentication:** OAuth 2.0
**Categories:** Media
**Tools:** 47: 30 read, 15 write, 2 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Spotify app
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SPOTIFY)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Spotify connection

   In **AgentKit > Connections**, create a Spotify connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Spotify connections use your own OAuth app. Register one with Spotify and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Spotify connection.

   **Console steps with screenshots:**

   Create a Spotify app so Scalekit can authorize access to your users' Spotify accounts. You'll register the Scalekit redirect URI in the app, then add the app's Client ID and Client secret to your Scalekit connection.

   1. ### Create a Spotify app

      - Sign in to the [Spotify for Developers dashboard](https://developer.spotify.com/dashboard).
      - Click **Create app**, enter an app name and description, and select **Web API** under **APIs used**.

        > Image: Spotify for Developers dashboard with the Create app button

   2. ### Copy the redirect URI from Scalekit

      - In the [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** > **Create Connection**. Find **Spotify** and click **Create**.
      - Click **Use your own credentials** and copy the redirect URI. It looks like `https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback`.

   3. ### Add the redirect URI to your Spotify app

      - In your Spotify app, open **Settings**.
      - Under **Redirect URIs**, paste the Scalekit redirect URI, click **Add**, and then **Save**.

        > Image: Spotify app settings with the Scalekit redirect URI listed under Redirect URIs

   4. ### Copy your Client ID and Client secret

      - On the same **Basic Information** page, copy the **Client ID**.
      - Click **View client secret** and copy the **Client secret**.

        > Image: Spotify Basic Information page with the Client ID and the View client secret link

   5. ### Add the credentials in Scalekit

      - Return to your Spotify connection in Scalekit.
      - Enter the **Client ID** and **Client secret**, select the scopes your tools need, and click **Save**.

      > note: Development mode
      >
      > New Spotify apps start in development mode, which only lets users you add under **User Management** authorize the app. Request extended quota from Spotify before you open the app to all users.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'spotify'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Spotify:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'spotify_devices_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "spotify"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Spotify:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="spotify_devices_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'spotify_album_get',
  toolInput: {
    id: '<id>',
  },
  connector: 'spotify',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="spotify_album_get",
    tool_input={
        "id": "<id>",
    },
    connection_name="spotify",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `spotify_album_get`

Get Album · Read-only

Get Spotify catalog information for a single album by its Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the album
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code for market filtering

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_album_tracks_get`

Get Album Tracks · Read-only

Get Spotify catalog information about an album's tracks. Returns paginated list of simplified track objects.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the album
- `limit` (`integer`, optional): Maximum number of tracks to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first track to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_artist_albums_get`

Get Artist's Albums · Read-only

Get Spotify catalog information about an artist's albums. Optionally filter by album group.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the artist
- `include_groups` (`string`, optional): Comma-separated list of album types to include: album, single, appears_on, compilation
- `limit` (`integer`, optional): Maximum number of items to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first item to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_artist_get`

Get Artist · Read-only

Get Spotify catalog information for a single artist by their Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the artist

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_audiobook_chapters_get`

Get Audiobook Chapters · Read-only

Get Spotify catalog information for an audiobook's chapters. Requires a valid Spotify ID for the audiobook.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the audiobook
- `limit` (`integer`, optional): Maximum number of chapters to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first chapter to return for pagination

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_audiobook_get`

Get Audiobook · Read-only

Get Spotify catalog information for a single audiobook. Only available for markets where audiobooks are available.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the audiobook
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_chapter_get`

Get Chapter · Read-only

Get Spotify catalog information for a single audiobook chapter by its Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the chapter
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_devices_get`

Get Available Devices · Read-only

Get information about a user's available playback devices. Returns device IDs, names, types, and active status. Requires user-read-playback-state scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_episode_get`

Get Episode · Read-only

Get Spotify catalog information for a single podcast episode by its Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the episode
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_following_get`

Get Followed Artists · Read-only

Get the current user's followed artists. Requires user-follow-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `type` (`string`, required): Type of entity to return (only 'artist' is supported)
- `after` (`string`, optional): The last artist ID from the previous page (for cursor-based pagination)
- `limit` (`integer`, optional): Maximum number of items to return (default 20, max 50)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"type":"<type>"}`

### `spotify_get_currently_playing`

Get Currently Playing Track · Read-only

Some random change for this tool. Get the user's currently playing track or episode.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `additional_types` (`string`, optional): Comma-separated list of additional content types to include: track, episode
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code for track relinking

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_get_user_playlists`

Get User Playlists · Read-only

Get a list of the playlists owned or followed by the current Spotify user. Returns playlist names, IDs, track counts, and visibility. Requires playlist-read-private scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of playlists to return (default 20, max 50)
- `offset` (`integer`, optional): Index of the first playlist to return for pagination

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_library_check`

Check Items in Library · Read-only

Check whether items are already in the current user's Spotify library by URI: tracks, albums, episodes, shows and audiobooks are checked as saved, artists, users and playlists as followed.
Returns a JSON array of booleans; true means the item is saved or followed.
Use for any supported item type in one call; it replaces the per-type tools spotify_saved_tracks_check, spotify_saved_albums_check, spotify_saved_episodes_check, spotify_saved_shows_check, spotify_saved_audiobooks_check and spotify_following_check (artists, users), whose Spotify endpoints are removed for Development Mode apps (Extended Quota Mode apps keep them). Use spotify_saved_tracks_get or the other saved-item list tools to list what is saved.
Needs 1 to 40 comma-separated URIs (taken from the uri field of spotify_search results or of get tools such as spotify_track_get) of type spotify:track, spotify:album, spotify:episode, spotify:show, spotify:audiobook, spotify:artist, spotify:user or spotify:playlist; the connection needs user-library-read, user-follow-read and playlist-read-private, depending on the URI types.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uris` (`string`, required): Comma-separated list of Spotify URIs to look up in the current user's library, 1 to 40 per call. Supported URI types: spotify:track:{id}, spotify:album:{id}, spotify:episode:{id}, spotify:show:{id}, spotify:audiobook:{id}, spotify:artist:{id}, spotify:user:{id}, spotify:playlist:{id}. The result is a JSON array of booleans; true means the item is saved or, for artists, users and playlists, followed. Use plain URIs separated by commas with no spaces. Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:album:4aawyAB9vmqN3uQ7FjRGTy,spotify:artist:0TnOYISbd1XYRBk9myaseg

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"uris":"<uris>"}`

### `spotify_me_get`

Get Current User Profile · Read-only

Get detailed profile information about the current authenticated user. Requires user-read-private and user-read-email scopes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playback_state_get`

Get Playback State · Read-only

Get information about the user's current playback state including track, progress, device, shuffle, and repeat. Requires user-read-playback-state scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `additional_types` (`string`, optional): Comma-separated list of additional content types: episode
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code for track relinking

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playlist_cover_get`

Get Playlist Cover Image · Read-only

Get the current image of a playlist. Returns an array of image objects with URL, height, and width.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `playlist_id` (`string`, required): The Spotify ID of the playlist

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>"}`

### `spotify_playlist_get`

Get Playlist · Read-only

Get a playlist by its Spotify ID. Returns playlist metadata, owner info, and optionally track list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `playlist_id` (`string`, required): The Spotify ID of the playlist
- `additional_types` (`string`, optional): Comma-separated list of item types to include alongside tracks: episode
- `fields` (`string`, optional): Filters for the query: a comma-separated list of fields to return
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>"}`

### `spotify_playlist_items_get`

Get Playlist Items · Read-only

Get full details of the tracks or episodes in a playlist. Returns paginated list of playlist items.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `playlist_id` (`string`, required): The Spotify ID of the playlist
- `additional_types` (`string`, optional): Comma-separated list of additional content types to include: episode
- `fields` (`string`, optional): Comma-separated list of fields to return
- `limit` (`integer`, optional): Maximum number of items to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first item to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>"}`

### `spotify_queue_get`

Get User's Queue · Read-only

Get the list of objects that make up the user's queue. Returns current track and upcoming tracks. Requires user-read-currently-playing scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_recently_played_get`

Get Recently Played Tracks · Read-only

Get tracks from the current user's recently played tracks. Requires user-read-recently-played scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`integer`, optional): Unix timestamp in milliseconds to return items after this cursor
- `before` (`integer`, optional): Unix timestamp in milliseconds to return items before this cursor
- `limit` (`integer`, optional): Maximum number of items to return (default 20, max 50)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_saved_albums_get`

Get Saved Albums · Read-only

Get a list of albums saved in the current user's library. Requires user-library-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of albums to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first album to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_saved_audiobooks_get`

Get Saved Audiobooks · Read-only

Get a list of audiobooks saved in the current Spotify user's library. Requires user-library-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of audiobooks to return (default 20, max 50)
- `offset` (`integer`, optional): Index of the first audiobook to return for pagination

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_saved_episodes_get`

Get Saved Episodes · Read-only

Get a list of episodes saved in the current user's library. Requires user-library-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of episodes to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first episode to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_saved_shows_get`

Get Saved Shows · Read-only

Get a list of shows saved in the current user's library. Requires user-library-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of shows to return (default 20, max 50)
- `offset` (`integer`, optional): Index of the first show to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_saved_tracks_get`

Get Saved Tracks · Read-only

Get a list of tracks saved in the current user's library (liked songs). Requires user-library-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Maximum number of tracks to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first track to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_search`

Search Spotify · Read-only

Search Spotify's catalog for tracks, artists, albums, playlists, shows, or episodes. Returns matching items with metadata.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): Search query string (e.g. artist name, track title, album name)
- `type` (`string`, required): Comma-separated list of item types to search: track, artist, album, playlist, show, episode
- `limit` (`integer`, optional): Maximum number of results per type to return (default 10, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code to filter results by market availability
- `offset` (`integer`, optional): Index of the first result to return for pagination

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"q":"<q>","type":"<type>"}`

### `spotify_show_episodes_get`

Get Show Episodes · Read-only

Get Spotify catalog information about episodes of a podcast show.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the show
- `limit` (`integer`, optional): Maximum number of episodes to return (default 20, max 50)
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code
- `offset` (`integer`, optional): Index of the first episode to return (default 0)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_show_get`

Get Show · Read-only

Get Spotify catalog information for a single podcast show (podcast) by its Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the show
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_top_items_get`

Get User's Top Items · Read-only

Get the current user's top artists or tracks based on calculated affinity. Requires user-top-read scope.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `type` (`string`, required): Type of top items to return: artists or tracks
- `limit` (`integer`, optional): Maximum number of items to return (default 20, max 50)
- `offset` (`integer`, optional): Index of the first item to return (default 0)
- `time_range` (`string`, optional): Time range for affinity computation: long_term (~1 year), medium_term (~6 months), short_term (~4 weeks)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"type":"<type>"}`

### `spotify_track_get`

Get Track · Read-only

Get Spotify catalog information for a single track by its Spotify ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): The Spotify ID of the track
- `market` (`string`, optional): ISO 3166-1 alpha-2 country code

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"id":"<id>"}`

### `spotify_add_to_playlist`

Add Items to Playlist · Write

Add one or more tracks or episodes to a playlist, appended at the end or inserted at a zero-based position.
Returns the playlist's new snapshot_id.
Pass item URIs (spotify:track:... or spotify:episode:...), comma-separated, up to 100 per call; read the current items with spotify_playlist_items_get and remove items with spotify_playlist_items_remove.
The current user must own or collaborate on the playlist; needs playlist-modify-public or playlist-modify-private.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `playlist_id` (`string`, required): Spotify ID of the playlist to add items to
- `uris` (`string`, required): Comma-separated Spotify track or episode URIs, up to 100 per call, e.g. spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:512ojhOuo1ktJprKbVcKyQ. Items are added in the order given.
- `position` (`integer`, optional): Zero-based position to insert items. Appends to end if omitted.

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>","uris":"<uris>"}`

### `spotify_library_save`

Save Items to Library · Write

Save items to the current user's Spotify library by URI: tracks, albums, episodes, shows and audiobooks are saved, users and playlists are followed.
Returns an empty success response (HTTP 200); confirm the change with spotify_library_check.
Use for any supported item type in one call; it replaces the per-type tools spotify_saved_tracks_save, spotify_saved_albums_save, spotify_saved_episodes_save, spotify_saved_shows_save, spotify_saved_audiobooks_save and spotify_playlist_follow and, for users, spotify_follow, whose Spotify endpoints are removed for Development Mode apps (Extended Quota Mode apps keep them). Use spotify_library_remove to undo.
Needs 1 to 40 comma-separated URIs (taken from the uri field of spotify_search results or of get tools such as spotify_track_get) of type spotify:track, spotify:album, spotify:episode, spotify:show, spotify:audiobook, spotify:user or spotify:playlist; the connection needs user-library-modify, user-follow-modify and playlist-modify-public, depending on the URI types.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `uris` (`string`, required): Comma-separated list of Spotify URIs to save to the current user's library, 1 to 40 per call. Supported URI types: spotify:track:{id}, spotify:album:{id}, spotify:episode:{id}, spotify:show:{id}, spotify:audiobook:{id}, spotify:user:{id}, spotify:playlist:{id}. Tracks, albums, episodes, shows and audiobooks are saved; a user or playlist URI follows that user or playlist. Artist URIs are not in Spotify's list of supported types for this call. Use plain URIs separated by commas with no spaces. Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:album:4aawyAB9vmqN3uQ7FjRGTy

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"uris":"<uris>"}`

### `spotify_playback_next`

Skip to Next Track · Write

Skip to the next track in the queue. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `device_id` (`string`, optional): The device ID to skip next on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playback_pause`

Pause Playback · Write

Pause playback on the user's account. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `device_id` (`string`, optional): The device ID to pause playback on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playback_previous`

Skip to Previous Track · Write

Skip to the previous track in the queue. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `device_id` (`string`, optional): The device ID to skip previous on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playback_seek`

Seek to Position · Write

Seek to a specific position in the currently playing track. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `position_ms` (`integer`, required): Position in milliseconds to seek to
- `device_id` (`string`, optional): The device ID to seek on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"position_ms":1}`

### `spotify_playback_start`

Start or Resume Playback · Write

Start or resume playback. Optionally set a context (album, artist, playlist) or specific tracks, and set an offset. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `context_uri` (`string`, optional): Spotify URI of the context to play (album, artist, or playlist)
- `device_id` (`string`, optional): The device ID to start playback on
- `position_ms` (`integer`, optional): Position in milliseconds to start playback from
- `uris` (`string`, optional): Comma-separated list of Spotify track URIs to play

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{}`

### `spotify_playback_transfer`

Transfer Playback · Write

Transfer playback to a new device. Optionally keep or start playing. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `device_id` (`string`, required): The Spotify device ID to transfer playback to
- `play` (`boolean`, optional): Whether to start playback on transfer (default false = keep current state)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"device_id":"<device_id>"}`

### `spotify_playlist_create`

Create Playlist · Write

Create an empty playlist owned by the current user; it is public unless public is set to false.
Returns the new playlist's id, uri, name, description, public, collaborative, snapshot_id and owner.
Use spotify_add_to_playlist to fill it and spotify_playlist_update to change its details later.
Needs playlist-modify-public (default) or playlist-modify-private (public=false); a collaborative playlist needs both scopes and public=false.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name for the new playlist
- `collaborative` (`boolean`, optional): Whether the playlist is collaborative (other users can add and remove items). Only works together with public=false, so set both; the API default for public is true. Needs the playlist-modify-public and playlist-modify-private scopes.
- `description` (`string`, optional): Description of the playlist (displayed in Spotify clients)
- `public` (`boolean`, optional): Whether the playlist is public (default true)

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"name":"<name>"}`

### `spotify_playlist_items_reorder`

Reorder Playlist Items · Write

Reorder items in a playlist by moving a range of items to a new position. Requires playlist-modify-public or playlist-modify-private scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `insert_before` (`integer`, required): The position where the items should be inserted (zero-based index)
- `playlist_id` (`string`, required): The Spotify ID of the playlist
- `range_start` (`integer`, required): Position of the first item to move (zero-based index)
- `range_length` (`integer`, optional): Number of items to move (default 1)
- `snapshot_id` (`string`, optional): Snapshot ID of the current playlist state to validate against

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"insert_before":1,"playlist_id":"<playlist_id>","range_start":1}`

### `spotify_playlist_update`

Update Playlist Details · Write

Change a playlist's name, description, public/private status, or collaborative setting. Requires playlist-modify-public or playlist-modify-private scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `playlist_id` (`string`, required): The Spotify ID of the playlist
- `collaborative` (`boolean`, optional): Whether the playlist is collaborative (only private playlists can be collaborative)
- `description` (`string`, optional): New description for the playlist
- `name` (`string`, optional): New name for the playlist
- `public` (`boolean`, optional): Whether the playlist is public

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>"}`

### `spotify_queue_add`

Add Item to Queue · Write

Add an item (track or episode) to the end of the user's playback queue. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `uri` (`string`, required): The Spotify URI of the track or episode to add
- `device_id` (`string`, optional): The device ID to add to queue on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"uri":"<uri>"}`

### `spotify_repeat_mode_set`

Set Repeat Mode · Write

Set the repeat mode for the user's playback. Options are track (repeat single track), context (repeat context), or off. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `state` (`string`, required): Repeat mode: track, context, or off
- `device_id` (`string`, optional): The device ID to set repeat mode on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"state":"<state>"}`

### `spotify_shuffle_set`

Toggle Shuffle · Write

Toggle shuffle on or off for the user's playback. Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `state` (`boolean`, required): Whether shuffle should be enabled (true) or disabled (false)
- `device_id` (`string`, optional): The device ID to toggle shuffle on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"state":true}`

### `spotify_volume_set`

Set Playback Volume · Write

Set the volume for the user's current playback device (0-100). Requires user-modify-playback-state scope.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `volume_percent` (`integer`, required): Volume percent (0-100)
- `device_id` (`string`, optional): The device ID to set volume on

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"volume_percent":1}`

### `spotify_library_remove`

Remove Items from Library · Destructive

Remove items from the current user's Spotify library by URI: tracks, albums, episodes, shows and audiobooks are removed, users and playlists are unfollowed.
Returns an empty success response (HTTP 200); confirm the change with spotify_library_check.
Use for any supported item type in one call; it replaces the per-type tools spotify_saved_tracks_remove, spotify_saved_albums_remove, spotify_saved_episodes_remove, spotify_saved_shows_remove, spotify_saved_audiobooks_remove and spotify_playlist_unfollow and, for users, spotify_unfollow, whose Spotify endpoints are removed for Development Mode apps (Extended Quota Mode apps keep them). Use spotify_library_save to add items.
Needs 1 to 40 comma-separated URIs (taken from the uri field of saved-item lists such as spotify_saved_tracks_get, or of spotify_search results) of type spotify:track, spotify:album, spotify:episode, spotify:show, spotify:audiobook, spotify:user or spotify:playlist; the connection needs user-library-modify, user-follow-modify and playlist-modify-public, depending on the URI types.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `uris` (`string`, required): Comma-separated list of Spotify URIs to remove from the current user's library, 1 to 40 per call. Supported URI types: spotify:track:{id}, spotify:album:{id}, spotify:episode:{id}, spotify:show:{id}, spotify:audiobook:{id}, spotify:user:{id}, spotify:playlist:{id}. Tracks, albums, episodes, shows and audiobooks are removed from the library; a user or playlist URI unfollows that user or playlist. Artist URIs are not in Spotify's list of supported types for this call. Use plain URIs separated by commas with no spaces. Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:album:4aawyAB9vmqN3uQ7FjRGTy

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"uris":"<uris>"}`

### `spotify_playlist_items_remove`

Remove Playlist Items · Destructive

Remove one or more tracks or episodes from a playlist. Provide track/episode URIs to remove. Requires playlist-modify-public or playlist-modify-private scope.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `playlist_id` (`string`, required): The Spotify ID of the playlist
- `uris` (`string`, required): Comma-separated list of Spotify track or episode URIs to remove
- `snapshot_id` (`string`, optional): Snapshot ID of the current playlist state to validate against

Also accepts `schema_version` and `tool_version` to pin a version.

Example input: `{"playlist_id":"<playlist_id>","uris":"<uris>"}`

## Related

Other Media connectors ([all 65](/agentkit/connectors/?category=media)):

- [Reddit](/agentkit/connectors/reddit/): Scalekit connector, OAuth, 105 tools
- [Diarize](/agentkit/connectors/diarize/): Scalekit connector, Access token, 3 tools
- [YouTube](/agentkit/connectors/youtube/): Scalekit connector, OAuth, 45 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
