{"openapi":"3.0.3","info":{"title":"Spotify API (ReefAPI)","version":"0.1.2","description":"Spotify API — artist monthly listeners and followers, track and album play counts, playlists, search, charts, podcasts, audiobooks and concerts Call POST /spotify/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/spotify-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Spotify API documentation","url":"https://reefapi.com/docs/spotify"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"spotify","description":"Spotify API — artist monthly listeners and followers, track and album play counts, playlists, search, charts, podcasts, audiobooks and concerts"}],"paths":{"/spotify/v1/artist":{"post":{"operationId":"spotify_artist","summary":"Everything on one Spotify artist page: monthly listeners, followers, world rank, the top 5 listener cities, verified badge, biography, social links, avatar / header / gallery images, the 10 most popul","description":"Everything on one Spotify artist page: monthly listeners, followers, world rank, the top 5 listener cities, verified badge, biography, social links, avatar / header / gallery images, the 10 most popular tracks with their all-time play counts, latest and popular releases, the first albums / singles / compilations with totals, related artists, appears-on releases, playlists featuring the artist, the artist's own playlists, upcoming concerts and merch.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/artist_stats":{"post":{"operationId":"spotify_artist_stats","summary":"The numbers of one artist in one small call: followers, monthly listeners, world rank, top 5 listener cities with listener counts, verified / registered flags, biography, social links and gallery.","description":"The numbers of one artist in one small call: followers, monthly listeners, world rank, top 5 listener cities with listener counts, verified / registered flags, biography, social links and gallery.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_top_tracks":{"post":{"operationId":"spotify_artist_top_tracks","summary":"The artist's 10 most popular tracks (Spotify's order) with each track's all-time play count, duration, album and artists.","description":"The artist's 10 most popular tracks (Spotify's order) with each track's all-time play count, duration, album and artists.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/artist_discography":{"post":{"operationId":"spotify_artist_discography","summary":"One page of an artist's releases: everything, or only albums / singles / compilations, newest or oldest first, with release date, label, track count, cover and copyright lines.","description":"One page of an artist's releases: everything, or only albums / singles / compilations, newest or oldest first, with release date, label, track count, cover and copyright lines.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"type":{"type":"string","enum":["all","albums","singles","compilations"],"default":"all","pattern":"(?i)(?:album|compilation|ep|eps|everything|single)","description":"Which releases (singular works too: album, single, compilation)."},"sort":{"type":"string","enum":["newest","oldest"],"default":"newest","pattern":"(?i)(?:asc|date[-_ ]asc|date[-_ ]desc|date_asc|date_desc|desc|earliest|latest|new|old)","description":"Order."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"Rows per page (1-100)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_related":{"post":{"operationId":"spotify_artist_related","summary":"Artists Spotify lists under \"Fans also like\" for this artist (Spotify's whole list in one call, 40 measured 2026-11-15; `total` says how many Spotify keeps).","description":"Artists Spotify lists under \"Fans also like\" for this artist (Spotify's whole list in one call, 40 measured 2026-11-15; `total` says how many Spotify keeps).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_appears_on":{"post":{"operationId":"spotify_artist_appears_on","summary":"Releases by other artists this artist appears on","description":"Releases by other artists this artist appears on. Spotify serves the first 50 to a logged-out viewer; `total` is its full count.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_discovered_on":{"post":{"operationId":"spotify_artist_discovered_on","summary":"Playlists where listeners discovered this artist (Spotify serves the first 50; `total` is its full count)","description":"Playlists where listeners discovered this artist (Spotify serves the first 50; `total` is its full count). Spotify hides some entries from logged-out viewers; those are counted in `hidden_count`, not returned.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_featuring":{"post":{"operationId":"spotify_artist_featuring","summary":"Spotify playlists featuring the artist (This Is …, Radio, editorial playlists).","description":"Spotify playlists featuring the artist (This Is …, Radio, editorial playlists).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_playlists":{"post":{"operationId":"spotify_artist_playlists","summary":"Public playlists the artist curates on their own profile.","description":"Public playlists the artist curates on their own profile.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_concerts":{"post":{"operationId":"spotify_artist_concerts","summary":"The artist's upcoming concerts on Spotify (date, venue, city, line-up).","description":"The artist's upcoming concerts on Spotify (date, venue, city, line-up).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/artist_radio":{"post":{"operationId":"spotify_artist_radio","summary":"The artist's radio: the \"<artist> Radio\" playlist Spotify generates, with its tracks (play counts included).","description":"The artist's radio: the \"<artist> Radio\" playlist Spotify generates, with its tracks (play counts included).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artist_id":{"type":"string","example":"06HL4z0CvFAxyc27GXpf02","description":"Spotify artist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page (1-100)."}},"required":["artist_id"]},"example":{"artist_id":"06HL4z0CvFAxyc27GXpf02"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/track":{"post":{"operationId":"spotify_track","summary":"One track: all-time play count, duration, explicit / playable flags, artists, album (type, release date, label, copyrights, cover), the 30-second preview link and the full credits (writers, producers,","description":"One track: all-time play count, duration, explicit / playable flags, artists, album (type, release date, label, copyrights, cover), the 30-second preview link and the full credits (writers, producers, performers with roles, and the label / distributor credited as source).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/track_playcount":{"post":{"operationId":"spotify_track_playcount","summary":"Just the all-time play count of one track, with its name, artists and duration — the small call for play-count tracking (one track per call; `album` returns the play count of every track on an album i","description":"Just the all-time play count of one track, with its name, artists and duration — the small call for play-count tracking (one track per call; `album` returns the play count of every track on an album in one call).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/track_credits":{"post":{"operationId":"spotify_track_credits","summary":"Songwriters, producers, performers and other contributors of a track with their roles, plus the label / distributor credited as source.","description":"Songwriters, producers, performers and other contributors of a track with their roles, plus the label / distributor credited as source.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/track_previews":{"post":{"operationId":"spotify_track_previews","summary":"The public 30-second MP3 preview link of up to 50 tracks (null where Spotify publishes none).","description":"The public 30-second MP3 preview link of up to 50 tracks (null where Spotify publishes none).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_ids":{"type":"array","items":{"type":"string"},"example":"4uLU6hMCjMI75M1A2tKUQC","description":"Up to 50 Spotify track ids, URIs or links (array, or one comma-separated string)."}},"required":["track_ids"]},"example":{"track_ids":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/track_related":{"post":{"operationId":"spotify_track_related","summary":"Tracks Spotify recommends next to this one on its track page (with play counts).","description":"Tracks Spotify recommends next to this one on its track page (with play counts).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20,"description":"How many tracks (1-50)."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/track_similar_albums":{"post":{"operationId":"spotify_track_similar_albums","summary":"Albums Spotify lists as similar to the album this track is on.","description":"Albums Spotify lists as similar to the album this track is on.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"How many albums (1-100); Spotify keeps 60-70 per track."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/track_radio":{"post":{"operationId":"spotify_track_radio","summary":"The track's radio: the \"<track> Radio\" playlist Spotify generates, with its tracks.","description":"The track's radio: the \"<track> Radio\" playlist Spotify generates, with its tracks.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"track_id":{"type":"string","example":"4uLU6hMCjMI75M1A2tKUQC","description":"Spotify track: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page (1-100)."}},"required":["track_id"]},"example":{"track_id":"4uLU6hMCjMI75M1A2tKUQC"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/album":{"post":{"operationId":"spotify_album","summary":"One album with every track and each track's all-time play count, label, release date, copyrights, disc count, other editions and more albums by the artist.","description":"One album with every track and each track's all-time play count, label, release date, copyrights, disc count, other editions and more albums by the artist.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"album_id":{"type":"string","example":"4m2880jivSbbyEGAKfITCa","description":"Spotify album: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["album_id"]},"example":{"album_id":"4m2880jivSbbyEGAKfITCa"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/album_tracks":{"post":{"operationId":"spotify_album_tracks","summary":"One page of an album's tracks with play counts.","description":"One page of an album's tracks with play counts.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"album_id":{"type":"string","example":"4m2880jivSbbyEGAKfITCa","description":"Spotify album: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":300,"default":50,"example":50,"description":"Rows per page (1-300)."}},"required":["album_id"]},"example":{"album_id":"4m2880jivSbbyEGAKfITCa"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/playlist":{"post":{"operationId":"spotify_playlist","summary":"One playlist: name, description, owner, followers, collaborators, last update, chart info for chart playlists, and its first rows — each with position, date added, the track's play count, BPM and musi","description":"One playlist: name, description, owner, followers, collaborators, last update, chart info for chart playlists, and its first rows — each with position, date added, the track's play count, BPM and musical key, and for chart playlists the chart position, previous position, movement and plays.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"playlist_id":{"type":"string","example":"37i9dQZEVXbMDoHDwVN2tF","description":"Spotify playlist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":100,"example":100,"description":"How many rows (1-100)."}},"required":["playlist_id"]},"example":{"playlist_id":"37i9dQZEVXbMDoHDwVN2tF"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/playlist_tracks":{"post":{"operationId":"spotify_playlist_tracks","summary":"One page of a playlist's rows (tracks and episodes) in playlist order, same row shape as `playlist`.","description":"One page of a playlist's rows (tracks and episodes) in playlist order, same row shape as `playlist`.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"playlist_id":{"type":"string","example":"37i9dQZEVXbMDoHDwVN2tF","description":"Spotify playlist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":100,"example":100,"description":"Rows per page (1-100)."}},"required":["playlist_id"]},"example":{"playlist_id":"37i9dQZEVXbMDoHDwVN2tF"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/playlist_followers":{"post":{"operationId":"spotify_playlist_followers","summary":"Just the follower count of a playlist (the cheap call for follower tracking).","description":"Just the follower count of a playlist (the cheap call for follower tracking).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"playlist_id":{"type":"string","example":"37i9dQZEVXbMDoHDwVN2tF","description":"Spotify playlist: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["playlist_id"]},"example":{"playlist_id":"37i9dQZEVXbMDoHDwVN2tF"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/search":{"post":{"operationId":"spotify_search","summary":"Spotify search","description":"Spotify search. `type: all` returns the top results plus the first rows and the total of every section (tracks, artists, albums, playlists, podcasts, episodes, audiobooks, genres, users); any other type returns one paged list (up to 100 rows per page). Spotify serves the first 1000 results of a query (page × limit ≤ 1000). Rows inside one page are always distinct, but Spotify re-ranks track results between requests, so consecutive track pages can repeat rows (measured: \"love\", 4 pages of 25, 23 repeats; artists and playlists 0) — ask for up to 100 rows in one page to avoid it.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"daft punk","description":"Search words."},"type":{"type":"string","enum":["all","tracks","artists","albums","playlists","podcasts","episodes","audiobooks","genres","users"],"default":"all","pattern":"(?i)(?:album|artist|audiobook|book|books|episode|everything|genre|playlist|podcast|profile|profiles|show|shows|song|songs|track|user)","description":"What to search for (singular works too: track, artist, album, playlist, podcast, episode, audiobook, genre, user)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"example":20,"description":"Rows per page (1-100)."}},"required":["query"]},"example":{"query":"daft punk","type":"tracks"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/search_suggestions":{"post":{"operationId":"spotify_search_suggestions","summary":"Autocomplete as typed into the Spotify search box: query completions plus the artists / tracks / albums / playlists it suggests.","description":"Autocomplete as typed into the Spotify search box: query completions plus the artists / tracks / albums / playlists it suggests.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"daft","description":"What the user typed so far."},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10,"example":10,"description":"Maximum suggestions (1-20)."}},"required":["query"]},"example":{"query":"daft punk"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/charts":{"post":{"operationId":"spotify_charts","summary":"Spotify's public global weekly chart (charts.spotify.com): Top Songs, Top Albums or Top Artists, 50 rows with rank, previous rank, peak rank and date, weeks on chart and entry status; songs carry labe","description":"Spotify's public global weekly chart (charts.spotify.com): Top Songs, Top Albums or Top Artists, 50 rows with rank, previous rank, peak rank and date, weeks on chart and entry status; songs carry labels, producers and songwriters.","tags":["spotify"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"chart":{"type":"string","enum":["tracks","albums","artists"],"default":"tracks","pattern":"(?i)(?:album|artist|song|songs|top[-_ ]albums|top[-_ ]artists|top[-_ ]songs|top_albums|top_artists|top_songs|track)","description":"Which global weekly chart (track / album / artist work too)."}}},"example":{"chart":"tracks"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/country_chart":{"post":{"operationId":"spotify_country_chart","summary":"A country's chart playlist on Spotify: `top_songs` (\"Top Songs - <country>\", weekly) or `top_50` (\"Top 50 - <country>\", daily), each row with chart position, previous position, movement, plays and the","description":"A country's chart playlist on Spotify: `top_songs` (\"Top Songs - <country>\", weekly) or `top_50` (\"Top 50 - <country>\", daily), each row with chart position, previous position, movement, plays and the track's all-time play count. `country: global` for the global playlists.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","example":"DE","description":"Two-letter country code (e.g. DE, US, BR, TR) or `global`."},"chart":{"type":"string","enum":["top_songs","top_50"],"default":"top_songs","pattern":"(?i)(?:daily|songs|top50|top[-_ ]50|top[-_ ]songs|top_50|top_songs|topsongs|weekly)","description":"Which chart playlist (also: weekly, daily, top50)."}},"required":["country"]},"example":{"country":"DE"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/home":{"post":{"operationId":"spotify_home","summary":"The home feed Spotify shows logged-out visitors (US): trending songs, popular artists, albums, radio and featured charts, shelf by shelf.","description":"The home feed Spotify shows logged-out visitors (US): trending songs, popular artists, albums, radio and featured charts, shelf by shelf.","tags":["spotify"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"section_limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Items per shelf (1-50)."}}},"example":{"section_limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/browse_categories":{"post":{"operationId":"spotify_browse_categories","summary":"Every Browse-all category (genres, moods, charts, podcasts …) with its id for `browse_category`.","description":"Every Browse-all category (genres, moods, charts, podcasts …) with its id for `browse_category`.","tags":["spotify"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/browse_category":{"post":{"operationId":"spotify_browse_category","summary":"One browse category page (e.g","description":"One browse category page (e.g. Pop): its shelves with their first playlists / albums; a shelf's `id` pages further with `browse_section`.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category_id":{"type":"string","example":"0JQ5DAqbMKFEC4WFtoNRpw","description":"Category id from `browse_categories` (or the open.spotify.com/genre/<id> link)."},"section_limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"example":20,"description":"Items per shelf (1-50)."}},"required":["category_id"]},"example":{"category_id":"0JQ5DAqbMKFEC4WFtoNRpw"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/browse_section":{"post":{"operationId":"spotify_browse_section","summary":"One browse shelf, paged.","description":"One browse shelf, paged.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"section_id":{"type":"string","example":"0JQ5IMCbQBLBdLiG2IRf0j","description":"Shelf id from `browse_category` sections[].id."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page (1-100)."}},"required":["section_id"]},"example":{"section_id":"0JQ5IMCbQBLBdLiG2IRf0j"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/country_hub":{"post":{"operationId":"spotify_country_hub","summary":"A country's music hub on Spotify: its chart playlists, popular artists, popular albums and trending songs.","description":"A country's music hub on Spotify: its chart playlists, popular artists, popular albums and trending songs.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","example":"DE","description":"Two-letter country code."}},"required":["country"]},"example":{"country":"DE"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/podcast":{"post":{"operationId":"spotify_podcast","summary":"One podcast: publisher, description, rating and rating count, topics, explicit flag, episode order, trailer, total episodes and the latest 10 episodes.","description":"One podcast: publisher, description, rating and rating count, topics, explicit flag, episode order, trailer, total episodes and the latest 10 episodes.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"podcast_id":{"type":"string","example":"4rOoJ6Egrf8K2IrywzwOMk","description":"Spotify podcast (show): the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["podcast_id"]},"example":{"podcast_id":"4rOoJ6Egrf8K2IrywzwOMk"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/podcast_episodes":{"post":{"operationId":"spotify_podcast_episodes","summary":"One page of a podcast's episodes, newest first.","description":"One page of a podcast's episodes, newest first.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"podcast_id":{"type":"string","example":"4rOoJ6Egrf8K2IrywzwOMk","description":"Spotify podcast (show): the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page (1-100)."}},"required":["podcast_id"]},"example":{"podcast_id":"4rOoJ6Egrf8K2IrywzwOMk"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":2}},"/spotify/v1/episode":{"post":{"operationId":"spotify_episode","summary":"One podcast episode: description, release time, duration, explicit / paywall flags, media types, transcript flag, 30-second preview and its podcast.","description":"One podcast episode: description, release time, duration, explicit / paywall flags, media types, transcript flag, 30-second preview and its podcast.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"episode_id":{"type":"string","example":"7Hf1JDw7XuetyEqlrIQLaG","description":"Spotify podcast episode: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["episode_id"]},"example":{"episode_id":"7Hf1JDw7XuetyEqlrIQLaG"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/audiobook":{"post":{"operationId":"spotify_audiobook","summary":"One audiobook (US store): authors, narrators, publisher, publish date, duration, rating, price and list price, genres, copyrights, trailer, total chapters and the first 10 chapters.","description":"One audiobook (US store): authors, narrators, publisher, publish date, duration, rating, price and list price, genres, copyrights, trailer, total chapters and the first 10 chapters.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audiobook_id":{"type":"string","example":"2IEBhnu61ieYGFRPEJIO40","description":"Spotify audiobook: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["audiobook_id"]},"example":{"audiobook_id":"2IEBhnu61ieYGFRPEJIO40"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/audiobook_chapters":{"post":{"operationId":"spotify_audiobook_chapters","summary":"One page of an audiobook's chapters in reading order.","description":"One page of an audiobook's chapters in reading order.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audiobook_id":{"type":"string","example":"2IEBhnu61ieYGFRPEJIO40","description":"Spotify audiobook: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."},"page":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":1,"description":"1-based page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50,"description":"Rows per page (1-100)."}},"required":["audiobook_id"]},"example":{"audiobook_id":"2IEBhnu61ieYGFRPEJIO40"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/chapter":{"post":{"operationId":"spotify_chapter","summary":"One audiobook chapter.","description":"One audiobook chapter.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chapter_id":{"type":"string","example":"4twr9j4P9xgnyNFYpuhWDa","description":"Spotify audiobook chapter: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["chapter_id"]},"example":{"chapter_id":"4twr9j4P9xgnyNFYpuhWDa"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/user":{"post":{"operationId":"spotify_user","summary":"A public Spotify user profile: display name, avatar, verified flag, public playlist count and the first 10 public playlists with follower counts.","description":"A public Spotify user profile: display name, avatar, verified flag, public playlist count and the first 10 public playlists with follower counts.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","example":"spotify","description":"Spotify username (e.g. `spotify`), the spotify:user: URI or the open.spotify.com/user/<name> link."}},"required":["user_id"]},"example":{"user_id":"spotify"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/user_playlists":{"post":{"operationId":"spotify_user_playlists","summary":"A user's public playlists with follower counts","description":"A user's public playlists with follower counts. Spotify serves a logged-out viewer the first 10 (offset and larger limits are ignored, measured); `total` is the user's full public playlist count.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","example":"spotify","description":"Spotify username (e.g. `spotify`), the spotify:user: URI or the open.spotify.com/user/<name> link."}},"required":["user_id"]},"example":{"user_id":"spotify"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/concert_locations":{"post":{"operationId":"spotify_concert_locations","summary":"Cities matching a name, each with the geohash `concerts_nearby` takes.","description":"Cities matching a name, each with the geohash `concerts_nearby` takes.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"berlin","description":"City name."}},"required":["query"]},"example":{"query":"daft punk"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/concerts_nearby":{"post":{"operationId":"spotify_concerts_nearby","summary":"Popular upcoming concerts Spotify lists near a city.","description":"Popular upcoming concerts Spotify lists near a city.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"string","example":"berlin","description":"City name (first match is used) or a geohash from `concert_locations`."}},"required":["location"]},"example":{"location":"berlin"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/spotify/v1/concert":{"post":{"operationId":"spotify_concert","summary":"One concert: date and doors time, venue with coordinates, line-up, genres, ticket sellers with links, sale window and price range, festival flag, age restriction and related concerts.","description":"One concert: date and doors time, venue with coordinates, line-up, genres, ticket sellers with links, sale window and price range, festival flag, age restriction and related concerts.","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"concert_id":{"type":"string","example":"5aVmPSGVZQza7QII6UjVbe","description":"Spotify concert: the 22-character id, the spotify: URI or the open.spotify.com link (spotify.link short links too)."}},"required":["concert_id"]},"example":{"concert_id":"5aVmPSGVZQza7QII6UjVbe"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/spotify/v1/resolve":{"post":{"operationId":"spotify_resolve","summary":"Any Spotify link, URI or spotify.link short link → its type, id, canonical link and URI (no lookup of the item itself).","description":"Any Spotify link, URI or spotify.link short link → its type, id, canonical link and URI (no lookup of the item itself).","tags":["spotify"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"string","example":"https://open.spotify.com/intl-de/track/4uLU6hMCjMI75M1A2tKUQC?si=x","description":"open.spotify.com link, spotify: URI or spotify.link short link."}},"required":["link"]},"example":{"link":"https://open.spotify.com/intl-de/track/4uLU6hMCjMI75M1A2tKUQC?si=x"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":0}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}