Spotify MCP server for AI agents

Let Claude, ChatGPT or your own agent read Spotify: 35 typed functions through one MCP server. No Spotify API key needed.

Functions
35
Sign-in
Not needed
Works with
MCP, HTTP, Node, Python

Connect

Just Spotify

An MCP server for Spotify alone, with one tool per function. Paste it into Claude, ChatGPT, Cursor or any MCP client as a remote server.

https://api.bowmark.ai/mcp/site/spotify
Every site

One MCP server for Spotify and every other site Bowmark covers. Your agent looks up what it needs and calls it.

https://api.bowmark.ai/mcp
Set it up in your client

Both need a Bowmark API key. The quickstart gets you one and a first result in a few minutes.

Functions

Open a function to see its arguments, what it returns and how to call it.

Read 35
  • browseCategoryBrowse a Spotify category's page (a genre or mood) as its sections of editorial playlists.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyBrowseCategory

    interface SpotifyBrowseItem {
      kind: "playlist" | "album" | "artist" | "track" | "category" | "other";
      id: string | null;
      uri: string;
      name: string;
      description: string | null;
      imageUrl: string | null;
    }
    
    interface SpotifyBrowseSection {
      title: string;
      items: SpotifyBrowseItem[];
    }
    
    interface SpotifyBrowseCategory {
      categoryId: string;
      /** the category's own name, e.g. "Pop" */
      title: string | null;
      sections: SpotifyBrowseSection[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/browseCategory

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.browseCategory("0JQ5DAqbMKFEC4WFtoNRpw");
  • getAlbumGet details about a specific album.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyAlbum

    interface SpotifyAlbum {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      release_date: string;
      total_tracks: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getAlbum

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getAlbum("2noRn2Aes5aoNVsU6iWThc");
  • getArtistGet details about a specific artist.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyArtist

    interface SpotifyArtist {
      id: string;
      name: string;
      genres: string[];
      popularity: number;
      followers: { total: number };
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getArtist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getArtist("4tZwfgrHOc3mvqYlEYSvVi");
  • getAvailableMarketsList the two-letter country codes of every market Spotify is available in.

    Arguments

    None.

    Returns SpotifyMarkets

    interface SpotifyMarkets {
      markets: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getAvailableMarkets

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getAvailableMarkets();
  • getChartGet Spotify's featured charts by type and country.

    Arguments

    NameTypeRequired
    opts{ type?: SpotifyChartType }No
    export type SpotifyChartType = "tracks" | "albums" | "artists";

    Returns SpotifyChart

    export type SpotifyChartType = "tracks" | "albums" | "artists";
    
    interface SpotifyChartEntry {
      rank: number;
      previousRank: number | null;
      peakRank: number | null;
      status: string | null; // "NO_CHANGE", the chart's own entryStatus labels; read the values off a result, never guess one from prose
      id: string | null;
      uri: string | null;
      name: string;
      artists: { id: string | null; name: string }[]; // empty for an artists chart
      imageUrl: string | null;
    }
    
    interface SpotifyChart {
      type: SpotifyChartType;
      title: string;
      date: string | null;
      recurrence: string | null; // WEEKLY
      country: string | null; // GLOBAL
      entries: SpotifyChartEntry[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getChart

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getChart({ type: "tracks" });
  • getCurrentPlaybackGet the signed-in user's current playback state.

    Arguments

    None.

    Returns SpotifyCurrentPlayback

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyCurrentPlayback {
      isPlaying: boolean;
      progressMs: number | null;
      item: SpotifyTrack | null;
      shuffleState: boolean;
      repeatState: string | null;
      device: { id: string | null; name: string; type: string } | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getCurrentPlayback

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getCurrentPlayback();
  • getDevicesGet the signed-in user's available devices.

    Arguments

    None.

    Returns { devices: SpotifyDevice[] }

    interface SpotifyDevice {
      id: string | null;
      isActive: boolean;
      isRestricted: boolean;
      name: string;
      type: string;
      volumePercent: number | null;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getDevices

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getDevices();
  • getEpisodeGet details about a specific podcast episode.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyEpisode

    interface SpotifyEpisode {
      id: string;
      name: string;
      description: string;
      releaseDate: string;
      durationMs: number;
      explicit: boolean;
      show?: { id: string; name: string };
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getEpisode

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getEpisode("512ojhOuo1ktJprKbVcKyQ");
  • getFeaturedPlaylistsGet the featured shelves (trending, popular, radio and chart playlists) on Spotify's signed-out home page.

    Arguments

    None.

    Returns SpotifyFeatured

    interface SpotifyBrowseItem {
      kind: "playlist" | "album" | "artist" | "track" | "category" | "other";
      id: string | null;
      uri: string;
      name: string;
      description: string | null;
      imageUrl: string | null;
    }
    
    interface SpotifyBrowseSection {
      title: string;
      items: SpotifyBrowseItem[];
    }
    
    interface SpotifyFeatured {
      sections: SpotifyBrowseSection[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getFeaturedPlaylists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getFeaturedPlaylists();
  • getGenreSeedsList the genre seed values Spotify's catalog recognizes.

    Arguments

    None.

    Returns SpotifyGenreSeeds

    interface SpotifyGenreSeeds {
      genres: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getGenreSeeds

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getGenreSeeds();
  • getLibraryAlbumsGet the signed-in user's saved albums.

    Arguments

    NameTypeRequired
    opts{ limit?: number; offset?: number }No

    Returns { albums: { addedAt: string | null; album: SpotifyAlbum }[]; total: number }

    interface SpotifyAlbum {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      release_date: string;
      total_tracks: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getLibraryAlbums

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getLibraryAlbums();
  • getLibraryArtistsGet the signed-in user's followed artists.

    Arguments

    NameTypeRequired
    opts{ limit?: number; after?: string }No

    Returns { artists: SpotifyArtist[]; total: number; after: string | null }

    interface SpotifyArtist {
      id: string;
      name: string;
      genres: string[];
      popularity: number;
      followers: { total: number };
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getLibraryArtists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getLibraryArtists();
  • getLibraryPlaylistsGet the signed-in user's playlists.

    Arguments

    NameTypeRequired
    opts{ limit?: number; offset?: number }No

    Returns { playlists: SpotifyPlaylist[]; total: number }

    interface SpotifyPlaylist {
      id: string;
      name: string;
      description: string;
      owner: { id: string; display_name: string };
      images: { url: string }[];
      tracks: { total: number };
      public: boolean;
      collaborative: boolean;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getLibraryPlaylists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getLibraryPlaylists();
  • getLibraryTracksGet the signed-in user's saved tracks.

    Arguments

    NameTypeRequired
    opts{ limit?: number; offset?: number }No

    Returns { tracks: { addedAt: string | null; track: SpotifyTrack }[]; total: number }

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getLibraryTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getLibraryTracks();
  • getLyricsA track's lyrics as Spotify's lyrics panel shows them, line by line (time-synced when available).

    Arguments

    NameTypeRequired
    trackstringYes

    Returns SpotifyLyrics

    interface SpotifyLyrics {
      trackId: string;
      /** false when Spotify has no lyrics for this track */
      available: boolean;
      syncType: string | null; // "LINE_SYNCED" | "UNSYNCED" …
      language: string | null;
      provider: string | null; // e.g. "Musixmatch"
      /** startTimeMs is null when the lyrics are not time-synced */
      lines: { startTimeMs: number | null; words: string }[];
      /** the lines joined with newlines */
      text: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getLyrics

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getLyrics("0DiWol3AO6WpXZgp0goxAV");
  • getOEmbedGet oEmbed metadata (title, thumbnail, embeddable player) for a track, album, artist, playlist, episode or show.

    Arguments

    NameTypeRequired
    inputstringYes
    typeSpotifyOEmbedTypeNo
    type SpotifyOEmbedType = "track" | "album" | "artist" | "playlist" | "episode" | "show";

    Returns SpotifyOEmbed

    interface SpotifyOEmbed {
      title: string;
      type: string;
      thumbnailUrl: string | null;
      html: string;
      iframeUrl: string | null;
      providerName: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getOEmbed

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getOEmbed("0DiWol3AO6WpXZgp0goxAV", "track");
  • getPlaylistGet details about a specific playlist.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyPlaylist

    interface SpotifyPlaylist {
      id: string;
      name: string;
      description: string;
      owner: { id: string; display_name: string };
      images: { url: string }[];
      tracks: { total: number };
      public: boolean;
      collaborative: boolean;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getPlaylist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getPlaylist("37i9dQZF1DXaQ34lqGBfrU");
  • getPlaylistCoverImageGet a playlist's cover image urls, largest first.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyPlaylistCover

    interface SpotifyPlaylistCover {
      playlistId: string;
      images: { url: string; height?: number; width?: number }[];   // largest first; [] when no cover
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getPlaylistCoverImage

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getPlaylistCoverImage("37i9dQZF1DXaQ34lqGBfrU");
  • getPodcastGet details about a specific podcast show.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyShow

    interface SpotifyShow {
      id: string;
      name: string;
      description: string;
      publisher: string;
      explicit: boolean;
      mediaType: string;
      totalEpisodes: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getPodcast

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getPodcast("38bS44xjbVVZ3No3ByF1dJ");
  • getRecentlyPlayedGet the signed-in user's recently played tracks.

    Arguments

    NameTypeRequired
    opts{ limit?: number; before?: number; after?: number }No

    Returns { items: { playedAt: string; track: SpotifyTrack }[]; cursors: { before: string | null; after: string | null } }

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getRecentlyPlayed

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getRecentlyPlayed();
  • getRecommendationsGet the tracks Spotify recommends for a seed track.

    Arguments

    NameTypeRequired
    trackIdstringYes

    Returns SpotifyRecommendations

    interface SpotifyRecommendations {
      seedTrackId: string;
      tracks: {
        id: string;
        uri: string;
        name: string;
        artists: { id: string; name: string }[];
        album: { id: string } | null;
        durationMs: number | null;
        /** lifetime play count Spotify shows on the track */
        playcount: number | null;
        imageUrl: string | null;
      }[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getRecommendations

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getRecommendations("0DiWol3AO6WpXZgp0goxAV");
  • getRecommendationsByArtistGet what Spotify recommends alongside a seed artist: related artists, featuring playlists and appears-on releases.

    Arguments

    NameTypeRequired
    artistIdstringYes

    Returns SpotifyArtistRecommendations

    interface SpotifyArtistRecommendations {
      seedArtistId: string;
      relatedArtists: { id: string; uri: string; name: string; imageUrl: string | null }[];
      featuringPlaylists: {
        id: string;
        uri: string;
        name: string;
        owner: string | null;
        imageUrl: string | null;
      }[];
      appearsOn: {
        id: string;
        uri: string;
        name: string;
        type: string | null;
        year: number | null;
        artists: { id: string; name: string }[];
        imageUrl: string | null;
      }[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getRecommendationsByArtist

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getRecommendationsByArtist("4tZwfgrHOc3mvqYlEYSvVi");
  • getRelatedArtistsGet the artists Spotify lists as "Fans also like" for an artist.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyRelatedArtists

    interface SpotifyRelatedArtists {
      artistId: string;
      /** how many related artists Spotify reports */
      totalCount: number;
      artists: { id: string; uri: string; name: string; imageUrl: string | null }[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getRelatedArtists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getRelatedArtists("4tZwfgrHOc3mvqYlEYSvVi");
  • getTopArtistsGet the signed-in user's top artists.

    Arguments

    NameTypeRequired
    timeRange"short_term" | "medium_term" | "long_term"
    Default "medium_term".
    No
    limitnumber
    1-50, default 20.
    No
    offsetnumberNo

    Returns SpotifyTopArtists

    interface SpotifyArtist {
      id: string;
      name: string;
      genres: string[];
      popularity: number;
      followers: { total: number };
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyTopArtists { artists: SpotifyArtist[]; total: number }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getTopArtists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getTopArtists();
  • getTopTracksGet the signed-in user's top tracks.

    Arguments

    NameTypeRequired
    timeRange"short_term" | "medium_term" | "long_term"
    Default "medium_term".
    No
    limitnumber
    1-50, default 20.
    No
    offsetnumberNo

    Returns SpotifyTopTracks

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyTopTracks { tracks: SpotifyTrack[]; total: number }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getTopTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getTopTracks();
  • getTrackGet details about a specific track including audio features.

    Arguments

    NameTypeRequired
    idstringYes

    Returns SpotifyTrack

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getTrack

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getTrack("0DiWol3AO6WpXZgp0goxAV");
  • getUserProfileGet the signed-in user's profile information.

    Arguments

    None.

    Returns SpotifyUserProfile

    interface SpotifyUserProfile {
      id: string;
      displayName: string | null;
      country: string | null;
      product: string | null; // "premium" | "free" …
      followers: number;
      images: { url: string }[];
      url: string;
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/getUserProfile

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.getUserProfile();
  • listAlbumTracksGet a page of an album's track listing.

    Arguments

    NameTypeRequired
    idstringYes
    opts.limitnumber
    1-50, default 50.
    No
    opts.offsetnumber
    Default 0.
    No

    Returns SpotifyAlbumTracksResult

    interface SpotifyAlbumTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      durationMs: number;
      explicit: boolean;
      trackNumber: number;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyAlbumTracksResult {
      albumId: string;
      tracks: SpotifyAlbumTrack[];
      total: number;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/listAlbumTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.listAlbumTracks("2noRn2Aes5aoNVsU6iWThc");
  • listArtistAlbumsGet a page of an artist's discography.

    Arguments

    NameTypeRequired
    idstringYes
    opts.includeGroups("album" | "single" | "compilation" | "appears_on")[]
    Default all four.
    No
    opts.limitnumber
    1-50, default 20.
    No
    opts.offsetnumber
    Default 0.
    No
    opts.marketstring
    Two-letter country, e.g. "US".
    No

    Returns SpotifyPagedAlbums

    interface SpotifySimpleAlbum {
      id: string;
      name: string;
      albumType: string;
      artists: { id: string; name: string }[];
      releaseDate: string;
      totalTracks: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyPagedAlbums {
      albums: SpotifySimpleAlbum[];
      total: number;
      limit: number;
      offset: number;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/listArtistAlbums

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.listArtistAlbums("4tZwfgrHOc3mvqYlEYSvVi");
  • listArtistTracksGet an artist's top tracks.

    Arguments

    NameTypeRequired
    idstringYes
    marketstringNo

    Returns SpotifyTrack[]

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/listArtistTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.listArtistTracks("4tZwfgrHOc3mvqYlEYSvVi");
  • listNewReleasesGet a page of Spotify's new-release albums for a market.

    Arguments

    NameTypeRequired
    limitnumber
    1-50, default 20.
    No
    offsetnumber
    Default 0.
    No
    countrystring
    Two-letter country, e.g. "US".
    No

    Returns SpotifyPagedAlbums

    interface SpotifySimpleAlbum {
      id: string;
      name: string;
      albumType: string;
      artists: { id: string; name: string }[];
      releaseDate: string;
      totalTracks: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyPagedAlbums {
      albums: SpotifySimpleAlbum[];
      total: number;
      limit: number;
      offset: number;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/listNewReleases

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.listNewReleases({ limit: 1 });
  • listPlaylistTracksGet a page of a playlist's tracks, with when each was added.

    Arguments

    NameTypeRequired
    idstringYes
    opts.limitnumber
    1-100, default 50.
    No
    opts.offsetnumber
    Default 0.
    No
    opts.marketstring
    Two-letter country, e.g. "US".
    No

    Returns SpotifyPlaylistTracksResult

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyPlaylistTrackItem {
      addedAt: string | null;
      track: SpotifyTrack | null;  // null for a local file or a podcast episode
    }
    
    interface SpotifyPlaylistTracksResult {
      playlistId: string;
      items: SpotifyPlaylistTrackItem[];
      total: number;
      limit: number;
      offset: number;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/listPlaylistTracks

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.listPlaylistTracks("37i9dQZF1DXaQ34lqGBfrU");
  • searchMyLibrarySearch only the signed-in user's own library (Liked Songs, saved albums, followed artists, playlists) by keyword.

    Arguments

    NameTypeRequired
    querystringYes
    opts{ types?: ("track" | "album" | "artist" | "playlist")[]; maxScan?: number }No

    Returns SpotifyLibrarySearchResult

    interface SpotifyTrack {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      album?: { id: string; name: string };
      duration_ms: number;
      explicit: boolean;
      popularity: number;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyAlbum {
      id: string;
      name: string;
      artists: { id: string; name: string }[];
      release_date: string;
      total_tracks: number;
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyArtist {
      id: string;
      name: string;
      genres: string[];
      popularity: number;
      followers: { total: number };
      images: { url: string; height?: number; width?: number }[];
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyPlaylist {
      id: string;
      name: string;
      description: string;
      owner: { id: string; display_name: string };
      images: { url: string }[];
      tracks: { total: number };
      public: boolean;
      collaborative: boolean;
      external_urls: { spotify: string };
      uri: string;
    }
    
    interface SpotifyLibrarySearchResult {
      query: string;
      tracks: SpotifyTrack[];
      albums: SpotifyAlbum[];
      artists: SpotifyArtist[];
      playlists: SpotifyPlaylist[];
      /** how many items of each type were read */
      scanned: { track?: number; album?: number; artist?: number; playlist?: number };
      /** false when the library was larger than maxScan for some type */
      complete: boolean;
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/searchMyLibrary

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.searchMyLibrary("daft punk");
  • searchPlaylistsSearch Spotify for playlists by keyword.

    Arguments

    NameTypeRequired
    querystringYes
    opts{ limit?: number; market?: string }No

    Returns SpotifySearchResult

    type SpotifySearchType = "track" | "album" | "artist" | "playlist" | "show" | "episode";
    
    interface SpotifySearchItem {
      type: SpotifySearchType;
      id: string;
      name: string;
      uri: string;                   // spotify:track:…
      url: string | null;            // open.spotify.com link
      artists: string[];
      album: string | null;
      owner: string | null;          // playlist owner or podcast publisher
      releaseDate: string | null;
      durationMs: number | null;
      explicit: boolean | null;
      image: string | null;
    }
    
    interface SpotifySearchResult {
      query: string;
      results: SpotifySearchItem[];
      totals: Partial<Record<SpotifySearchType, number>>;
      warnings: string[];
    }

    HTTP endpoint

    POST https://api.bowmark.ai/v1/sites/spotify/searchPlaylists

    Call it

    import { bowmark } from "@bowmark/web";
    
    const result = await bowmark.providers.spotify.searchPlaylists("daft punk", { limit: 1 });

Use it from code