Spotify Web API
Search Spotify's catalog, sign users in with PKCE, read their library, build playlists and control playback.
Media & contentGuided#music#podcasts#oauth2#pkce#playlists#playback
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Spotify Web API gives your app Spotify's music and podcast catalog (search, tracks, albums, artists, shows) and, with the listener's permission, their profile, library, playlists and playback. This guided collection covers the requests a new app can actually use today, in the order you need them.
Access for new apps (read this first)
Spotify has narrowed what development-mode apps can call twice:
- November 2024: related artists, recommendations, audio features, audio analysis, featured and category playlists, preview URLs in multi-item responses, and Spotify's own editorial and algorithmic playlists were closed to new apps.
- February 2026: development-mode apps need an owner with Spotify Premium, allow five signed-in users, and lost the batch lookups, artist top tracks, new releases, browse categories, other users' profiles and playlists, and several fields (popularity, available markets, email, country). Playlist contents moved to
/playlists/{id}/items, and saving/following is now onePUT /me/libraryendpoint. Search returns at most 10 results per type.
Apps with extended quota keep the older behaviour, but since May 2025 only established organizations can apply. This collection uses only endpoints listed as still available on the February 2026 changelog.
Get credentials
- Sign in at the Developer Dashboard with a Spotify account (Premium is needed for development-mode apps to work).
- Create app: give it a name and description, add a redirect URI such as
http://127.0.0.1:8080/callback(HTTPS, or HTTP only on a loopback IP;localhostis refused), and tick Web API. - Open the app's Settings to copy the Client ID and Client Secret.
- Under User Management, add the Spotify accounts that will sign in to your app while it is in development mode.
Authentication
Every call sends Authorization: Bearer <access token> to https://api.spotify.com/v1. Two ways to get a token from https://accounts.spotify.com/api/token:
- Client credentials (folder 1): your Client ID and Secret as HTTP Basic auth,
grant_type=client_credentials. Catalog data only. - Authorization code with PKCE (folder 3): the user signs in in a browser and grants scopes; you exchange the returned code plus your code verifier for a user token and a refresh token. Required for profile, library, playlists and player.
Using this collection
Fill clientId and clientSecret, run folder 1, then folder 2 (search fills the IDs). For user data, follow folder 3's steps, then folders 4-6. Test scripts copy tokens and IDs into variables for you.
Common errors
| Status | Meaning | What to do |
|---|---|---|
| 400 | Bad parameter or ID | Check IDs are 22-character Spotify IDs; search limit is 0-10. |
| 401 | Token missing or expired | Get a new app token or refresh the user token. |
| 403 | Not allowed | User not on the development-mode allowlist, scope not granted, free account on a player command, or an endpoint your app cannot use. |
| 404 | Not found | Unknown ID, or no active device for a player command. |
| 429 | Rate limit or quota | Wait for Retry-After seconds. A body reason of QUOTA_EXCEEDED means your account's development-mode quota is used up. |
Limits and pricing
The Web API is free to use under the Developer Terms and Developer Policy (no downloading, no training models on Spotify content). Rate limits are a rolling window and quotas are shared across all development-mode apps on one account; see Rate limits and Quota modes.
Official docs
Endpoints 25
1. Start here: app token
- POSTGet an app token (client credentials)
{{accountsUrl}}/api/tokenExchanges your app's Client ID and Client Secret for a short-lived access token. When: first, and again whenever catalog calls start returning 401 (the token…
2. Catalog (app token)
- GETSearch the catalog
/searchFinds tracks, artists, albums, playlists, shows, episodes or audiobooks by keyword. What comes back: one paging object per requested type (tracks, artists,… - GETGet a track
/tracks/{{trackId}}Returns one track: name, duration, explicit flag, album, artists, ISRC (external_ids), and URI. Set first: trackId (filled by the search request, or paste the… - GETGet an album
/albums/{{albumId}}Returns one album with its artists, release date, cover images and the first page of tracks (tracks.items). Set first: albumId (filled by the search request).… - GETGet an album's tracks
/albums/{{albumId}}/tracksPages through every track on an album when you need more than the first page that "Get an album" includes. What comes back: a paging object of simplified… - GETGet an artist
/artists/{{artistId}}Returns one artist: name, genres, images and URI. Set first: artistId (filled by the search request). followers and popularity were removed for… - GETGet an artist's albums
/artists/{{artistId}}/albumsLists an artist's releases, newest first. This is the way to build an artist page now that top tracks is no longer available to development-mode apps. What…
3. User sign-in (authorization code + PKCE)
- POSTExchange the code for a user token
{{accountsUrl}}/api/tokenTurns the one-time code from the browser redirect into a user access token and a refresh token. No client secret is sent with PKCE. The test script stores… - POSTRefresh the user token
{{accountsUrl}}/api/tokenGets a new user access token without asking the user to sign in again. Run it when user requests start returning 401. What comes back: a new access_token, and…
4. The signed-in user
- GETGet my profile
/meReturns the signed-in user's public profile. Scope: none is needed for the basic profile. What comes back: id, display_name, images, uri, and account_id, a… - GETGet my top tracks
/me/top/tracksThe user's most played tracks (use artists instead of tracks in the path for top artists). Scope: user-top-read. A brand-new account may return an empty list. - GETGet my saved tracks
/me/tracksLists the tracks in the user's Liked Songs, most recently saved first. Scope: user-library-read. What comes back: a paging object; each item has added_at and… - PUTSave items to my library
/me/librarySaves tracks, albums, episodes, shows or audiobooks to the user's library, follows artists, users or playlists: all through one endpoint, by Spotify URI.… - DELETERemove items from my library
/me/libraryThe reverse of "Save items to my library": removes saved items and unfollows artists, users or playlists, by URI. Same scopes as saving. A 200 with an empty…
5. Playlists
- GETList my playlists
/me/playlistsPlaylists the user owns or follows. Scope: playlist-read-private (and playlist-read-collaborative to include collaborative ones). - POSTCreate a playlist
/me/playlistsCreates an empty playlist for the signed-in user. Scopes: playlist-modify-public and/or playlist-modify-private. What comes back: 201 with the new playlist;… - POSTAdd items to a playlist
/playlists/{{playlistId}}/itemsAdds tracks or episodes to a playlist the user can edit. Set first: playlistId (from "Create a playlist") and trackId (from search). What comes back: 201 with… - GETGet a playlist
/playlists/{{playlistId}}Returns a playlist's details: name, description, owner, images, snapshot_id and, for playlists the user owns or collaborates on, the first page of items.… - GETGet a playlist's items
/playlists/{{playlistId}}/itemsPages through a playlist's tracks and episodes. Works only for playlists the user owns or collaborates on; others return 403. Scope: playlist-read-private.…
6. Player (Premium)
- GETGet available devices
/me/player/devicesLists the user's Spotify Connect devices (phone, computer, speaker) that are online. Scope: user-read-playback-state. What comes back: devices, each with id,… - GETGet playback state
/me/playerReturns the full playback state: active device, shuffle and repeat state, progress and the current item. Scope: user-read-playback-state. When no device is… - GETGet the currently playing item
/me/player/currently-playingJust what is playing right now, lighter than "Get playback state". Scope: user-read-currently-playing. What comes back: is_playing, progress_ms,… - PUTStart or resume playback
/me/player/playStarts playing on a device, or resumes what was paused when the body is empty. device_id (query) picks the device; leave it out to use the active one. Scope:… - PUTPause playback
/me/player/pausePauses the user's playback. device_id (query) is optional; leave it out to pause the active device. Scope: user-modify-playback-state. Premium only. What… - POSTSkip to the next item
/me/player/nextSkips to the next track or episode in the user's queue. device_id (query) is optional. Scope: user-modify-playback-state. Premium only. What comes back: 204…
API details
- Base URL
https://api.spotify.com/v1https://accounts.spotify.com- Authentication
- A bearer token in the Authorization header
OAuth 2.0 (client credentials, authorization code flows) - Operations
- 25 operations on 25 pathsGET 15POST 6PUT 3DELETE 1
- Main resources
- 1. Start here: app token 12. Catalog (app token) 63. User sign-in (authorization code + PKCE) 24. The signed-in user 55. Playlists 56. Player (Premium) 6
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-17 - Links
- Documentation
How to test the Spotify Web API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Spotify Web API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get an app token (client credentials)” (POST {{accountsUrl}}/api/token), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Spotify Web API?
Search Spotify's catalog, sign users in with PKCE, read their library, build playlists and control playback. It is listed under Media & content and has 25 endpoints.
Who publishes the Spotify Web API?
It is listed from Spotify's public API description (an OpenAPI document), not published by Spotify on Swastik Codes. Anyone who controls spotify.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Spotify Web API?
Its description lists 2 base URLs: https://api.spotify.com/v1, https://accounts.spotify.com. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Spotify Web API?
It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (client credentials, authorization code flows).
How many endpoints does the Spotify Web API have?
25 operations on 25 paths (15 GET, 6 POST, 3 PUT, 1 DELETE). The largest groups are 1. Start here: app token, 2. Catalog (app token), 3. User sign-in (authorization code + PKCE), 4. The signed-in user.
Is forking the Spotify Web API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.