Using the Spotify integration
Send Spotify commands from your device. Command keys use the spotify.context.action form.
Contexts
Player
List available devices
Returns Spotify Connect devices available to the linked account.
spotify.player.list-devices
Request
{
"spotify.player.list-devices" : ""
}Example response
{
"spotify.player.list-devices.response" : {
"the id" : {
"volume" : 59,
"name" : "Kitchen speaker"
}
},
"endpointId" : "test-endpoint-id"
}Get playback state
Returns the current playback state.
spotify.player.get-state
Request
{
"spotify.player.get-state" : ""
}Example response
{
"spotify.player.get-state.response" : {
"isPlaying" : true,
"item" : {
"artist" : "Sample Artist",
"album" : "Sample Album",
"name" : "Sample Track"
},
"shuffling" : false,
"device" : {
"volumepercent" : 59,
"name" : "Kitchen speaker",
"id" : "string"
}
},
"endpointId" : "test-endpoint-id"
}Start playback
Starts playback on the active device.
spotify.player.play
Request
{
"spotify.player.play" : ""
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.play.response" : {
"result" : "OK"
}
}Play selected items
spotify.player.play-items starts the supplied album, artist, playlist, or track selection.
Request
{
"spotify.player.play-items" : "spotify:track:a single track"
}Example response
{
"spotify.player.play-items.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Get currently playing content
spotify.player.get-currently-playing returns the currently playing content.
Request
{
"spotify.player.get-currently-playing" : ""
}Example response
{
"spotify.player.get-currently-playing.response" : {
"isPlaying" : false,
"item" : {
"artist" : "Sample Artist",
"album" : "Sample Album",
"name" : "Sample Track"
},
"device" : {
"volumepercent" : 59,
"name" : "Kitchen speaker",
"id" : "string"
}
},
"endpointId" : "test-endpoint-id"
}Start playback on a device
spotify.player.play-on-device starts playback on a selected device.
Request
{
"spotify.player.play-on-device" : "the id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.play-on-device.response" : {
"result" : "OK"
}
}Skip to the next track
spotify.player.next skips to the next track.
Request
{
"spotify.player.next" : ""
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.next.response" : {
"result" : "OK"
}
}Skip to the previous track
spotify.player.previous skips to the previous track.
Request
{
"spotify.player.previous" : ""
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.previous.response" : {
"result" : "OK"
}
}Pause playback
spotify.player.pause pauses playback.
Request
{
"spotify.player.pause" : ""
}Example response
{
"spotify.player.pause.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Stop playback
spotify.player.stop stops playback.
Request
{
"spotify.player.stop" : ""
}Example response
{
"spotify.player.stop.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Set playback volume
spotify.player.set-volume sets the playback volume.
Request
{
"spotify.player.set-volume" : "12"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.set-volume.response" : {
"result" : "OK"
}
}Set shuffle
spotify.player.set-shuffle sets shuffle playback.
Request
{
"spotify.player.set-shuffle" : "on"
}Example response
{
"spotify.player.set-shuffle.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Set repeat
spotify.player.set-repeat sets repeat playback.
Request
{
"spotify.player.set-repeat" : "track"
}Example response
{
"spotify.player.set-repeat.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Transfer playback
spotify.player.transfer transfers playback between devices.
Request
{
"spotify.player.transfer" : "{\"device_ids\":[\"device-id\"],\"play\":true}"
}Example response
{
"spotify.player.transfer.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Seek playback
spotify.player.seek seeks to a playback position.
Request
{
"spotify.player.seek" : "position_ms=120000"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.seek.response" : {
"result" : "OK"
}
}List recently played tracks
spotify.player.list-recently-played returns recently played tracks.
Request
{
"spotify.player.list-recently-played" : "limit=5"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.player.list-recently-played.response" : {
"result" : {
"items" : [ {
"track" : {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
}
} ]
}
}
}Get the queue
spotify.queue.get returns the current playback queue.
Request
{
"spotify.queue.get" : ""
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.queue.get.response" : {
"result" : {
"currently_playing" : {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
},
"queue" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
} ]
}
}
}Add a queue item
spotify.queue.add adds an item to the playback queue.
Request
{
"spotify.queue.add" : "uri=spotify:track:track-id"
}Example response
{
"spotify.queue.add.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Albums
Get an album
Returns an album identified by its Spotify ID.
spotify.albums.get
Request
{
"spotify.albums.get" : "album-id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.albums.get.response" : {
"result" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ],
"tracks" : null,
"copyrights" : [ ],
"external_ids" : null,
"genres" : [ ],
"label" : null,
"popularity" : null
}
}
}Get multiple albums
Returns albums for explicitly supplied Spotify IDs.
spotify.albums.get-many
Request
{
"spotify.albums.get-many" : "ids=album-1,album-2"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.albums.get-many.response" : {
"result" : {
"albums" : [ {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-1",
"images" : [ ],
"name" : "Morning Drive",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ],
"tracks" : null,
"copyrights" : [ ],
"external_ids" : null,
"genres" : [ ],
"label" : null,
"popularity" : null
}, {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-2",
"images" : [ ],
"name" : "Evening Chill",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ],
"tracks" : null,
"copyrights" : [ ],
"external_ids" : null,
"genres" : [ ],
"label" : null,
"popularity" : null
} ]
}
}
}List album tracks
Returns tracks belonging to an album.
spotify.albums.list-tracks
Request
{
"spotify.albums.list-tracks" : "album-id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.albums.list-tracks.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
} ]
}
}
}List saved albums
spotify.saved-albums.list returns the current user’s saved albums.
Request
{
"spotify.saved-albums.list" : "limit=2"
}Example response
{
"spotify.saved-albums.list.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ],
"tracks" : null,
"copyrights" : [ ],
"external_ids" : null,
"genres" : [ ],
"label" : null,
"popularity" : null
}
} ]
}
},
"endpointId" : "test-endpoint-id"
}Save albums
spotify.saved-albums.save saves albums for the current user.
Request
{
"spotify.saved-albums.save" : "[\"album-id\"]"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.saved-albums.save.response" : {
"result" : "OK"
}
}Remove saved albums
spotify.saved-albums.remove removes saved albums.
Request
{
"spotify.saved-albums.remove" : "[\"album-id\"]"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.saved-albums.remove.response" : {
"result" : "OK"
}
}Check saved albums
spotify.saved-albums.check checks whether albums are saved.
Request
{
"spotify.saved-albums.check" : "ids=album-id"
}Example response
{
"spotify.saved-albums.check.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}List new releases
spotify.albums.list-new-releases returns new album releases.
Request
{
"spotify.albums.list-new-releases" : "country=US"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.albums.list-new-releases.response" : {
"result" : {
"albums" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
} ]
}
}
}
}Artists
Get an artist
spotify.artists.get returns an artist by Spotify ID.
Request
{
"spotify.artists.get" : "artist-id"
}Example response
{
"spotify.artists.get.response" : {
"result" : {
"genres" : [ ],
"id" : "artist-id",
"images" : [ ],
"name" : "Sample Artist"
}
},
"endpointId" : "test-endpoint-id"
}Get multiple artists
spotify.artists.get-many returns artists for supplied IDs.
Request
{
"spotify.artists.get-many" : "ids=artist-1,artist-2"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.artists.get-many.response" : {
"result" : {
"artists" : [ {
"genres" : [ ],
"id" : "artist-1",
"images" : [ ],
"name" : "Headliner"
}, {
"genres" : [ ],
"id" : "artist-2",
"images" : [ ],
"name" : "Support Act"
} ]
}
}
}List artist albums
spotify.artists.list-albums returns an artist’s albums.
Request
{
"spotify.artists.list-albums" : "artist-id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.artists.list-albums.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
} ]
}
}
}List artist top tracks
spotify.artists.list-top-tracks returns an artist’s top tracks.
Request
{
"spotify.artists.list-top-tracks" : "artist-id/top-tracks?market=US"
}Example response
{
"spotify.artists.list-top-tracks.response" : {
"result" : {
"tracks" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-1",
"name" : "Main Hit"
}, {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-2",
"name" : "Deep Cut"
} ]
}
},
"endpointId" : "test-endpoint-id"
}List followed artists
spotify.artists.list-followed returns artists followed by the current user.
Request
{
"spotify.artists.list-followed" : "type=artist&limit=5"
}Example response
{
"spotify.artists.list-followed.response" : {
"result" : {
"artists" : {
"items" : [ {
"genres" : [ ],
"id" : "artist-id",
"images" : [ ],
"name" : "Followed Artist"
} ]
}
}
},
"endpointId" : "test-endpoint-id"
}Audiobooks
Get an audiobook
spotify.audiobooks.get returns an audiobook by Spotify ID.
Request
{
"spotify.audiobooks.get" : "audiobook-id"
}Example response
{
"spotify.audiobooks.get.response" : {
"result" : {
"authors" : [ ],
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "audiobook-id",
"images" : [ ],
"languages" : [ ],
"media_type" : null,
"name" : "Sample Audiobook",
"narrators" : [ ],
"publisher" : null,
"type" : null,
"uri" : null,
"total_chapters" : null,
"chapters" : null
}
},
"endpointId" : "test-endpoint-id"
}Get multiple audiobooks
spotify.audiobooks.get-many returns audiobooks for supplied IDs.
Request
{
"spotify.audiobooks.get-many" : "ids=book-1,book-2"
}Example response
{
"spotify.audiobooks.get-many.response" : {
"result" : {
"audiobooks" : [ {
"authors" : [ ],
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "book-1",
"images" : [ ],
"languages" : [ ],
"media_type" : null,
"name" : "Morning Stories",
"narrators" : [ ],
"publisher" : null,
"type" : null,
"uri" : null,
"total_chapters" : null,
"chapters" : null
}, {
"authors" : [ ],
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "book-2",
"images" : [ ],
"languages" : [ ],
"media_type" : null,
"name" : "Evening Stories",
"narrators" : [ ],
"publisher" : null,
"type" : null,
"uri" : null,
"total_chapters" : null,
"chapters" : null
} ]
}
},
"endpointId" : "test-endpoint-id"
}List audiobook chapters
spotify.audiobooks.list-chapters returns an audiobook’s chapters.
Request
{
"spotify.audiobooks.list-chapters" : "audiobook-id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.audiobooks.list-chapters.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"audio_preview_url" : null,
"available_markets" : [ ],
"chapter_number" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "chapter-id",
"images" : [ ],
"is_playable" : null,
"languages" : [ ],
"name" : "Opening Chapter",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null
} ]
}
}
}List saved audiobooks
spotify.saved-audiobooks.list returns the current user’s saved audiobooks.
Request
{
"spotify.saved-audiobooks.list" : "limit=5"
}Example response
{
"spotify.saved-audiobooks.list.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"audiobook" : {
"authors" : [ ],
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "audiobook-id",
"images" : [ ],
"languages" : [ ],
"media_type" : null,
"name" : "Sample Audiobook",
"narrators" : [ ],
"publisher" : null,
"type" : null,
"uri" : null,
"total_chapters" : null,
"chapters" : null
}
} ]
}
},
"endpointId" : "test-endpoint-id"
}Save audiobooks
spotify.saved-audiobooks.save saves audiobooks for the current user.
Request
{
"spotify.saved-audiobooks.save" : "[\"audiobook-id\"]"
}Example response
{
"spotify.saved-audiobooks.save.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Remove saved audiobooks
spotify.saved-audiobooks.remove removes audiobooks saved by the current user.
Request
{
"spotify.saved-audiobooks.remove" : "[\"audiobook-id\"]"
}Example response
{
"spotify.saved-audiobooks.remove.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Check saved audiobooks
spotify.saved-audiobooks.check checks whether audiobooks are saved.
Request
{
"spotify.saved-audiobooks.check" : "ids=audiobook-id"
}Example response
{
"spotify.saved-audiobooks.check.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}Categories
List categories
spotify.categories.list returns available browse categories.
Request
Unresolved directive in spotify-request-response.adoc - include::/home/jenkins/workspace/efer-grafana-org-to-oauth-signup/soren-app/target/generated-snippets/spotify/categories-list—get-several-browse-categories/request-body.adoc[]
Example response
Unresolved directive in spotify-request-response.adoc - include::/home/jenkins/workspace/efer-grafana-org-to-oauth-signup/soren-app/target/generated-snippets/spotify/categories-list—get-several-browse-categories/response-body.adoc[]
Get a category
spotify.categories.get returns a browse category by ID.
Request
{
"spotify.categories.get" : "category-id"
}Example response
{
"spotify.categories.get.response" : {
"result" : {
"href" : null,
"icons" : [ ],
"id" : "category-id",
"name" : "Party Time"
}
},
"endpointId" : "test-endpoint-id"
}Chapters
Get a chapter
spotify.chapters.get returns a chapter by Spotify ID.
Request
{
"spotify.chapters.get" : "chapter-id"
}Example response
{
"spotify.chapters.get.response" : {
"result" : {
"audio_preview_url" : null,
"available_markets" : [ ],
"chapter_number" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "chapter-id",
"images" : [ ],
"is_playable" : null,
"languages" : [ ],
"name" : "Opening Chapter",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"audiobook" : null
}
},
"endpointId" : "test-endpoint-id"
}Get multiple chapters
spotify.chapters.get-many returns chapters for supplied IDs.
Request
{
"spotify.chapters.get-many" : "ids=chapter-1,chapter-2"
}Example response
{
"spotify.chapters.get-many.response" : {
"result" : {
"chapters" : [ {
"audio_preview_url" : null,
"available_markets" : [ ],
"chapter_number" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "chapter-1",
"images" : [ ],
"is_playable" : null,
"languages" : [ ],
"name" : "Introduction",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"audiobook" : null
}, {
"audio_preview_url" : null,
"available_markets" : [ ],
"chapter_number" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "chapter-2",
"images" : [ ],
"is_playable" : null,
"languages" : [ ],
"name" : "Deep Dive",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"audiobook" : null
} ]
}
},
"endpointId" : "test-endpoint-id"
}Episodes
Get an episode
spotify.episodes.get returns an episode by Spotify ID.
Request
{
"spotify.episodes.get" : "episode-id"
}Example response
{
"spotify.episodes.get.response" : {
"result" : {
"audio_preview_url" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "episode-id",
"images" : [ ],
"is_externally_hosted" : null,
"is_playable" : null,
"languages" : [ ],
"name" : "Sample Episode",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"show" : null
}
},
"endpointId" : "test-endpoint-id"
}Get multiple episodes
spotify.episodes.get-many returns episodes for supplied IDs.
Request
{
"spotify.episodes.get-many" : "ids=episode-1,episode-2"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.episodes.get-many.response" : {
"result" : {
"episodes" : [ {
"audio_preview_url" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "episode-1",
"images" : [ ],
"is_externally_hosted" : null,
"is_playable" : null,
"languages" : [ ],
"name" : "Chapter One",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"show" : null
}, {
"audio_preview_url" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "episode-2",
"images" : [ ],
"is_externally_hosted" : null,
"is_playable" : null,
"languages" : [ ],
"name" : "Chapter Two",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"show" : null
} ]
}
}
}List saved episodes
spotify.saved-episodes.list returns the current user’s saved episodes.
Request
{
"spotify.saved-episodes.list" : "limit=1"
}Example response
{
"spotify.saved-episodes.list.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"episode" : {
"audio_preview_url" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "episode-id",
"images" : [ ],
"is_externally_hosted" : null,
"is_playable" : null,
"languages" : [ ],
"name" : "Sample Episode",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"show" : null
}
} ]
}
},
"endpointId" : "test-endpoint-id"
}Save episodes
spotify.saved-episodes.save saves episodes for the current user.
Request
{
"spotify.saved-episodes.save" : "[\"episode-id\"]"
}Example response
{
"spotify.saved-episodes.save.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Remove saved episodes
spotify.saved-episodes.remove removes episodes saved by the current user.
Request
{
"spotify.saved-episodes.remove" : "[\"episode-id\"]"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.saved-episodes.remove.response" : {
"result" : "OK"
}
}Check saved episodes
spotify.saved-episodes.check checks whether episodes are saved.
Request
{
"spotify.saved-episodes.check" : "ids=episode-id"
}Example response
{
"spotify.saved-episodes.check.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}Genres
List genre seeds
spotify.genres.list-seeds returns available recommendation genre seeds.
Request
{
"spotify.genres.list-seeds" : ""
}Example response
{
"spotify.genres.list-seeds.response" : {
"result" : {
"genres" : [ "alternative", "samba" ]
}
},
"endpointId" : "test-endpoint-id"
}Playlists
Get a playlist
spotify.playlists.get
Request
{
"spotify.playlists.get" : "playlist-id"
}Example response
{
"spotify.playlists.get.response" : {
"result" : {
"id" : "playlist-id",
"images" : [ ],
"name" : "Sample Playlist"
}
},
"endpointId" : "test-endpoint-id"
}Update playlist details
spotify.playlists.update-details
Request
{
"spotify.playlists.update-details" : "playlist-id||{\"name\":\"Road Trip\"}"
}Example response
{
"spotify.playlists.update-details.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}List playlist items
spotify.playlists.list-items
Request
{
"spotify.playlists.list-items" : "playlist-id/tracks?limit=10"
}Example response
{
"spotify.playlists.list-items.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"track" : {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-1",
"name" : "Sample Track"
}
} ]
}
},
"endpointId" : "test-endpoint-id"
}Update playlist items
spotify.playlists.update-items
Request
{
"spotify.playlists.update-items" : "playlist-id||{\"uris\":[\"spotify:track:1\"]}"
}Example response
{
"spotify.playlists.update-items.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Add playlist items
spotify.playlists.add-items
Request
{
"spotify.playlists.add-items" : "playlist-id||{\"uris\":[\"spotify:track:1\"]}"
}Example response
{
"spotify.playlists.add-items.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Remove playlist items
spotify.playlists.remove-items
Request
{
"spotify.playlists.remove-items" : "playlist-id||{\"tracks\":[{\"uri\":\"spotify:track:1\"}]}"
}Example response
{
"spotify.playlists.remove-items.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}List current user’s playlists
spotify.playlists.list-current-user
Request
{
"spotify.playlists.list-current-user" : "limit=5"
}Example response
{
"spotify.playlists.list-current-user.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"id" : "playlist-1",
"images" : [ ],
"name" : "Daily Mix"
} ]
}
},
"endpointId" : "test-endpoint-id"
}List a user’s playlists
spotify.playlists.list-user
Request
{
"spotify.playlists.list-user" : "user-id/playlists?limit=5"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.playlists.list-user.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"id" : "playlist-2",
"images" : [ ],
"name" : "Road Trip"
} ]
}
}
}Create a playlist
spotify.playlists.create
Request
{
"spotify.playlists.create" : "user-id||{\"name\":\"Chill\"}"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.playlists.create.response" : {
"result" : {
"id" : "playlist-id",
"images" : [ ],
"name" : "Chill"
}
}
}List featured playlists
spotify.playlists.list-featured
Request
{
"spotify.playlists.list-featured" : "country=US"
}Example response
{
"spotify.playlists.list-featured.response" : {
"result" : {
"playlists" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"id" : "playlist-id",
"images" : [ ],
"name" : "Featured Picks"
} ]
}
}
},
"endpointId" : "test-endpoint-id"
}List a category’s playlists
spotify.playlists.list-category
Request
{
"spotify.playlists.list-category" : "category-id/playlists?limit=10"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.playlists.list-category.response" : {
"result" : {
"playlists" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"id" : "playlist-id",
"images" : [ ],
"name" : "Category Mix"
} ]
}
}
}
}Follow a playlist
spotify.playlists.follow
Request
{
"spotify.playlists.follow" : "playlist-id||{\"public\":false}"
}Example response
{
"spotify.playlists.follow.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Unfollow a playlist
spotify.playlists.unfollow
Request
{
"spotify.playlists.unfollow" : "playlist-id"
}Example response
{
"spotify.playlists.unfollow.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Check playlist following
spotify.playlists.check-following
Request
{
"spotify.playlists.check-following" : "playlist-id/followers/contains?ids=user-id"
}Example response
{
"spotify.playlists.check-following.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}Get a playlist cover
spotify.playlist-covers.get
Request
{
"spotify.playlist-covers.get" : "playlist-id"
}Example response
{
"spotify.playlist-covers.get.response" : {
"result" : [ {
"url" : "https://image",
"height" : null,
"width" : null
} ]
},
"endpointId" : "test-endpoint-id"
}Add a playlist cover
spotify.playlist-covers.add
Request
{
"spotify.playlist-covers.add" : "playlist-id||BASE64DATA"
}Example response
{
"spotify.playlist-covers.add.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Search
Search Spotify
spotify.search.search searches Spotify content.
Request
{
"spotify.search.search" : "type=track&q=hello"
}Example response
{
"spotify.search.search.response" : {
"result" : {
"tracks" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Hello World"
} ]
}
}
},
"endpointId" : "test-endpoint-id"
}Shows
Get a show
spotify.shows.get returns a show by Spotify ID.
Request
{
"spotify.shows.get" : "show-id"
}Example response
{
"spotify.shows.get.response" : {
"result" : {
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "show-id",
"images" : [ ],
"is_externally_hosted" : null,
"languages" : [ ],
"media_type" : null,
"name" : "Sample Show",
"publisher" : null,
"type" : null,
"uri" : null,
"total_episodes" : null,
"episodes" : null
}
},
"endpointId" : "test-endpoint-id"
}Get multiple shows
spotify.shows.get-many returns shows for supplied IDs.
Request
{
"spotify.shows.get-many" : "ids=show-1,show-2"
}Example response
{
"spotify.shows.get-many.response" : {
"result" : {
"shows" : [ {
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "show-1",
"images" : [ ],
"is_externally_hosted" : null,
"languages" : [ ],
"media_type" : null,
"name" : "Morning Show",
"publisher" : null,
"type" : null,
"uri" : null,
"total_episodes" : null,
"episodes" : null
}, {
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "show-2",
"images" : [ ],
"is_externally_hosted" : null,
"languages" : [ ],
"media_type" : null,
"name" : "Night Show",
"publisher" : null,
"type" : null,
"uri" : null,
"total_episodes" : null,
"episodes" : null
} ]
}
},
"endpointId" : "test-endpoint-id"
}List show episodes
spotify.shows.list-episodes returns episodes for a show.
Request
{
"spotify.shows.list-episodes" : "show-id/episodes?market=US"
}Example response
{
"spotify.shows.list-episodes.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"audio_preview_url" : null,
"description" : null,
"html_description" : null,
"duration_ms" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "episode-id",
"images" : [ ],
"is_externally_hosted" : null,
"is_playable" : null,
"languages" : [ ],
"name" : "Pilot Episode",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null
} ]
}
},
"endpointId" : "test-endpoint-id"
}List saved shows
spotify.saved-shows.list returns the current user’s saved shows.
Request
{
"spotify.saved-shows.list" : "limit=3"
}Example response
{
"spotify.saved-shows.list.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"show" : {
"available_markets" : [ ],
"copyrights" : [ ],
"description" : null,
"html_description" : null,
"explicit" : null,
"external_urls" : null,
"href" : null,
"id" : "show-id",
"images" : [ ],
"is_externally_hosted" : null,
"languages" : [ ],
"media_type" : null,
"name" : "Sample Show",
"publisher" : null,
"type" : null,
"uri" : null,
"total_episodes" : null
}
} ]
}
},
"endpointId" : "test-endpoint-id"
}Save shows
spotify.saved-shows.save saves shows for the current user.
Request
{
"spotify.saved-shows.save" : "[\"show-id\"]"
}Example response
{
"spotify.saved-shows.save.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Remove saved shows
spotify.saved-shows.remove removes shows saved by the current user.
Request
{
"spotify.saved-shows.remove" : "[\"show-id\"]"
}Example response
{
"spotify.saved-shows.remove.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Check saved shows
spotify.saved-shows.check checks whether shows are saved.
Request
{
"spotify.saved-shows.check" : "ids=show-id"
}Example response
{
"spotify.saved-shows.check.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}Tracks
Get a track
spotify.tracks.get returns a track by Spotify ID.
Request
{
"spotify.tracks.get" : "track-id"
}Example response
{
"spotify.tracks.get.response" : {
"result" : {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
}
},
"endpointId" : "test-endpoint-id"
}Get multiple tracks
spotify.tracks.get-many returns tracks for supplied IDs.
Request
{
"spotify.tracks.get-many" : "ids=track-1,track-2"
}Example response
{
"spotify.tracks.get-many.response" : {
"result" : {
"tracks" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-1",
"name" : "First Track"
}, {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-2",
"name" : "Second Track"
} ]
}
},
"endpointId" : "test-endpoint-id"
}Like the current track
spotify.tracks.like-current saves the current track.
Request
{
"spotify.tracks.like-current" : ""
}Example response
{
"spotify.tracks.like-current.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Unlike the current track
spotify.tracks.unlike-current removes the current track from saved tracks.
Request
{
"spotify.tracks.unlike-current" : ""
}Example response
{
"spotify.tracks.unlike-current.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}List saved tracks
spotify.saved-tracks.list returns the current user’s saved tracks.
Request
{
"spotify.saved-tracks.list" : "limit=1"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.saved-tracks.list.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"track" : {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Sample Track"
}
} ]
}
}
}Save tracks
spotify.saved-tracks.save saves tracks for the current user.
Request
{
"spotify.saved-tracks.save" : "[\"track-id\"]"
}Example response
{
"spotify.saved-tracks.save.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Remove saved tracks
spotify.saved-tracks.remove removes saved tracks.
Request
{
"spotify.saved-tracks.remove" : "[\"track-id\"]"
}Example response
{
"spotify.saved-tracks.remove.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Check saved tracks
spotify.saved-tracks.check checks whether tracks are saved.
Request
{
"spotify.saved-tracks.check" : "ids=track-id"
}Example response
{
"spotify.saved-tracks.check.response" : {
"result" : [ true ]
},
"endpointId" : "test-endpoint-id"
}Get track audio features
spotify.audio-features.get returns audio features for one track.
Request
{
"spotify.audio-features.get" : "track-id"
}Example response
{
"spotify.audio-features.get.response" : {
"result" : {
"id" : "track-id",
"tempo" : 123.0
}
},
"endpointId" : "test-endpoint-id"
}Get multiple track audio features
spotify.audio-features.get-many returns audio features for supplied tracks.
Request
{
"spotify.audio-features.get-many" : "ids=track-1,track-2"
}Example response
{
"spotify.audio-features.get-many.response" : {
"result" : {
"audio_features" : [ {
"id" : "track-1",
"tempo" : 120.0
}, {
"id" : "track-2",
"tempo" : 128.0
} ]
}
},
"endpointId" : "test-endpoint-id"
}Get track audio analysis
spotify.audio-analysis.get returns audio analysis for a track.
Request
{
"spotify.audio-analysis.get" : "track-id"
}Example response
{
"endpointId" : "test-endpoint-id",
"spotify.audio-analysis.get.response" : {
"result" : {
"bars" : [ ],
"beats" : [ ],
"sections" : [ ],
"segments" : [ ],
"tatums" : [ ]
}
}
}List recommendations
spotify.recommendations.list returns track recommendations.
Request
{
"spotify.recommendations.list" : "seed_tracks=track-1"
}Example response
{
"spotify.recommendations.list.response" : {
"result" : {
"seeds" : [ ],
"tracks" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-1",
"name" : "First Track"
} ]
}
},
"endpointId" : "test-endpoint-id"
}Users
Get the current user
spotify.users.get-current returns the current user’s profile.
Request
{
"spotify.users.get-current" : ""
}Example response
{
"spotify.users.get-current.response" : {
"result" : {
"display_name" : "Sample User",
"id" : "user-id",
"images" : [ ]
}
},
"endpointId" : "test-endpoint-id"
}Get a user
spotify.users.get returns a user’s public profile.
Request
{
"spotify.users.get" : "user-id"
}Example response
{
"spotify.users.get.response" : {
"result" : {
"display_name" : "Public User",
"id" : "user-id",
"images" : [ ]
}
},
"endpointId" : "test-endpoint-id"
}List top items
spotify.users.list-top-items returns the current user’s top items.
Request
{
"spotify.users.list-top-items" : "tracks?limit=5"
}Example response
{
"spotify.users.list-top-items.response" : {
"result" : {
"href" : null,
"limit" : null,
"next" : null,
"offset" : null,
"previous" : null,
"total" : null,
"items" : [ {
"album" : {
"album_type" : null,
"total_tracks" : null,
"available_markets" : [ ],
"external_urls" : null,
"href" : null,
"id" : "album-id",
"images" : [ ],
"name" : "Sample Album",
"release_date" : null,
"release_date_precision" : null,
"type" : null,
"uri" : null,
"artists" : [ ]
},
"artists" : [ {
"id" : "artist-id",
"name" : "Sample Artist"
} ],
"available_markets" : [ ],
"id" : "track-id",
"name" : "Top Track"
} ]
}
},
"endpointId" : "test-endpoint-id"
}Follow artists or users
spotify.users.follow follows artists or users.
Request
{
"spotify.users.follow" : "type=artist&ids=artist-id"
}Example response
{
"spotify.users.follow.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Unfollow artists or users
spotify.users.unfollow unfollows artists or users.
Request
{
"spotify.users.unfollow" : "type=user&ids=user-id"
}Example response
{
"spotify.users.unfollow.response" : {
"result" : "OK"
},
"endpointId" : "test-endpoint-id"
}Check user following
spotify.users.check-following checks whether artists or users are followed.
Request
{
"spotify.users.check-following" : "type=artist&ids=artist-id"
}Example response
{
"spotify.users.check-following.response" : {
"result" : [ false ]
},
"endpointId" : "test-endpoint-id"
}Deprecated commands
Deprecated aliases remain available during the compatibility window. Their responses retain the deprecated response key. Each alias has generated REST Docs snippets named after the normalized alias plus -deprecated; migrate to the canonical command listed in its context above.