Docs Site Using Hugo

🎧 Overview

Spotify is a leading digital audio streaming service that gives you access to millions of songs, podcasts, and videos. Spotify is accessible for free with ads or through a paid Premium plan for ad-free listening, offline downloads, and higher audio quality. It allows users to create playlists, discover new music, and listen using various devices, including phones, computers, and tablets.

The Spotify Web API is a RESTful API with different endpoints that return JSON metadata about music artists, albums, and tracks, directly from the Spotify Data Catalog. It allows developers to build applications that interact with Spotify’s music data and features, allowing them to retrieve music information, manage playlists, control playback, and access user data through standard web requests (RESTful). It provides access to Spotify’s catalog (including artists, albums, and tracks), and user features, using authorization flows like Client Credentials for app data and Authorization Code for user-specific actions.

Common use cases

• Access catalog information: Developers can retrieve metadata about artists, albums, tracks, and podcasts, including cover art, release dates, popularity ratings, and links to 30-second audio previews.

• Create music statistics trackers: Third-party websites can analyze a user’s listening habits and display their top tracks, artists and listening history.

• Automate playlist generation: Applications can automatically create new playlists, add or remove items, reorder tracks, and even upload custom cover images.

• Create collaborative playlists: Applications can facilitate the creation of shared playlists for events like parties or weddings, where multiple users can contribute songs.

• Control playback: Applications can control the playback state (play, pause, skip, or seek), manage the playback queue, and transfer playback between different Spotify Connect devices (like speakers or a phone).

• Display profile data: Users can authorize third-party web applications to display their personal profile information and playlists.

Technical details

• Supports resource-oriented endpoints under https://api.spotify.com, such as /albums, /artists, /tracks, and /playlists.
• Supports standard HTTP methods: GET, POST, PUT, DELETE (204 responses when applicable).
• Exchanges data in UTF‑8 encoded JSON. Responses contain metadata for artists, tracks, playlists, playback state, etc.
• Uses JSON exclusively; XML/HTML not natively supported.
• Utilizes OAuth 2.0 with multiple flows for authentication and authorization, and requires the Bearer header with an access token.

Target audience

This guide is intended for developers who want to integrate Spotify features into web, mobile, or backend applications. It assumes familiarity with HTTP requests, JSON, and basic command-line tools, such as curl. No prior experience with OAuth 2.0 is required. The authentication section provides a clear, task‑oriented explanation to help new integrators get started quickly.

🔗 Base URL

All API requests are made to the following base URL. When constructing requests, append the endpoint paths to this root URL. For security, the API is served over HTTPS, and all endpoints are versioned.

https://api.spotify.com

🔐 Authentication

In the Spotify Web API, users grant consent for specific scopes to a registered client application. The application (server-side) authenticates to Spotify using its client ID and client secret (never exposed to end users) and requests access tokens to call the API. The server authenticates and authorizes the clients, and sends them access tokens, which are used by the clients to make API requests on behalf of the user or application.

Access to protected resources is determined by one or several scopes. Scopes allow the application to access specific functionality (such as reading a playlist, modifying your library, or streaming) on behalf of a user. The set of scopes set during authorization determines the access permissions that the user is asked to grant.

OAuth authorization framework in Spotify

Spotify implements the OAuth2 standard accordingly:

Spotify implements three OAuth grant types

The OAuth2 standard defines four grant types (or flows) for authentication. Spotify implements three of these grant types.

Select the right grant type for the application you are building:

• Authorization Code: When developing a long-running application, like a web app running on the server, use this grant type, in which the user grants permission only once and the client secret can be safely stored.

• Authorization Code with PKCE Extension: When developing a desktop app, mobile app, or JavaScript web app that run in a browser, the client secret is not safe. To provide protection against attacks where the authorization code can be intercepted, use this grant type.

• Client Credentials: When developing applications that run on the backend, such as CLIs or daemons, the system authenticates and authorizes the app rather than the user. For these applications, Client Credentials is the typical choice. This grant type does not include user authentication, so only endpoints that do not request user information (such as profile data) can be accessed.

📊 Rate limits

A rate limit is the number of requests the API can receive in a specific time period. Rate limiting ensures efficient API performance and prevents abuse. Once the limit is reached, API requests from the client will fail.

Spotify applies rate limiting and returns 429 Too Many Requests when your app exceeds allowed thresholds. The exact limits are not publicly documented and may vary by app. Use the Retry-After response header to back off and retry after the indicated number of seconds.

429 error response

Use the information in the 429 response to slow down the number of API requests that it makes to the Web API. The header of the 429 response includes a Retry-After parameter with a value in seconds. Consider waiting for the number of seconds before your app calls the Web API again.

For example, the following 429 response contains a Retry-After header set to 30 seconds:

{
  "headers": {
    "Retry-After": "30"
  },
  "body": {
    "error": {
      "code": "rate_limited",
      "message": "Too many requests. Try again later.",
      "request_id": "req_xR72m3"
    }
  }
}

App access modes (user access quotas)

These modes control which users can access your app, and not the per‑second rate limit:

• Development mode (default): Your app can be used by up to 25 specified Spotify users you add in User Management.

• Extended access (via review): After a successful partner/review process, your app can be used by a broader set of users. Individuals cannot apply. This is for organizations with approved use cases.

Define authenticated users in development mode

When you first create an app from the Spotify Developer Dashboard, the default quota mode is development mode. You can define authenticated users for the app, including testers, friends, or fellow developers.

Before you begin

Complete the getting started tasks:

• Set up your account

• Create an app

Procedure:

1. From the Dashboard page, select the app for which you want to define authenticated users.

2. On the next page, select the User Management tab.

3. In the Full Name and Email fields, enter the name and email address of the first user you want to add, and select Add user.

   ---

   

   ---

   The user you added can now authenticate with your app. You can define a total of 25 authenticated users in development mode. To define an unlimited number of users, apply for extended quota mode.

   ---

   

   ---

Apply for extended quota mode

If you want your app to be used by many Spotify users at the same time, your organization can apply for the extended quota mode, which has a much higher rate limit than development mode.

To apply for this mode, your business or organization first needs to be an approved Spotify partner, which involves completing and submitting a Partner Application Form. Upon approval, you can then complete and submit a Quota Extension Request Form from the Developer Dashboard. The Spotify App Review Team reviews your request, tests your app and sends you feedback via email about your request.

Before you begin

• Complete the getting started tasks:

  • Set up your account

  • Create an app

• Verify that your organization or business:

  • Is an established business entity (legally registered business or organization)

  • Operates an active, launched service

  • Maintains a minimum of at least 250K active users

  • Is available in key Spotify markets

Procedure:

1. Complete the Partner Application Form.

   Spotify will review your submitted form and send a response by email. If Spotify approves your Partner Application Form, continue to the next step.

2. From the Dashboard page, select the app for which you want to request extended quota mode.

3. From the Quota Extension Request tab, complete the Quota Extension Request Form, which includes four main sections.

   ---

   

   ---

4. When you have completed the form, select Submit.

   If you have successfully submitted your app for review, Sent is displayed in blue on your app detail page. The app review team will review your form, evaluate it for compliance with Spotify’s Developer Policy, and send you feedback to the email address associated with your Spotify account. This review process can take up to 6 weeks.

Rate limit techniques

• Use extended quota mode: If you want your app to be used by many Spotify users at the same time, apply for extended quota mode.

• Use batch APIs: Some Spotify APIs, such as the Get Multiple Albums endpoint, allow you to fetch a batch of data in one API request. If you know you will need data from a set of objects, reduce your API requests by calling the batch APIs.

• Analyze your app request volume: On the Developer Dashboard, on your app’s detail page, a graph displays data about your API request volume over time. To avoid exceeding the rate limit, understand the anomalies in your API requests and the reasons for them. For example, if you notice that your website receives a surge in traffic after you send out your weekly newsletter, you can stagger the delivery of the emails over a longer period of time.

• Use lazy loading features: Make API calls conditional on user interactions, such as selecting a Learn more link or scrolling to a defined region of a web page. Most users do not want to use every feature that is available to them on a web page or mobile app. This technique avoids making unnecessary API requests.

⚠️ HTTP status and error codes

Spotify’s Web API follows standard HTTP status codes, paired with JSON responses.

Common HTTP status codes

Error response format

Most error codes (4xx or 5xx) adhere to this JSON format:

{
  "error": {
    "status": 401,
    "message": "Invalid access token"
  }
}

↕️ Pagination

Pagination allows you to retrieve large sets of data in smaller, manageable chunks by using specific parameters to limit the amount of data sent in each API response.

The Spotify Web API uses an offset-based paging model for endpoints that return multiple items (such as tracks, artists, and playlists).

Responses include a Paging object with the following parameters:

• items: Array of the current page’s objects

• limit: Maximum number of items per page. (The maximum limit value is 50 for most endpoints.)

• offset: Index where the page starts

• total: Total count of all matching items

• next: URL of the next page (or null)

• previous: URL of the previous page (or null)

Note the following:

• Use the next and previous URLs instead of manually calculating offsets.

• To retrieve more pages, request the URL provided by the next parameter.

• To control page size and the starting point, use the limit and offset parameters.

Example: API request and response using pagination

Here’s how to request the second page of playlists and what the response looks like:

curl "https://api.spotify.com/v1/me/playlists?offset=20&limit=20" \
     -H "Authorization: Bearer <access_token>"

{
  "href": "https://api.spotify.com/v1/me/playlists?offset=20&limit=20",
  "items": [ ... ],
  "limit": 20,
  "next": "https://api.spotify.com/v1/me/playlists?offset=40&limit=20",
  "offset": 20,
  "previous": "https://api.spotify.com/v1/me/playlists?offset=0&limit=20",
  "total": 85
}

🚀 Getting started

From the Spotify Developer Dashboard, set up your account. Then, create your first app, which provides you with a client ID and client secret. Finally, request an access token, which is a string that contains the credentials and permissions you need to access a given resource.

Every access token is valid for 1 hour. Include the Authorization header in your API requests using: Bearer <access_token>.

Set up your account

Set up your Spotify Web API account on the Spotify Developer Dashboard.

Procedure

1. Go to the Spotify for Developers page.

2. Select Log in.

3. Under Don’t have an account?, select Sign up.

4. Do one of the following:

   • Type your email address and select Next.

   • Select Sign up with Google and select an existing Google account.

5. From the Spotify for Developers page, from your username, select Dashboard.

6. Read the Spotify Developer Terms page and select Accept the terms.

   The system displays the Dashboard page. You can now create an app.

Create an app

After you set up your account, you can create your first app on the Spotify Developer Dashboard.

An app provides the client ID and client secret you need to request an access token, which is used to access any resource (such as artists, albums, or tracks) or user data (for example, your profile or playlists).

Before you begin

Set up your account

Procedure

1. From the Spotify for Developers page, select Create app.

2. On the Create app page, complete the fields.

   ---

   

   ---

   Field	Description
   App name	Enter the name of the application.
   App description	Enter a description of the application.
   Website	Optional_. Enter the Web domain or URL that allows users to get more information about your application.
   Redirect URIs	Enter one or more URIs where users can be redirected after authentication success or failure, and select Add. These URIs enable the Spotify authentication service to automatically invoke your app every time the user logs in. For example: http://127.0.0.1:8080/. Note that on iOS apps, the redirect URI must adhere to the following: All of the characters are lowercase. Prefix must be unique to your application. (It cannot be a general prefix like http.) NOTE: The prefix must only be used by your application for authenticating Spotify. If you already have a URL scheme handled by your application for other uses, do not reuse it. Include a path after the first pair of forward slashes. For example, if your app name is Get My Fav Music Stats, a good candidate for the redirect URI could be: get-my-fav-music-stats-login://callback.
   Which API/SDKs are you planning to use?	Select the type of APIs/SDKs you are planning to use for the app.
   I understand and agree with Spotify’s Developer Terms of Service and Design Guidelines.	Select the terms of service.

3. Select Save.

   ---

   

   ---

   The application adds the app you created.

   ---

   

   ---

By default, every app you create starts in development mode, which limits usage to up to 25 specified users. If you want to share your app with up to 25 users, define authenticated users in development mode.

However, if you want to define an unlimited number of users, your organization can apply for extended quota mode. For details on both modes, see App access modes (user access quotas).

Request an access token

You can now request an access token, which is a string that contains the credentials and permissions used to access a given resource (such as artists, albums, or tracks) or user data (for example, your profile or playlists).

Before you begin

• Create an app

• Verify that curl is installed on your computer:

  • For macOS/Linux, it is usually pre-installed.
  • For Windows, download and install curl or use Git Bash.

Procedure

1. From the Dashboard, select the app you just created.

   ---

   

   ---

2. From the Basic Information tab, access your client ID and client secret:

   • Client ID: The client ID is displayed in the Client ID field. To copy it, click the copy icon in the corner.

   • Client Secret: To view the client secret, select View client secret. To copy it, click the copy icon in the corner.

   ---

   

   ---

3. Using the Client Credentials authorization flow, send an API request with the following information:

   • Send a POST request to the token endpoint URI.
   • Add the Content-Type header: application/x-www-form-urlencoded.
   • Add an Authorization header using HTTP Basic with base64(client_id:client_secret).
   • Set the body parameter: grant_type=client_credentials.

   curl -X POST "https://accounts.spotify.com/api/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Basic <base64(client_id:client_secret)>" \
    -d "grant_type=client_credentials"
   

   The response returns an access token that is valid for 1 hour (or 3600 seconds). After that time, the token expires and you need to request a new one.

   
   {
     "access_token": "BQDBKJ5eo5jxbtpWjVOj7ryS84khybFpP_lTqzV7uV-T_m0cTfwvdn5BnBSKPxKgEb11",
     "token_type": "Bearer",
     "expires_in": 3600
   }
   

   To use the access token, you must include the Authorization header in your API requests, where the value is the valid access token following the format: Bearer <Access Token>.

🎤 Tutorial: Request artist data

This tutorial describes how to retrieve information about an artist. It involves appending the Spotify ID of the artist to the Get Artist endpoint, and including the access token using the Authorization header in the API request.

Before you begin

Complete all of the Getting started tasks, including setting up an account, creating an app, and requesting an access token.

Step 1: Get the Spotify ID of an artist

For the Get Artist endpoint, you need the Spotify ID of the artist.

Use the Spotify Desktop App to get the Spotify ID:

1. Search for the artist.

2. From the artist profile, click the 3 dots icon.

3. Select Share > Copy link to artist.

   The Spotify ID is the final path segment in the URL, after open.spotify.com/artist/. For example, in https://open.spotify.com/artist/4Z8W4fKeB5YxbusRsdQVPb, the ID is 4Z8W4fKeB5YxbusRsdQVPb.

Step 2: Start the API request with the Get Artist endpoint

Append the Spotify ID to the Get Artist endpoint (https://api.spotify.com/v1/artists/{artist_id}).

For example:

curl "https://api.spotify.com/v1/artists/4Z8W4fKeB5YxbusRsdQVPb" \

Step 3: Include the access token in the API request

Include an access token (recently generated) using the Authorization header.

For example:

curl "https://api.spotify.com/v1/artists/4Z8W4fKeB5YxbusRsdQVPb" \
     -H "Authorization: Bearer BQDBKJ5eo5jxbtpWjVOj7ryS84khybFpP_lTqzV7uV-T_m0cTfwvdn5BnBSKPxKgEb11"

Step 4: Verify a successful response

Verify that the API returns a successful JSON response, which includes information about the artist.

📘 API reference

The Spotify Web API Reference is designed to help developers integrate Spotify features into applications by providing clear examples, endpoint details, and request/response formats.

API reference overview

The API reference provides curated examples of Spotify Web API endpoints for portfolio purposes. Endpoints are grouped by resource type for easier navigation.

Each endpoint includes the following data:

• Description or purpose of the endpoint
• HTTP method
• Endpoint
• Request syntax
• Query parameters
• Request example
• Response example
• Response elements

Resource groups and endpoints

The following table summarizes the resource groups and their associated endpoints included in this guide:

Headers

The following headers are commonly used:

Error responses

All endpoints return errors in a consistent JSON format when something goes wrong. The response includes an error object with two fields:

• status: HTTP status code (integer)
• message: Human-readable description of the error (string)

For example:

{
  "error": {
    "status": 401,
    "message": "Invalid access token"
  }
}

For more information, see HTTP Status and Error Codes.

Albums 🎵

Endpoints related to retrieving metadata for a single or multiple music albums, including tracks, artists, and availability by market.

Endpoints

• Get album
• Save albums for current user
• Remove a user’s saved albums

Get album

Retrieves Spotify catalog information for a single album.

Method

GET

Endpoint

https://api.spotify.com/v1/albums/{id}

Request syntax

GET https://api.spotify.com/v1/albums/{id}

Authorization: Bearer <access_token>

Query parameters

Request example

curl --request GET \
  --url https://api.spotify.com/v1/albums/4aawyAB9vmqN3uQ7FjRGTy \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

{
  "album_type": "compilation",
  "total_tracks": 9,
  "available_markets": ["CA", "BR", "IT"],
  "external_urls": {
    "spotify": "string"
  },
  "href": "string",
  "id": "2up3OPMp9Tb4dAKM2erWXQ",
  "images": [
    {
      "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",
      "height": 300,
      "width": 300
    }
  ],
  "name": "string",
  "release_date": "1981-12",
 "release_date_precision": "month",
  "restrictions": {
    "reason": "market"
  },
  "type": "album",
  "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ",
  "artists": [
    {
      "external_urls": {
        "spotify": "string"
      },
      "href": "string",
      "id": "string",
      "name": "string",
      "type": "artist",
      "uri": "string"
    }
  ],
"tracks": {
  "href": "https://api.spotify.com/v1/albums/2up3OPMp9Tb4dAKM2erWXQ/tracks?offset=0&limit=20",
  "limit": 20,
  "next": "https://api.spotify.com/v1/albums/2up3OPMp9Tb4dAKM2erWXQ/tracks?offset=20&limit=20",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/albums/2up3OPMp9Tb4dAKM2erWXQ/tracks?offset=0&limit=20",
  "total": 4,
  "items": [
      {
        "artists": [
          {
            "external_urls": {
              "spotify": "string"
            },
            "href": "string",
            "id": "string",
            "name": "string",
            "type": "artist",
            "uri": "string"
          }
        ],
        "available_markets": ["string"],
        "disc_number": 0,
        "duration_ms": 0,
        "explicit": false,
        "external_urls": {
          "spotify": "string"
        },
        "href": "string",
        "id": "string",
        "is_playable": false,
        "linked_from": {
          "external_urls": {
            "spotify": "string"
          },
          "href": "string",
          "id": "string",
          "type": "string",
          "uri": "string"
        },
        "restrictions": {
          "reason": "string"
        },
        "name": "string",
        "preview_url": "string",
        "track_number": 0,
        "type": "string",
        "uri": "string",
        "is_local": false
      }
    ]
  },
  "copyrights": [
    {
      "text": "string",
      "type": "string"
    }
  ],
  "external_ids": {
    "isrc": "string",
    "ean": "string",
    "upc": "string"
  },
  "genres": [],
  "label": "string",
  "popularity": 0
}

Response elements

Save albums for current user

Saves one or more albums to the current user’s music library.

Method

PUT

Endpoint

https://api.spotify.com/v1/me/albums

Request syntax

PUT https://api.spotify.com/v1/me/albums

Authorization: Bearer <access_token>

Query parameters

PUT body

Request example

curl --request PUT \
  --url 'https://api.spotify.com/v1/me/albums?ids=382ObEPsp2rxGrnsizN5TX%2C1A2GTWGtFfWp7KSQTwWOyo%2C2noRn2Aes5aoNVsU6iWThc' \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": [
        "string"
    ]
}'

Response example

If successful (200 status code), the album is saved.

Remove a user’s saved albums

Removes one or more albums from the current user’s music library.

Method

DELETE

Endpoint

https://api.spotify.com/v1/me/albums

Request syntax

DELETE https://api.spotify.com/v1/me/albums

Authorization: Bearer <access_token>

Query parameters

DELETE body

Request example

curl --request DELETE \
  --url 'https://api.spotify.com/v1/me/albums?ids=382ObEPsp2rxGrnsizN5TX%2C1A2GTWGtFfWp7KSQTwWOyo%2C2noRn2Aes5aoNVsU6iWThc' \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": [
        "string"
    ]
}'

Response example

If successful (200 status code), the specified albums have been removed from the library.

Artists 👤

Endpoints related to retrieving Spotify catalog information for a single or multiple artists by their unique Spotify IDs.

Endpoints

• Get several artists
• Get artist’s top tracks

Get several artists

Retrieves Spotify catalog information for several artists based on their Spotify IDs.

Method

GET

Endpoint

https://api.spotify.com/v1/artists

Request syntax

GET https://api.spotify.com/v1/artists


Authorization: Bearer <access_token>

Request example

curl --request GET \
  --url 'https://api.spotify.com/v1/artists?ids=2CIMQHirSU0MQqyYHq0eOx%2C57dN52uHvrHOxijzpIgu3E%2C1vCWHaC5f2uS3yhpwWbIA6' \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

{
  "artists": [
    {
      "external_urls": {
        "spotify": "string"
      },
      "followers": {
        "href": null,
        "total": 0
      },
      "genres": [
        "Prog rock",
        "Grunge"
      ],
      "href": "string",
      "id": "string",
      "images": [
        {
          "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",
          "height": 300,
          "width": 300
        }
      ],
      "name": "string",
      "popularity": 0,
      "type": "artist",
      "uri": "string"
    }
  ]
}

Response elements

Get artist’s top tracks

Retrieves Spotify catalog information about an artist’s top tracks by country.

Method

GET

Endpoint

https://api.spotify.com/v1/artists/{id}/top-tracks

Request syntax

GET https://api.spotify.com/v1/artists/{id}/top-tracks

Authorization: Bearer <access_token>

Query parameters

Request example

curl --request GET \
  --url https://api.spotify.com/v1/artists/0TnOYISbd1XYRBk9myaseg/top-tracks \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

{
  "tracks": [
    {
      "album": {
        "album_type": "compilation",
        "total_tracks": 9,
        "available_markets": [
          "CA",
          "BR",
          "IT"
        ],
        "external_urls": {
          "spotify": "string"
        },
        "href": "string",
        "id": "2up3OPMp9Tb4dAKM2erWXQ",
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",
            "height": 300,
            "width": 300
          }
        ],
        "name": "string",
        "release_date": "1981-12",
        "release_date_precision": "year",
        "restrictions": {
          "reason": "market"
        },
        "type": "album",
        "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ",
        "artists": [
          {
            "external_urls": {
              "spotify": "string"
            },
            "href": "string",
            "id": "string",
            "name": "string",
            "type": "artist",
            "uri": "string"
          }
        ]
      },
      "artists": [
        {
          "external_urls": {
            "spotify": "string"
          },
          "href": "string",
          "id": "string",
          "name": "string",
          "type": "artist",
          "uri": "string"
        }
      ],
      "available_markets": [
        "string"
      ],
      "disc_number": 0,
      "duration_ms": 0,
      "explicit": false,
      "external_ids": {
        "isrc": "string",
        "ean": "string",
        "upc": "string"
      },
      "external_urls": {
        "spotify": "string"
      },
      "href": "string",
      "id": "string",
      "is_playable": false,
      "linked_from": {},
      "restrictions": {
        "reason": "string"
      },
      "name": "string",
      "popularity": 0,
      "preview_url": "string",
      "track_number": 0,
      "type": "track",
      "uri": "string",
      "is_local": false
    }
  ]
}

Response elements

Player ▶️

Endpoints related to performing playback actions on a specific device.

Endpoints

• Get available devices
• Pause playback
• Skip to next

Get available devices

Retrieves information about a user’s available Spotify Connect devices. Availability can vary by device type and compatibility. Therefore, some devices might not appear in the response.

Method

GET

Endpoint

https://api.spotify.com/v1/me/player/devices

Request syntax

GET https://api.spotify.com/v1/me/player/devices

Authorization: Bearer <access_token>

Query parameters

No query parameters are supported for this endpoint.

Request example

curl --request GET \
  --url https://api.spotify.com/v1/me/player/devices \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

{
  "devices": [
    {
      "id": "string",
      "is_active": false,
      "is_private_session": false,
      "is_restricted": false,
      "name": "Kitchen speaker",
      "type": "computer",
      "volume_percent": 59,
      "supports_volume": false
    }
  ]
}

Response elements

Pause playback

Pauses playback on a user’s account. This API only works for users who have Spotify Premium. The order of execution is not guaranteed when you use this API with other Player API endpoints.

Method

PUT

Endpoint

https://api.spotify.com/v1/me/player/pause

Request syntax

PUT https://api.spotify.com/v1/me/player/pause

Authorization: Bearer <access_token>

Query parameters

Request example

curl --request PUT \
  --url https://api.spotify.com/v1/me/player/pause \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

If successful (204 status code), playback on the device is paused.

Skip to next

Skips to the next track in the user’s queue.

Method

POST

Endpoint

https://api.spotify.com/v1/me/player/next

Request syntax

POST https://api.spotify.com/v1/me/player/next

Authorization: Bearer <access_token>

Query parameters

Request example

curl --request POST \
  --url https://api.spotify.com/v1/me/player/next \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

If successful (204 status code), the device skips to the next track in the queue.

Playlists 📂

Endpoints related to performing actions on a specific playlist owned by a Spotify user.

Endpoints

• Get playlist
• Update playlist items
• Add items to playlist
• Remove playlist items

Get playlist

Retrieves a playlist owned by a Spotify user.

Method

GET

Endpoint

https://api.spotify.com/v1/playlists/{playlist_id}

Request syntax

GET https://api.spotify.com/v1/playlists/{playlist_id}

Authorization: Bearer <access_token>

Query parameters

Request example

curl --request GET \
  --url https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z'

Response example

{
  "collaborative": false,
  "description": "string",
  "external_urls": {
    "spotify": "string"
  },
  "href": "string",
  "id": "string",
  "images": [
    {
      "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",
      "height": 300,
      "width": 300
    }
  ],
  "name": "string",
  "owner": {
    "external_urls": {
      "spotify": "string"
    },
    "href": "string",
    "id": "string",
    "type": "user",
    "uri": "string",
    "display_name": "string"
  },
  "public": false,
  "snapshot_id": "string",
 "tracks": {
  "href": "https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks?offset=0&limit=20",
  "limit": 20,
  "next": "https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks?offset=20&limit=20",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks?offset=0&limit=20",
  "total": 4,
  "items": [
      {
        "added_at": "string",
        "added_by": {
          "external_urls": {
            "spotify": "string"
          },
          "href": "string",
          "id": "string",
          "type": "user",
          "uri": "string"
        },
        "is_local": false,
        "track": {
          "album": {
            "album_type": "compilation",
            "total_tracks": 9,
            "available_markets": [
              "CA",
              "BR",
              "IT"
            ],
            "external_urls": {
              "spotify": "string"
            },
            "href": "string",
            "id": "2up3OPMp9Tb4dAKM2erWXQ",
            "images": [
              {
                "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",
                "height": 300,
                "width": 300
              }
            ],
            "name": "string",
            "release_date": "1981-12",
            "release_date_precision": "year",
            "restrictions": {
              "reason": "market"
            },
            "type": "album",
            "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ",
            "artists": [
              {
                "external_urls": {
                  "spotify": "string"
                },
                "href": "string",
                "id": "string",
                "name": "string",
                "type": "artist",
                "uri": "string"
              }
            ]
          },
          "artists": [
            {
              "external_urls": {
                "spotify": "string"
              },
              "href": "string",
              "id": "string",
              "name": "string",
              "type": "artist",
              "uri": "string"
            }
          ],
          "available_markets": [
            "string"
          ],
          "disc_number": 0,
          "duration_ms": 0,
          "explicit": false,
          "external_ids": {
            "isrc": "string",
            "ean": "string",
            "upc": "string"
          },
          "external_urls": {
            "spotify": "string"
          },
          "href": "string",
          "id": "string",
          "is_playable": false,
          "linked_from": {},
          "restrictions": {
            "reason": "string"
          },
          "name": "string",
          "popularity": 0,
          "preview_url": "string",
          "track_number": 0,
          "type": "track",
          "uri": "string",
          "is_local": false
        }
      }
    ]
  },
  "type": "string",
  "uri": "string"
}

Response elements

Update playlist items

Reorders or replaces items in a playlist, depending on the request’s parameters. Replacing items in a playlist overwrites its existing items. This operation can be used for replacing or clearing items in a playlist.

Method

PUT

Endpoint

https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Request syntax

PUT https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Authorization: Bearer <access_token>

Content-Type: application/json

{

  "range_start": 1,
  
  "insert_before": 3,

  "range_length": 2
  
}

Query parameters

PUT body

Request example

curl --request PUT \
  --url https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z' \
  --header 'Content-Type: application/json' \
  --data '{
    "range_start": 1,
    "insert_before": 3,
    "range_length": 2
}'

Response example

If successful (200 status code), the API returns the snapshot ID for the updated playlist.

For example:

{
  "snapshot_id": "abc"
}

Add items to playlist

Adds one or more items to a user’s playlist.

Method

POST

Endpoint

https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Request syntax

POST https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Authorization: Bearer <access_token>

Content-Type: application/json

{

  "uris": [
  
      "string"
 
    ],
 
      "position":0
  
}

Query parameters

POST body

Request example

curl --request POST \
  --url https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z' \
  --header 'Content-Type: application/json' \
  --data '{
    "uris": [
        "string"
    ],
    "position": 0
}'

Response example

If successful (201 status code), the API returns the snapshot ID for the updated playlist.

For example:

{
  "snapshot_id": "abc"
}

Remove playlist items

Removes one or more items from a user’s playlist.

Method

DELETE

Endpoint

https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Request syntax

DELETE https://api.spotify.com/v1/playlists/{playlist_id}/tracks

Authorization: Bearer <access_token>

Content-Type: application/json

{

  "tracks": [

      {

         "uri": "string"

      }

   ],
  
   "snapshot_id": "string"
  
}

Query parameters

DELETE body

Request example

curl --request DELETE \
  --url https://api.spotify.com/v1/playlists/3cEYpjA9oz9GiPac4AsH4n/tracks \
  --header 'Authorization: Bearer 1POdFZRZbvb...qqillRxMr2z' \
  --header 'Content-Type: application/json' \
  --data '{
    "tracks": [
        {
            "uri": "string"
        }
    ],
    "snapshot_id": "string"
}'

Response example

If successful (200 status code), the API returns the snapshot ID for the updated playlist.

For example:

{
  "snapshot_id": "abc"
}