Spotify

Current playback

Fetch what is playing on Spotify right now: the track, the device it is on, playback progress, and shuffle / repeat state. Returns {"is_playing": false, "item": null} when nothing is active (no device running). Read-only.

Recently played

List the tracks the user most recently played, newest first, each with its played_at timestamp. Use for 'what was that song I played yesterday' style questions. Default 20, max 50. Read-only.

Search

Search the Spotify catalog for tracks, artists, albums, and / or playlists by free-text query. Returns trimmed results grouped by type, each carrying a Spotify URI you can pass to play, queue_track, save_to_liked, or add_to_playlist. Default type is just tracks. Read-only.

List playlists

List the user's playlists (owned and followed) with name, owner, track count, and the playlist id / URI needed by get_playlist_tracks and add_to_playlist. Use this to resolve a playlist the user names ('my running playlist') to its id. Default 50, max 50. Read-only.

Get playlist tracks

List the tracks in a specific playlist by playlist id. Get the id from list_playlists or search. Returns trimmed track summaries with their added_at timestamp. Default 50, max 100; use offset to page through long playlists. Read-only.

Top items

Fetch the user's top tracks or top artists over a time range: short_term (~4 weeks), medium_term (~6 months), or long_term (~1 year). Great for 'what have I been into lately' and building recommendations off real listening. Default 20, max 50. Read-only.

Get liked tracks

List the user's Liked Songs (saved tracks), newest first, each with the date it was saved. A strong taste signal for building recommendations and mixtapes off what the user has explicitly hearted. Default 50, max 50; use offset to page through a large library. Read-only.

Get followed artists

List the artists the user follows on Spotify. A deliberate taste signal (who they chose to follow), complementary to top_items (play-count driven) and get_liked_tracks. Default 50, max 50; this endpoint pages by cursor, so pass the returned _next_after value as `after` to fetch the next page. Read-only.

Play

Start or resume playback on the user's active Spotify device. With no arguments, resumes whatever is loaded. Pass context_uri to play an album, artist, or playlist (e.g. 'spotify:playlist:...'), or uris to play a specific list of tracks (e.g. ['spotify:track:...']). Get URIs from search. Requires an active device — if the user has no device running, tell them to open Spotify first. Write action.

Pause

Pause playback on the user's active Spotify device. Requires an active device. Write action.

Queue track

Add a track to the end of the playback queue on the active device. Pass the track's Spotify URI (from search). Requires an active device. Write action.

List devices

List the Spotify Connect devices available to the account, each with its id, name, type, and whether it's the active one. Use this to resolve a device the user names ('the family room speakers') to an id before play / transfer_playback. Note: Google Cast devices often appear with opaque hashed names instead of their friendly label, so match by name when you can and otherwise identify a device by which one is_active after the user starts it. Read-only.

Transfer playback

Move playback to a specific Spotify Connect device, optionally starting it. Pass the device id (from list_devices, or a saved device alias in your memory). Set play=true to start playing on it, false to just make it the active device. Returns status=device_not_found if the id is no longer available — when that happens, drop the stale saved alias and re-resolve via list_devices. Write action.

Save to liked

Add one or more tracks to the user's Liked Songs. Accepts track ids or full 'spotify:track:...' URIs from search or current_playback (URIs are normalized to ids automatically). Idempotent: re-saving an already-liked track is a no-op. Write action.

Remove from liked

Remove (unlike) one or more tracks from the user's Liked Songs. The counterpart to save_to_liked. Accepts track ids or full 'spotify:track:...' URIs from search, current_playback, or get_liked_tracks (URIs are normalized automatically). Idempotent: removing a track that isn't liked is a no-op. Reversible (the user can re-like), so no confirmation needed when the track is clear. Write action.

Add to playlist

Add one or more tracks to a playlist. Pass the playlist id (from list_playlists or search) and the track URIs (from search). Confirm the playlist and tracks with the user before calling — this modifies a playlist others may follow. Returns the playlist snapshot_id. Write action.

Create playlist

Create a new playlist for the user, optionally seeding it with tracks in one shot — the core 'make me a mixtape' action. Pass a name and optional description; the playlist is private by default (set public=true to make it shareable). Pass track_uris (from search) to populate it immediately, or omit them and add later with add_to_playlist. Confirm the name and the track list with the user before calling. Returns the new playlist's id and URI. Write action.

Update playlist

Update an existing playlist's details: rename it, change its description, or flip it between public and private. Pass the playlist id (from list_playlists or search) plus only the fields you want to change; omitted fields are left as-is. Does not touch the tracks — use add_to_playlist or remove_from_playlist for that. Confirm the change with the user before calling. Write action.

Remove from playlist

Remove one or more tracks from a playlist. Pass the playlist id (from list_playlists or search) and the track URIs to remove (from get_playlist_tracks or search); every occurrence of each is removed. Confirm the playlist and tracks with the user before calling — this modifies a playlist others may follow. Returns the playlist snapshot_id. Write action.

Delete playlist

Delete a playlist the user owns (Spotify removes it from their library by unfollowing it). Pass the playlist id from list_playlists or search. This is destructive and cannot be undone, so always confirm the exact playlist by name with the user before calling. Write action.