Spotify

Music streaming. Search the catalog, control playback on a device, manage playlists, save tracks and albums, and read history.

Measured routing accuracy

58 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 40 cases written by hand and 18 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

oauth2

Tools

40 action tools. The catalog-wide slug is spotify.<tool>, which is what search_tools returns and call_tool takes.

spotify.search

Search the Spotify catalog for tracks, albums, artists, or playlists by keyword. Use when the user wants to find or play something by name and you don't already have its Spotify id. For an id you already have, use get_track, get_album, or get_artist instead.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /search.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "look up a song by name", "find that artist on spotify", "hunt down an album title", "see if a playlist exists", "pull up something by keyword".

spotify.get_track

Get full details for one track by its Spotify id: title, artists, album, duration, and popularity. Use when the user already names or links a specific track. To find a track's id from a name, use search first.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /tracks/{{params.track_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what song is this exactly", "details on this specific song", "how long does this song run", "who made this particular song".

spotify.get_album

Get full details for one album by its Spotify id: title, artists, release date, and track count. Use when the user already names or links a specific album. For the album's individual tracks, use get_album_tracks.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /albums/{{params.album_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "when did this record come out", "how many songs are on this record", "info about this specific release".

spotify.get_album_tracks

List the tracks on an album, in album order. Use when the user asks what songs are on an album or wants its full tracklist. For the album's own title and release details rather than its songs, use get_album.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /albums/{{params.album_id}}/tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what songs are on this record", "see the full tracklist", "list every song on this release", "what's the order of songs here".

spotify.get_artist

Get full details for one artist by their Spotify id: name, genres, popularity, and follower count. Use when the user already names or links a specific artist. For their most popular songs, use get_artist_top_tracks.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /artists/{{params.artist_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who is this musician", "how popular is this act", "what genre does this act play", "how many people follow this musician".

spotify.get_artist_top_tracks

Get an artist's most popular tracks. Use when the user asks for an artist's biggest songs, hits, or best-known tracks. For their whole discography or a specific album, use get_album or get_album_tracks instead.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /artists/{{params.artist_id}}/top-tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "this act's biggest hits", "most popular songs by this musician", "what should I listen to first from them", "their most streamed songs".

spotify.get_playback_state

Get what's currently playing and the full player state: device, progress, shuffle, and repeat. Use when the user asks what's playing, what song this is, or which device is active. Returns no item when nothing is playing.

Class read (reads only). Scopes user-read-playback-state. Calls GET /me/player.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's on right now", "which speaker is this playing on", "is anything playing at the moment", "what song is this that's on".

spotify.start_playback

Start or resume playback of a track, album, artist, or playlist. Use when the user wants to play, resume, or start something. Pass context_uri for an album, playlist, or artist, or track_uris for specific tracks. With neither, resumes whatever was paused.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/play.

Arguments:

Also retrieved by: "hit play on this record", "throw this playlist on", "get this song going", "kick off this album", "put this on".

spotify.pause_playback

Pause playback on the active or a given device. Use when the user wants to pause, stop, or halt what's playing. To resume, use start_playback.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/pause.

Arguments:

Also retrieved by: "hold the music for a second", "cut the music", "silence whatever's on".

spotify.skip_to_next

Skip to the next track in the current context. Use when the user wants to skip, go to the next song, or move forward a track. For the previous track, use skip_to_previous.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls POST /me/player/next.

Arguments:

Also retrieved by: "next song please", "move on from this one", "I'm done with this track", "forward one song".

spotify.skip_to_previous

Go back to the previous track. Use when the user wants to go back, replay the last song, or skip backward. For the next track, use skip_to_next.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls POST /me/player/previous.

Arguments:

Also retrieved by: "go back a song", "that last one again", "rewind to the one before this".

spotify.seek_to_position

Jump to a specific position within the currently playing track. Use when the user wants to skip ahead, rewind, or jump to a point in the current song.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/seek.

Arguments:

Also retrieved by: "jump ahead in the song", "go back to the chorus", "fast forward this track", "start this over from a point".

spotify.set_repeat_mode

Set the repeat mode for playback. Use when the user wants to repeat the current track, repeat the whole playlist or album, or turn repeat off.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/repeat.

Arguments:

Also retrieved by: "loop this song", "keep this album going in a loop", "stop looping the music", "play this on repeat".

spotify.set_playback_volume

Set the playback volume on the active or a given device. Use when the user wants to turn the volume up, down, or set it to a specific level.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/volume.

Arguments:

Also retrieved by: "turn it up", "lower the sound a bit", "make the music louder", "crank it down".

spotify.set_shuffle_mode

Turn shuffle on or off for playback. Use when the user wants to shuffle, randomize, or turn off shuffling of the current context.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player/shuffle.

Arguments:

Also retrieved by: "randomize the order", "mix these songs up", "stop playing in order", "shake up the playlist order".

spotify.transfer_playback

Move playback to a different device, like a phone, speaker, or computer. Use when the user wants to switch playback to another device or keep listening somewhere else. Find device ids with get_available_devices.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls PUT /me/player.

Arguments:

Also retrieved by: "move the music to my speaker", "play this on the living room speaker instead", "switch what's playing over to my phone", "send the audio to another device".

spotify.get_available_devices

List the devices currently available for playback, like phones, speakers, and computers signed into Spotify. Use when the user asks what devices are available, or before calling transfer_playback.

Class read (reads only). Scopes user-read-playback-state. Calls GET /me/player/devices.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what can I play music on right now", "which speakers are online", "see what's signed into my account".

spotify.add_to_queue

Add a track to the end of the playback queue, without interrupting what's playing now. Use when the user wants to queue up, add next, or play something right after the current song.

Class write (writes, no confirmation needed). Scopes user-modify-playback-state. Calls POST /me/player/queue.

Arguments:

Also retrieved by: "play this one right after", "line this up next", "queue this song up".

spotify.get_queue

See the currently playing track and what's queued up to play next. Use when the user asks what's coming up next or what's in the queue.

Class read (reads only). Scopes user-read-playback-state. Calls GET /me/player/queue.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's coming up after this", "see what's next in line", "what's lined up to play".

spotify.get_playlist

Get details for one playlist by id: name, description, owner, track count, and public or collaborative flags. Use when the user names or links a specific playlist. For the actual tracks inside it, use get_playlist_items.

Class read (reads only). Scopes playlist-read-private. Calls GET /playlists/{{params.playlist_id}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "tell me about this collection", "who made this playlist", "how many songs are in this mix".

spotify.get_playlist_items

List the tracks inside a playlist, in playlist order. Use when the user wants to see, read, or browse what's in a playlist. For the playlist's own name and details rather than its contents, use get_playlist.

Class read (reads only). Scopes playlist-read-private. Calls GET /playlists/{{params.playlist_id}}/tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what songs are in this collection", "show me everything in this mix", "what's inside this playlist".

spotify.create_playlist

Create a new, empty playlist owned by a user. Use when the user wants to make, start, or set up a new playlist. Needs the owning user's id; get it from get_current_user_profile. Add songs afterward with add_items_to_playlist.

Class write (writes, no confirmation needed). Scopes playlist-modify-public, playlist-modify-private. Calls POST /users/{{params.user_id}}/playlists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new collection of songs", "make me a fresh mix", "set up a new song list".

spotify.add_items_to_playlist

Add one or more tracks to a playlist. Use when the user wants to add, put, or include a song in a playlist. Pass Spotify track URIs, e.g. "spotify:track:11dFghVXANMlKmJXsNCbNl". To remove tracks instead, use remove_items_from_playlist.

Class write (writes, no confirmation needed). Scopes playlist-modify-public, playlist-modify-private. Calls POST /playlists/{{params.playlist_id}}/tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "drop this song into my mix", "put this track in that collection", "toss this onto the playlist".

spotify.remove_items_from_playlist

Remove one or more tracks from a playlist. Use when the user wants to remove, delete, or take a song out of a playlist. Removes every occurrence of the track in the playlist. Undoable by adding it back with add_items_to_playlist.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes playlist-modify-public, playlist-modify-private. Calls DELETE /playlists/{{params.playlist_id}}/tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take this song out of the mix", "pull this track from that collection", "I don't want this one in the playlist anymore".

spotify.update_playlist_details

Change a playlist's name, description, or public and collaborative settings. Use when the user wants to rename or edit a playlist's details. Does not touch its tracks; for that use add_items_to_playlist or remove_items_from_playlist.

Class write (writes, no confirmation needed). Scopes playlist-modify-public, playlist-modify-private. Calls PUT /playlists/{{params.playlist_id}}.

Arguments:

Also retrieved by: "give this collection a new name", "change what this mix is called", "edit the blurb on this playlist".

spotify.follow_playlist

Follow a playlist, saving it to the user's own library. Use when the user wants to save, follow, or add someone else's playlist to their library. To save a track or album instead, use save_tracks or save_albums.

Class write (writes, no confirmation needed). Scopes playlist-modify-public, playlist-modify-private. Calls PUT /playlists/{{params.playlist_id}}/followers.

Arguments:

Also retrieved by: "save this mix to my library", "keep this collection in my account", "grab this playlist for myself".

spotify.unfollow_playlist

Unfollow a playlist, removing it from the user's library. Use when the user wants to remove, delete, or take a playlist out of their library. The playlist itself is not deleted for its other followers; follow_playlist reverses this.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes playlist-modify-public, playlist-modify-private. Calls DELETE /playlists/{{params.playlist_id}}/followers.

Arguments:

Also retrieved by: "take this collection off my account", "drop this mix from my library", "I don't want this playlist anymore".

spotify.get_saved_tracks

List tracks saved to the user's Liked Songs library, most recently added first. Use when the user asks what songs they've saved, liked, or added to their library. For one or two specific tracks, use check_saved_tracks.

Class read (reads only). Scopes user-library-read. Calls GET /me/tracks.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what's in my liked songs", "show my saved music", "what have I hearted".

spotify.save_tracks

Save one or more tracks to the user's Liked Songs library. Use when the user wants to like, save, or add a song to their library. Pass track ids comma separated. To remove one, use remove_saved_tracks.

Class write (writes, no confirmation needed). Scopes user-library-modify. Calls PUT /me/tracks.

Arguments:

Also retrieved by: "heart this song", "add this to my liked songs", "keep this track for later".

spotify.remove_saved_tracks

Remove one or more tracks from the user's Liked Songs library. Use when the user wants to unlike, unsave, or take a song out of their library. Pass track ids comma separated. Undoable with save_tracks.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes user-library-modify. Calls DELETE /me/tracks.

Arguments:

Also retrieved by: "unheart this song", "take this out of my liked songs", "stop keeping this track".

spotify.check_saved_tracks

Check whether specific tracks are already in the user's Liked Songs library. Use when the user asks if they've already saved or liked a song. Pass track ids comma separated; returns one true or false per id, in the same order.

Class read (reads only). Scopes user-library-read. Calls GET /me/tracks/contains.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did I already like this one", "is this already in my library", "have I saved this before".

spotify.get_saved_albums

List albums saved to the user's library, most recently added first. Use when the user asks what albums they've saved or added to their library. For individual saved songs rather than whole albums, use get_saved_tracks.

Class read (reads only). Scopes user-library-read. Calls GET /me/albums.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what records have I kept", "show the albums I've collected", "my saved full-length releases".

spotify.save_albums

Save one or more albums to the user's library. Use when the user wants to save or add a whole album to their library. Pass album ids comma separated. To remove one, use remove_saved_albums.

Class write (writes, no confirmation needed). Scopes user-library-modify. Calls PUT /me/albums.

Arguments:

Also retrieved by: "keep this whole record", "add this release to my collection", "hang on to this album".

spotify.remove_saved_albums

Remove one or more albums from the user's library. Use when the user wants to remove or take an album out of their saved library. Pass album ids comma separated. Undoable with save_albums.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes user-library-modify. Calls DELETE /me/albums.

Arguments:

Also retrieved by: "drop this record from my collection", "take this release out of my library", "stop keeping this album".

spotify.get_current_user_profile

Get the connected account's own Spotify profile: display name, email, country, and subscription plan. Use when the user asks about their own account, or when another tool needs the user's own id, like create_playlist.

Class read (reads only). Scopes user-read-email, user-read-private. Calls GET /me.

Takes no arguments.

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what account am I logged into", "my subscription plan", "my own account details".

spotify.get_user_top_items

Get the user's most listened-to artists or tracks over a time window. Use when the user asks what they listen to most, their top songs, or their top artists. item_type picks artists or tracks.

Class read (reads only). Scopes user-top-read. Calls GET /me/top/{{params.item_type}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what I've been listening to most", "my most played artists", "my heaviest rotation this year".

spotify.get_recently_played

List tracks the user recently played, most recent first. Use when the user asks what they just listened to or their play history. Not for what's on right now; for that use get_playback_state.

Class read (reads only). Scopes user-read-recently-played. Calls GET /me/player/recently-played.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "my listening history", "what I just had on", "what I listened to earlier today".

spotify.get_followed_artists

List the artists the user currently follows. Use when the user asks who they follow or which artists are in their following list. Spotify only supports listing followed artists, not followed users.

Class read (reads only). Scopes user-follow-read. Calls GET /me/following.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who am I subscribed to", "my followed musicians", "the acts I keep up with".

spotify.follow_artists_or_users

Follow one or more artists or Spotify users. Use when the user wants to follow, subscribe to, or start following an artist or another Spotify user. Set item_type and pass ids comma separated. To follow a playlist instead, use follow_playlist.

Class write (writes, no confirmation needed). Scopes user-follow-modify. Calls PUT /me/following.

Arguments:

Also retrieved by: "subscribe to this musician", "start keeping up with this act", "add this person to who I follow".

spotify.unfollow_artists_or_users

Unfollow one or more artists or Spotify users. Use when the user wants to unfollow, stop following, or remove an artist or user from who they follow. Set item_type and pass ids comma separated. Undoable with follow_artists_or_users.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes user-follow-modify. Calls DELETE /me/following.

Arguments:

Also retrieved by: "stop keeping up with this act", "drop this musician from who I follow", "unsubscribe from this person".