Spotify's Web API centers on three families of entities you will use most: catalog objects (artists, albums, tracks, shows, episodes, audiobooks), user-scoped resources (playlists, saved library items, followed artists/users), and playback targets (devices & the user's active playback session). Understanding how these groups relate and which IDs each operation needs is the difference between succeeding on the first call and getting stuck hunting for values.

Domain model and key relationships

• Catalog objects are identified by Spotify IDs and URIs. Catalog endpoints accept either raw id path parameters (e.g. get-track, get-an-album) or comma-separated ids query parameters for batch fetches (e.g. get-several-tracks). Some write endpoints require full Spotify URIs (e.g. add-to-queue and playlist insertions accept spotify:track:<id> or spotify:episode:<id>).

• Playlists are first-class, mutable, user-owned resources. Most playlist operations require a playlist_id path value (get details, get items, add items, remove items, reorder). Playlist creation uses a user_id path (create a playlist for a user). Playlist mutation endpoints often return a snapshot_id that identifies the playlist state after the change.

• The authenticated user's identity and library are separate: get-current-users-profile returns the current user's id (useful for create-playlist), while get-users-playlists and get-a-list-of-current-users-playlists enumerate playlists. Saved library operations (save/remove albums, tracks, shows, episodes, audiobooks) operate on the current user and use dedicated endpoints.

• Playback control targets devices. get-a-users-available-devices returns device.id values you pass to playback operations. If you omit device_id, commands target the user's currently active device.

Entry points — what to call first

• When you need the current user's identifier: call get-current-users-profile. The returned id is the user_id used by create-playlist and some user-scoped listing endpoints.

• When you need a playlist_id: either use search with type=playlist, use get-a-list-of-current-users-playlists (or get-list-users-playlists for other users), or call get-playlist if you already have an id/URI.

• For playback control: call get-a-users-available-devices to discover device_id values (useful for start-a-users-playback, transfer-a-users-playback, volume and skip commands). If no device_id is provided, the active device is used.

• To fetch catalog IDs in bulk: search (with appropriate type) finds items and returns id and uri; get-several-tracks, get-multiple-artists, get-multiple-albums accept comma-separated ids for batch retrieval.

Common tasks and the sequence of calls to perform them

The following tasks are the ones users ask for most often and show the typical sequence of operations and parameters you must supply.

• Create a playlist and add tracks

  • Get current user id via get-current-users-profile (if creating for the authenticated user). Use that user_id with create-playlist and supply playlist metadata in the body.
  • Add items with add-tracks-to-playlist using the playlist_id. Prefer sending URIs in the request body when adding many items (query uris can exceed URL length). Note the maximum items per request (see batching below).

• Inspect and modify a playlist's items

  • Retrieve playlist items with get-playlists-tracks (use fields to limit nested fields and reduce payload). Mutating operations return snapshot_id values: remove-tracks-playlist and reorder-or-replace-playlists-tracks return snapshot_id which identifies the new playlist state.
  • Use reorder-or-replace-playlists-tracks to replace the full item list (supply uris or a body). Use the reorder parameters in the body to move ranges — the operation returns a new snapshot_id.

• Control playback (start, pause, skip, seek, queue)

  • Discover devices via get-a-users-available-devices. Use device_id for explicit targeting or omit it to affect the active device.
  • Start/resume with start-a-users-playback. Provide context_uri (album/playlist) or uris (list of track URIs) in the body; use offset to start at a specific position.
  • Add a single item to the queue with add-to-queue (requires a Spotify URI, not just an id).
  • Seek with seek-to-position-in-currently-playing-track, set volume with set-volume-for-users-playback, toggle shuffle with toggle-shuffle-for-users-playback, and set repeat with set-repeat-mode-on-users-playback.

• Manage the user's saved library (save / remove / check)

  • Save or remove items using the dedicated endpoints: save-tracks-user, remove-tracks-user, save-albums-user, remove-albums-user, save-shows-user, remove-shows-user, etc. Each endpoint has its own maximum per request (see batching rules below).
  • To check whether items are in the user's library, use the corresponding "check" endpoints (e.g. check-users-saved-tracks) which accept comma-separated ids and return boolean arrays.

• Search and recommendations

  • Use search with q and type to find catalog items and obtain id/uri. Use field filters in q (e.g. year:1990-1995, artist:Radiohead, tag:new) to narrow results.
  • Generate personalized recommendations with get-recommendations. Provide up to 5 seed values across seed_artists, seed_tracks, and seed_genres (at least one seed is required). Optionally set tunable attributes (e.g. target_energy, min_tempo) to bias results.

Paging, batching, and parameter limits (practical rules)

• Many list endpoints use limit and offset. Defaults are typically 20; maximum per-request limits are often 50. If more results are needed, call the same endpoint with a larger offset.

• Batch endpoints accept comma-separated ids or uris with strict maxima: common limits are 20 for albums, 50 for tracks/shows/episodes/audiobooks, and 100 for some playlist operations (playlist add/set endpoints note a 100-item limit). Sending more than the allowed maximum in one request will fail.

• When adding many tracks to a playlist, avoid using the uris query parameter because of URL-length concerns; put the URIs in the request body instead.

• Audio-features batching: get-several-audio-features accepts up to 100 track IDs.

OAuth scopes and permission patterns (what will fail without the right scopes)

Many operations require the authenticated token to include specific user-scopes. Common mappings to keep in mind:

• Playback control: require playback scopes such as user-read-playback-state, user-modify-playback-state, and for streaming/remote control a streaming-related scope may be necessary.

• Reading the current playback and currently playing track: user-read-currently-playing and user-read-playback-state.

• Managing playlists: playlist-modify-public and/or playlist-modify-private are required to create or edit playlists; playlist-read-private is required to read private playlists.

• Saved library: user-library-read to check and list saved items, user-library-modify to save or remove items.

• Following artists/users and checking follows: user-follow-read and user-follow-modify.

• Top items and recently-played: user-top-read and user-read-recently-played.

If a write operation returns 403 or 401-like errors, it commonly indicates missing scopes or that the authenticated user is not allowed to perform the action on that resource.

Market and availability quirks

• Many catalog endpoints accept a market parameter. If a user access token is supplied, the user's account country takes precedence over the market query value. If neither a market nor a user-country is available, some content may be treated as unavailable. When availability matters (e.g., building a play queue or creating a playlist meant to be playable), prefer catalog items returned with an explicit market or respect the user's account country.

• Track/episode playability sometimes differs by market and by whether the response marks an item as playable. Use include_external=audio on search only when the client can play externally hosted content.

Playlist mutation details and snapshot semantics

• After any playlist mutation (add-tracks-to-playlist, remove-tracks-playlist, reorder-or-replace-playlists-tracks) the response includes a snapshot_id. The snapshot_id is an opaque identifier for that playlist state. If the caller needs to confirm a change was applied or to detect concurrent modifications, preserve the snapshot_id returned by the most recent change.

• When removing individual occurrences of a track from a playlist, use remove-tracks-playlist with objects identifying uri and positions if you need to remove a specific occurrence.

Playback command details and device selection

• Most playback commands accept an optional device_id. If omitted they act on the user's currently active device. Use get-a-users-available-devices to list devices and their id values. Some devices may refuse remote commands depending on platform or current state (e.g. a device already in a different session).

• add-to-queue requires a Spotify URI (track or episode). Passing an id without the spotify:track: or spotify:episode: prefix will not work.

• start-a-users-playback accepts a body with context_uri (album/playlist/podcast) or an array uris for a list of tracks; use the offset object to start at a specific item index.

Search syntax and recommendation seeds — non-obvious filters

• The search q parameter supports field filters (for example artist:Queen year:1975-1980 isrc:...) and special filters like tag:new (albums in the last two weeks) and tag:hipster (lowest popularity). Use these filters to narrow results without post-filtering.

• get-recommendations requires at least one seed across seed_artists, seed_tracks, seed_genres and allows at most five total seed values. Tunable attributes (min/max/target prefixed keys) bias results; if results are sparse, the recommendations response can include debugging information explaining why the requested target count couldn't be met.

Error and rate-limit signals to observe

• 429 responses indicate rate limiting. The response typically includes a Retry-After header; use the header value to determine when the operation can be retried.

• 400-level errors on write endpoints commonly indicate invalid input (exceeding batch size, malformed URIs, invalid position indices when inserting into playlists). 403 errors often indicate missing scopes or permission problems.

Practical tips and gotchas (quick reference of common pitfalls)

• Many endpoints accept both id and uri forms in different contexts. Check whether an endpoint requires id (path param) or uri (queue and many playlist insertion operations). Passing the wrong form will fail.

• Respect per-endpoint batch limits (20, 50, 100 depending on endpoint). If a user requests adding dozens or hundreds of items, break the work into multiple requests explicitly by calling the add endpoint multiple times with valid batch sizes.

• For playlist operations that accept fields, use fields to return only what you need (for example fields=tracks.items(track(name,uri)),snapshot_id) to reduce payload size when scanning or reporting playlist contents.

• When modifying playback, several operations are eventual: transfer-a-users-playback may not make a device active instantly; start-a-users-playback may return before playback actually starts. Verify playback state via get-information-about-the-users-current-playback if you need confirmation.

• Some "get multiple" endpoints (e.g. get-several-tracks, get-multiple-artists) will return arrays in the same order as requested IDs; use that ordering to correlate results to input IDs.

• If the user asks to play or queue an item found via search, prefer the uri field from search results—it's the simplest, guaranteed-to-work identifier for playback endpoints.

When you need something not covered here

If a requested action requires IDs you don't have, the usual ways to obtain them are search (by text/filters), get-current-users-profile (to find the current user_id), or the relevant list endpoint (get-a-list-of-current-users-playlists, get-a-users-available-devices, or catalog lookups like get-an-artist / get-an-album). Use the operation that naturally returns the ID the mutate or playback endpoint requires.

Use these patterns to map user intents to the minimal set of calls: find the needed IDs via search/list endpoints, ensure required OAuth scopes are present for the intended mutation or playback, respect per-endpoint batch limits, and pass device_id when you must target a particular device rather than the user's active device.