Building with AI

This guide explains how to use the Spotify Web API with large language models (LLMs) and AI coding assistants. We provide machine-readable documentation formats optimized for AI consumption, so you can build Spotify integrations faster with tools like Claude, ChatGPT, Cursor, GitHub Copilot, and other AI-powered development environments.

OpenAPI specification

The Spotify Web API is documented with an OpenAPI 3.0 specification that can be consumed directly by AI tools and code generators. This machine-readable spec includes all endpoints, request/response schemas, authentication requirements, and parameter descriptions.


_10https://developer.spotify.com/reference/web-api/open-api-schema.yaml

Many AI coding tools can ingest OpenAPI specs directly. For example, you can paste the spec URL into your AI assistant's context or use it with code generation tools to scaffold API clients automatically.

Prompt for AI coding assistants

When starting a new project, give your AI assistant the following prompt to ensure it follows Spotify's API guidelines and best practices. Copy and adapt it to your needs:


_11You are helping me build an application using the Spotify Web API. Follow these rules:
_11
_11- OpenAPI spec: Refer to the Spotify OpenAPI specification at https://developer.spotify.com/reference/web-api/open-api-schema.yaml for all endpoint paths, parameters, and response schemas. Do not guess endpoints or field names.
_11- Authorization: Use the Authorization Code with PKCE flow (https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flow) for any user-specific data. If the app has a secure backend, the Authorization Code flow (https://developer.spotify.com/documentation/web-api/tutorials/code-flow) is also acceptable. Only use Client Credentials for public, non-user data. Never use the Implicit Grant flow (it is deprecated).
_11- Redirect URIs: Always use HTTPS redirect URIs (except http://127.0.0.1 for local development). Never use http://localhost or wildcard URIs. See https://developer.spotify.com/documentation/web-api/concepts/redirect_uri for requirements.
_11- Scopes: Request only the minimum scopes (https://developer.spotify.com/documentation/web-api/concepts/scopes) needed for the features being built. Do not request broad scopes preemptively.
_11- Token management: Store tokens securely. Never expose the Client Secret in client-side code. Implement token refresh (https://developer.spotify.com/documentation/web-api/tutorials/refreshing-tokens) logic so the app does not break when access tokens expire.
_11- Rate limits: Implement exponential backoff and respect the Retry-After header when receiving HTTP 429 responses. Do not retry immediately or in tight loops.
_11- Deprecated endpoints: Do not use deprecated endpoints. Prefer /playlists/{id}/items over /playlists/{id}/tracks, and use /me/library over the type-specific library endpoints.
_11- Error handling: Handle all HTTP error codes documented in the OpenAPI schema. Read the returned error message and use it to provide meaningful feedback to the user.
_11- Developer Terms of Service: Comply with the Spotify Developer Terms (https://developer.spotify.com/terms). In particular: do not cache Spotify content beyond what is needed for immediate use, always attribute content to Spotify, and do not use the API to train machine learning models on Spotify data.

For feature-specific work, you can also share the relevant documentation page directly. For example, if you're implementing authorization, share the Authorization page.

Example prompts

Here are some example prompts for common tasks:

Searching for tracks:

Using the Spotify Web API, write a Python function that searches for tracks by name and returns the top 5 results with their artist names and preview URLs. Use the Client Credentials flow for authentication.

Creating a playlist:

Help me build a Node.js script that authenticates with Spotify using Authorization Code with PKCE, gets my top tracks from the last 6 months, and creates a new playlist with those tracks.

Controlling playback:

Write a React component that shows the currently playing track on Spotify and provides play/pause and skip controls. Use the Web API player endpoints.

Reviewing AI-generated code

AI models can produce code that uses outdated patterns or misses important details. Here's a checklist for reviewing Spotify API code before shipping it:

Authorization flow: Is it using the right OAuth flow? Client Credentials should only be used for public data. User data requires Authorization Code with PKCE, or Authorization Code if the app has a secure backend. It should never use the deprecated Implicit Grant flow.
Redirect URIs: Are redirect URIs using HTTPS? The only exception is http://127.0.0.1 for local development. Never use http://localhost or wildcard URIs. See the Redirect URI guide.
Scopes: Does it request only the scopes it actually needs? Missing scopes cause 403 errors; overly broad scopes violate the principle of least privilege.
Token management: Are tokens stored securely? Is the Client Secret kept out of client-side code? For long-running apps, does it refresh tokens before they expire?
Rate limiting: Does it handle 429 responses with exponential backoff using the Retry-After header, rather than retrying in a tight loop?
Error handling: Does it handle all HTTP error codes documented in the OpenAPI schema? Does it read returned error messages and surface them to the user?
Endpoint freshness: Are the endpoints current? AI models trained on older data may use deprecated endpoints. Cross-check against the API reference.
Terms compliance: Does the code comply with the Developer Terms of Service? Watch for excessive caching, missing attribution, or data misuse.