CONNECT APP
Build with Spotify
Entertainment
- OAuth
MCP
Give your agent Spotify tools
Every Spotify action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's Spotify account for each tool call — you store no tokens.
// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
"x-pd-app-slug": "spotify",
},
},
},
)
const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)
const { tools } = await mcp.listTools()
// e.g. run Add Items to a Playlist:
const result = await mcp.callTool({
name: "spotify-add-items-to-playlist",
arguments: {
playlistId: "Playlist ID",
uris: ["Track or Episode URIs"],
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"x-pd-project-id": "{project_id}",
"x-pd-environment": "production",
"x-pd-external-user-id": "{external_user_id}", # any stable ID for this user in your system
"x-pd-app-slug": "spotify",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Add Items to a Playlist:
result = await session.call_tool("spotify-add-items-to-playlist", {
"playlistId": "Playlist ID",
"uris": ["Track or Episode URIs"],
})API PROXY
Call the Spotify API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the Spotify API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://api.spotify.com/v1/me",
})
// Any allowed Spotify endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# The path segment is the target URL, URL-safe base64 encoded:
# https://api.spotify.com/v1/me
curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly9hcGkuc3BvdGlmeS5jb20vdjEvbWU?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
-H "Authorization: Bearer {access_token}" \
-H "x-pd-environment: production"SDK
Run Spotify actions from your backend
Connect a user's Spotify account once, then run Add Items to a Playlist on their behalf from your own code — TypeScript, Python, or plain HTTP.
import { PipedreamClient } from "@pipedream/sdk"
const pd = new PipedreamClient({
projectId: process.env.PIPEDREAM_PROJECT_ID!,
clientId: process.env.PIPEDREAM_CLIENT_ID!,
clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
projectEnvironment: "production",
})
const result = await pd.actions.run({
id: "spotify-add-items-to-playlist",
externalUserId: "{external_user_id}", // any stable ID for this user in your system
configuredProps: {
spotify: { authProvisionId: "apn_xxxxxxx" },
playlistId: "Playlist ID",
uris: ["Track or Episode URIs"],
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="spotify-add-items-to-playlist",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"spotify": {"authProvisionId": "apn_xxxxxxx"},
"playlistId": "Playlist ID",
"uris": ["Track or Episode URIs"],
},
)curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
-H "Content-Type: application/json" \
-H "X-PD-Environment: production" \
-H "Authorization: Bearer {access_token}" \
-d '{
"external_user_id": "{external_user_id}",
"id": "spotify-add-items-to-playlist",
"configured_props": {
"spotify": { "authProvisionId": "apn_xxxxxxx" },
"playlistId": "Playlist ID",
"uris": ["Track or Episode URIs"]
}
}'TOOLS
Spotify actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Add Items to a Playlist
actionAdd tracks or podcast episodes to an existing Spotify playlist that the current user can modify. Use List Playlist ID Options to find the playlist ID, or Create a Playlist to make a new one first. Items are identified by Spotify URI, not bare ID: tracks asspotify:track:<id>and episodes asspotify:episode:<id>. Use Search with typetrackorepisodeto find them: pass theurifromtracks.items[]orepisodes.items[]. Up to 100 items per call; split larger batches into several calls. Items are added in the order given, appended to the end unlessPositionis set. Returns{ snapshot_id }, the playlist's new version ID. Use Get a Playlist's Items to confirm the result, or Remove Items from a Playlist to undo. See the documentationWritev0.2.0 -
Create a Playlist
actionCreate a playlist for a Spotify user. The playlist will be empty until you add tracks. See the docs here.Writev0.1.9 -
Get a Category's Playlists
actionGet a list of Spotify playlists tagged with a particular category. See the docs here.Read-onlyv0.1.8 -
Get a Playlist
actionGet a playlist owned by a Spotify user. See the documentation.Read-onlyv0.0.9 -
Get a Playlist's Items
actionGet full details of the items of a playlist owned by a Spotify user. See the docs here.Read-onlyv0.1.8 -
Get a Track
actionGet a track by its name or ID. See the docs hereRead-onlyv0.1.8 -
Get Album Tracks
actionGet all tracks in an album. See the docs hereRead-onlyv0.0.9 -
Get All Tracks by Artist
actionGet Spotify tracks information related with an artist's. see docs here.Read-onlyv0.1.8 -
Get an Artist's Top Tracks
actionGet Spotify catalog information about an artist's top tracks by country. See the docs here.Read-onlyv0.1.8 -
Get Audio Features for a Track
actionGet audio feature information for a single track identified by its unique Spotify ID. See the docs here.Read-onlyv0.1.8 -
Get currently playing track
actionGet the object currently being played on the user's Spotify account. See the documentationRead-onlyv0.0.9 -
Get Recommendations
actionCreate a list of recommendations based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details. See the docs here.Writev0.1.9 -
List Category ID Options
actionList Spotify browse categories, as{ label, value }options wherevalueis the category ID (e.g.party). Results are paginated 50 per page;pageis zero-based, so call with0, then1, and so on until fewer than 50 options (or none) are returned. See the documentationRead-onlyv0.0.4 -
List Playlist ID Options
actionList playlists owned or followed by the current user, as{ label, value }options wherevalueis the playlist ID (e.g.3cEYpjA9oz9GiPac4AsH4n). Results are paginated 50 per page;pageis zero-based, so call with0, then1, and so on until fewer than 50 options (or none) are returned. See the documentationRead-onlyv0.0.4 -
List Seed Genres Options
actionRetrieves available options for the Seed Genres field.Read-onlyv0.0.4 -
List Track ID Options
actionList tracks saved in the current user's Liked Songs, as{ label, value }options wherevalueis the track ID (e.g.4iV5W9uYEdYUVa79Axb7Rh). Use it to find track IDs to pass to actions such as Remove User's Saved Tracks. Results are paginated 50 per page;pageis zero-based, so call with0, then1, and so on until fewer than 50 options (or none) are returned. See the documentationRead-onlyv0.0.4 -
Remove Items from a Playlist
actionRemove one or more items from a user's playlist. See the docs hereWritev0.1.8 -
Remove User's Saved Tracks
actionRemove one or more tracks from the current user's 'Your Music' library. See the docs hereWritev0.1.8 -
Save Tracks for User
actionSave one or more tracks to the current user's "Your Music" library. See the docs here.Writev0.1.8 -
Search
actionSearch for items on Spotify (tracks, albums, artists, playlists, shows, or episodes). See the docs hereRead-onlyv0.0.7
EVENTS
Spotify triggers
Event sources your backend can deploy for users and receive through a webhook.
-
New Playlist
triggerEmit new event when a new playlist is created or followed by the current Spotify user.v0.1.7 -
New Saved Track
triggerEmit new event for each new track saved to the current Spotify user's Music Library.v0.1.7 -
New Track by Artist
triggerEmit new event for each new Spotify track related with an artist. See the documentationv0.1.7 -
New Track in Playlist
triggerEmit new event for each new Spotify track added to a playlistv0.1.7
MULTI-APP
Use Spotify with other popular apps
Most products don't stop at one integration. Pair Spotify with the other apps your users rely on, and ship use cases that span both.
- App slug
- spotify
- Authentication
- OAuth
- Categories
- Entertainment
- Actions
- 20
- Triggers
- 4
- API proxy
- Available
OAuth scopes
These are the scopes Pipedream's managed Spotify OAuth client requests when one of your users connects an account. Supply your own OAuth client to request a different set.
- playlist-read-collaborative
- playlist-modify-private
- playlist-modify-public
- playlist-read-private
- user-modify-playback-state
- user-read-currently-playing
- user-read-playback-state
- user-read-private
- user-read-email
- user-library-modify
- user-library-read
- user-follow-modify
- user-follow-read
- user-read-recently-played
- user-top-read
- streaming
- app-remote-control
- ugc-image-upload
- user-read-playback-position