{"openapi":"3.0.3","info":{"title":"Spotify Data API","description":"Authenticated proxy to the Spotify Data API.\n\nAll `/spotify-data/*` endpoints require a valid API key sent in the\n`x-rapidapi-key` header. `/docs`, `/openapi.json`, `/openapi.yaml`,\nand `/help` are public.\n\n### Concert endpoints\n\n- `/partner/concert-locations` → search cities/venues, returns `geoHash` + `geonameId`.\n- `/partner/concert-feed` → list concerts in an area (paginated). Optional deep-search via `details=true`.\n- `/partner/concert` → full concert details by ID/URI/URL (lineup, tickets, venue).\n- `/partner/artist-concerts` → upcoming concerts for an artist.\n- `/partner/search-concert-artists` → resolve artist by name → upcoming concerts in one call.\n\nConcert endpoints accept `details=true` (parallel deep-fetch, capped by `detailsLimit`,\nmax 50) and `parsed=true` (flat normalized response shape).\n","version":"1.1.0","contact":{"name":"API Support"}},"servers":[{"url":"/spotify-data","description":"Proxy server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Health"},{"name":"Search"},{"name":"Albums"},{"name":"Artists"},{"name":"Tracks"},{"name":"Playlists"},{"name":"Users"},{"name":"Charts"},{"name":"Downloads"},{"name":"Partner"},{"name":"Concerts"},{"name":"Browse"},{"name":"Audiobooks"},{"name":"Shows"},{"name":"Episodes"},{"name":"Markets"},{"name":"Lookups"},{"name":"Batch"},{"name":"Analysis"},{"name":"Snapshots"},{"name":"Webhooks"},{"name":"Cache"},{"name":"Tracking"},{"name":"AI"},{"name":"Credentials"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-rapidapi-key"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"}}},"SuccessEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"description":"Endpoint payload (raw upstream or parsed shape)."},"metadata":{"type":"object","additionalProperties":true}}}},"parameters":{"OffsetParam":{"name":"offset","in":"query","schema":{"type":"integer","default":0}},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","default":10}},"ContrastParam":{"name":"contrast","in":"query","description":"Comma-separated list of streaming providers to contrast against.\nAppends a `_contrast` field to the response with cross-platform matching data.\nAvailable providers: `ytmusic`, `applemusic`, `amazonmusic`, `tencentmusic`, `pandora`, `gaana`.\n","schema":{"type":"string"},"examples":{"single":{"summary":"Single provider","value":"ytmusic"},"multiple":{"summary":"Multiple providers","value":"ytmusic,applemusic"}}},"DetailsParam":{"name":"details","in":"query","description":"Enrich each concert with full concert details in parallel.","schema":{"type":"boolean","default":false}},"DetailsLimitParam":{"name":"detailsLimit","in":"query","description":"Max concerts to enrich per request (max 50).","schema":{"type":"integer","default":20,"maximum":50}},"ParsedParam":{"name":"parsed","in":"query","description":"Return a flat, normalized concert shape instead of raw GraphQL.","schema":{"type":"boolean","default":false}}}},"paths":{"/ping":{"get":{"summary":"Ping","tags":["Health"],"responses":{"200":{"description":"OK"}}}},"/health":{"get":{"summary":"Cluster health","tags":["Health"],"responses":{"200":{"description":"Healthy"},"500":{"description":"Unhealthy"}}}},"/health/instance":{"get":{"summary":"Instance health","tags":["Health"],"responses":{"200":{"description":"Healthy / degraded"},"503":{"description":"Unhealthy"}}}},"/health/cluster":{"get":{"summary":"Cluster overview","tags":["Health"],"responses":{"200":{"description":"Cluster health report"}}}},"/health/cluster/strict":{"get":{"summary":"Strict cluster health","description":"Includes periodic search test results.","tags":["Health"],"responses":{"200":{"description":"All healthy"},"503":{"description":"Unhealthy"}}}},"/health/proxies":{"get":{"summary":"Proxy health","tags":["Health"],"responses":{"200":{"description":"Proxy pool status"}}}},"/health/proxies/clear":{"post":{"summary":"Clear proxy stats","tags":["Health"],"responses":{"200":{"description":"Cleared"}}}},"/health/clear-errors":{"post":{"summary":"Clear error counters","tags":["Health"],"responses":{"200":{"description":"Cleared"}}}},"/credentials/status":{"get":{"summary":"Credentials status","tags":["Credentials"],"responses":{"200":{"description":"Credentials status"}}}},"/cookies/redis":{"get":{"summary":"Redis cookies status","tags":["Credentials"],"responses":{"200":{"description":"Cookies status"}}}},"/search":{"get":{"summary":"Search Spotify","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","default":"multi"},"description":"Search type: multi, tracks, albums, artists, playlists, etc."},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"numberOfTopResults","in":"query","schema":{"type":"integer","default":5}},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Search results"},"400":{"description":"Invalid search type"}}}},"/search_top_results":{"get":{"summary":"Search — top results only","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"numberOfTopResults","in":"query","schema":{"type":"integer","default":5}},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Top search results"}}}},"/search_lyrics":{"get":{"summary":"Search & get lyrics","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","lrc","srt","raw"],"default":"json"}}],"responses":{"200":{"description":"Lyrics data"}}}},"/search_suggestions":{"get":{"summary":"Search suggestions","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":30}},{"name":"numberOfTopResults","in":"query","schema":{"type":"integer","default":30}},{"name":"includeAuthors","in":"query","schema":{"type":"boolean","default":true}},{"name":"debug","in":"query","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","schema":{"type":"integer","default":30000}},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Search suggestions"},"400":{"description":"Missing required query parameter q"}}}},"/search_multi_market":{"get":{"summary":"Multi-market search","description":"Run the same search across multiple markets in parallel.","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","default":"multi"}},{"name":"markets","in":"query","description":"Comma-separated ISO market codes (e.g. `US,GB,DE`).","schema":{"type":"string"}},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Per-market results"}}}},"/albums":{"get":{"summary":"Get albums","tags":["Albums"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated album IDs"},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Album data"}}}},"/album_tracks":{"get":{"summary":"Album tracks","tags":["Albums"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Album track listing"}}}},"/album_metadata":{"get":{"summary":"Album metadata","tags":["Albums"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Album metadata"}}}},"/album_metadata_batch":{"get":{"summary":"Album metadata (batch)","tags":["Batch"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated album IDs (max 25)."}],"responses":{"200":{"description":"Batch album metadata"}}}},"/artists":{"get":{"summary":"Get artists","tags":["Artists"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated artist IDs"},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Artist data"}}}},"/artist_overview":{"get":{"summary":"Artist overview","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Artist overview"}}}},"/artist_overview_batch":{"get":{"summary":"Artist overview (batch)","tags":["Batch"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated artist IDs (max 25)."}],"responses":{"200":{"description":"Batch artist overview"}}}},"/artist_discography_overview":{"get":{"summary":"Artist discography overview","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Discography overview"}}}},"/artist_albums":{"get":{"summary":"Artist albums","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":300}}],"responses":{"200":{"description":"Artist album list"}}}},"/artist_singles":{"get":{"summary":"Artist singles","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Artist singles"}}}},"/artist_appears_on":{"get":{"summary":"Artist appears on","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Albums the artist appears on"}}}},"/artist_discovered_on":{"get":{"summary":"Artist discovered on","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Playlists where the artist was discovered"}}}},"/artist_featuring":{"get":{"summary":"Artist featuring","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Playlists featuring the artist"}}}},"/artist_related":{"get":{"summary":"Related artists","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Related artists"}}}},"/artist_top_tracks":{"get":{"summary":"Artist top tracks","tags":["Artists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Top tracks"}}}},"/artist_compare":{"get":{"summary":"Compare artists","tags":["Analysis"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated artist IDs (2–10)."}],"responses":{"200":{"description":"Comparison report"}}}},"/tracks":{"get":{"summary":"Get tracks","tags":["Tracks"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated track IDs"},{"$ref":"#/components/parameters/ContrastParam"}],"responses":{"200":{"description":"Track data"}}}},"/track_credits":{"get":{"summary":"Track credits","tags":["Tracks"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track credits"}}}},"/track_credits_batch":{"get":{"summary":"Track credits (batch)","tags":["Batch"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated track IDs (max 25)."}],"responses":{"200":{"description":"Batch credits"}}}},"/track_lyrics":{"get":{"summary":"Track lyrics","tags":["Tracks"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","lrc","srt","raw"],"default":"json"}},{"name":"vocalRemoval","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Lyrics"}}}},"/track_lyrics_batch":{"get":{"summary":"Track lyrics (batch)","tags":["Batch"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","lrc","srt","raw"],"default":"json"}}],"responses":{"200":{"description":"Batch lyrics"}}}},"/track_popularity_batch":{"get":{"summary":"Track popularity (batch)","tags":["Batch"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Popularity values"}}}},"/audio_features":{"get":{"summary":"Audio features","description":"Tempo, energy, danceability, valence, etc.","tags":["Analysis"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audio features"}}}},"/isrc_lookup":{"get":{"summary":"Lookup track by ISRC","tags":["Lookups"],"parameters":[{"name":"isrc","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track data"}}}},"/upc_lookup":{"get":{"summary":"Lookup album by UPC","tags":["Lookups"],"parameters":[{"name":"upc","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Album data"}}}},"/recommendations":{"get":{"summary":"Recommendations","tags":["Tracks"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"seed_tracks","in":"query","schema":{"type":"string"}},{"name":"seed_artists","in":"query","schema":{"type":"string"}},{"name":"seed_genres","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Recommended tracks"}}}},"/playlist":{"get":{"summary":"Get playlist","tags":["Playlists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Playlist data"}}}},"/playlist_tracks":{"get":{"summary":"Playlist tracks","tags":["Playlists"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Playlist track listing"}}}},"/playlist_analysis":{"get":{"summary":"Playlist analysis","tags":["Analysis"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate playlist stats"}}}},"/playlist_snapshot":{"get":{"summary":"List playlist snapshots","tags":["Snapshots"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Snapshot history"}}},"post":{"summary":"Create playlist snapshot","tags":["Snapshots"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Playlist ID"},"webhook":{"type":"string","description":"Optional webhook URL for change notifications."}}}}}},"responses":{"200":{"description":"Snapshot created"}}}},"/seed_to_playlist":{"get":{"summary":"Seed to playlist","tags":["Playlists"],"parameters":[{"name":"uri","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Generated playlist from seed"}}}},"/user_profile":{"get":{"summary":"User profile","tags":["Users"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"playlistLimit","in":"query","schema":{"type":"integer","default":10}},{"name":"artistLimit","in":"query","schema":{"type":"integer","default":100}},{"name":"episodeLimit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"User profile"}}}},"/user_followers":{"get":{"summary":"User followers","tags":["Users"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"User followers"}}}},"/top_20_by_monthly_listeners":{"get":{"summary":"Top 20 by monthly listeners","tags":["Charts"],"responses":{"200":{"description":"Top 20 artists by monthly listeners"}}}},"/top_200_tracks":{"get":{"summary":"Top 200 tracks","tags":["Charts"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","default":"daily"}},{"name":"country","in":"query","schema":{"type":"string","default":"global"}},{"name":"date","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Top 200 tracks chart"}}}},"/top_artists":{"get":{"summary":"Top artists chart","tags":["Charts"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","default":"daily"}},{"name":"country","in":"query","schema":{"type":"string","default":"global"}}],"responses":{"200":{"description":"Top artists"}}}},"/top_albums":{"get":{"summary":"Top albums chart","tags":["Charts"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","default":"daily"}},{"name":"country","in":"query","schema":{"type":"string","default":"global"}}],"responses":{"200":{"description":"Top albums"}}}},"/viral_tracks":{"get":{"summary":"Viral tracks chart","tags":["Charts"],"parameters":[{"name":"country","in":"query","schema":{"type":"string","default":"global"}}],"responses":{"200":{"description":"Viral tracks"}}}},"/top_20_by_followers":{"get":{"summary":"Top 20 by followers","tags":["Charts"],"responses":{"200":{"description":"Top 20 artists by followers"}}}},"/download_track":{"get":{"summary":"Download track","tags":["Downloads"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track download"}}}},"/download_track_sc":{"get":{"summary":"Download track (SoundCloud)","tags":["Downloads"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track download via SoundCloud"}}}},"/browse/categories":{"get":{"summary":"Browse categories","tags":["Browse"],"parameters":[{"name":"country","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"Categories"}}}},"/browse/categories/{id}":{"get":{"summary":"Category by ID","tags":["Browse"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Category"}}}},"/browse/featured-playlists":{"get":{"summary":"Featured playlists","tags":["Browse"],"parameters":[{"name":"country","in":"query","schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"Featured playlists"}}}},"/browse/new-releases":{"get":{"summary":"New releases","tags":["Browse"],"parameters":[{"name":"country","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"New releases"}}}},"/browse/recommendations":{"get":{"summary":"Browse recommendations","tags":["Browse"],"parameters":[{"name":"seed_tracks","in":"query","schema":{"type":"string"}},{"name":"seed_artists","in":"query","schema":{"type":"string"}},{"name":"seed_genres","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Recommendations"}}}},"/audiobooks":{"get":{"summary":"Get audiobooks","tags":["Audiobooks"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Audiobook data"}}}},"/audiobooks/{id}":{"get":{"summary":"Audiobook by ID","tags":["Audiobooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Audiobook"}}}},"/audiobooks/{id}/chapters":{"get":{"summary":"Audiobook chapters","tags":["Audiobooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Chapters"}}}},"/shows":{"get":{"summary":"Get shows","tags":["Shows"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Show data"}}}},"/shows/{id}":{"get":{"summary":"Show by ID","tags":["Shows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Show"}}}},"/shows/{id}/episodes":{"get":{"summary":"Show episodes","tags":["Shows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Episodes"}}}},"/episodes":{"get":{"summary":"Get episodes","tags":["Episodes"],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Episode data"}}}},"/episodes/{id}":{"get":{"summary":"Episode by ID","tags":["Episodes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Episode"}}}},"/markets":{"get":{"summary":"Available markets","tags":["Markets"],"responses":{"200":{"description":"Market list"}}}},"/partner/playlist":{"get":{"summary":"Partner playlist data","tags":["Partner"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"22-character Spotify playlist ID"},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"Playlist data from pathfinder v2"}}}},"/partner/track":{"get":{"summary":"Partner track data","tags":["Partner"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Track data from pathfinder v2"}}}},"/partner/track/count":{"get":{"summary":"Track play count","tags":["Partner"],"parameters":[{"name":"spotify_track_id","in":"query","schema":{"type":"string"}},{"name":"isrc","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Track play count"}}}},"/partner/album":{"get":{"summary":"Partner album data","tags":["Partner"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"intl-es"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Album data from pathfinder v2"}}}},"/partner/artist-overview":{"get":{"summary":"Partner artist overview","description":"Comprehensive artist data — profile, visuals, top tracks, stats, related artists, discography.","tags":["Partner"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","schema":{"type":"string","default":"en"}},{"name":"includePrerelease","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Artist overview"}}}},"/partner/artist-discography":{"get":{"summary":"Partner artist discography","description":"Full artist discography — albums, singles, EPs, compilations with pagination.","tags":["Partner"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Discography"}}}},"/partner/concert-locations":{"get":{"summary":"Search concert locations","description":"Search Spotify for cities and venues. Returns `geoHash` and `geonameId` values that feed `/partner/concert-feed`.","tags":["Concerts"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"City, venue, or place name."}],"responses":{"200":{"description":"Matching locations"}}}},"/partner/concert-feed":{"get":{"summary":"Concert feed by location","description":"List upcoming concerts in a geographic area (geoHash + geonameId, obtained from\n`/partner/concert-locations`). Returns paginated concert sections grouped by date.\nUse `details=true` to deep-search every concert in parallel and attach venue,\nlineup, and ticket providers.\n","tags":["Concerts"],"parameters":[{"name":"geoHash","in":"query","required":true,"schema":{"type":"string"},"description":"Spotify geohash (from `/partner/concert-locations`)."},{"name":"geonameId","in":"query","required":true,"schema":{"type":"string"},"description":"Geoname ID (from `/partner/concert-locations`)."},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Start of date range (YYYY-MM-DD)."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"End of date range (YYYY-MM-DD)."},{"name":"radiusInKm","in":"query","schema":{"type":"integer","default":100}},{"name":"conceptUris","in":"query","schema":{"type":"string"},"description":"Comma-separated Spotify concept URIs (e.g. `spotify:concept:rock,spotify:concept:pop`)."},{"name":"paginationKey","in":"query","schema":{"type":"string"},"description":"Pass back the `paginationKey` from a prior response."},{"$ref":"#/components/parameters/DetailsParam"},{"$ref":"#/components/parameters/DetailsLimitParam"},{"$ref":"#/components/parameters/ParsedParam"}],"responses":{"200":{"description":"Concert feed"},"400":{"description":"Invalid date format"}}}},"/partner/concert":{"get":{"summary":"Concert details","description":"Fetch full concert details by Spotify concert ID, URI, or open.spotify.com URL.\nReturns venue, lineup, ticket providers (DICE, Ticketmaster, etc.), accepted dates,\nfestival flag, related concerts, and partner sale links. Pass `parsed=true` for a\nflat, ready-to-consume shape.\n","tags":["Concerts"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Concert ID, `spotify:concert:URI`, or `open.spotify.com/concert/<id>` URL."},{"$ref":"#/components/parameters/ParsedParam"},{"name":"authenticated","in":"query","schema":{"type":"boolean","default":true},"description":"Set `false` to query as anonymous user (omits `me.profile` block)."}],"responses":{"200":{"description":"Concert payload"},"400":{"description":"Concert ID is required / invalid format"}}}},"/partner/artist-concerts":{"get":{"summary":"Artist upcoming concerts","description":"Fetch every upcoming concert/tour date for a Spotify artist.\nAccepts artist ID, `spotify:artist:URI`, or `open.spotify.com/artist/<id>` URL.\nWith `parsed=true` returns a flat `{ artist, concerts[], nearby }` shape;\nwith `details=true` each concert is enriched with venue, lineup, and ticket providers.\n","tags":["Concerts"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Artist ID, URI, or open.spotify.com URL."},{"name":"geoHash","in":"query","schema":{"type":"string","default":"0"},"description":"Geohash for nearby-concert prioritization. `0` = global."},{"name":"includeNearby","in":"query","schema":{"type":"boolean","default":true}},{"$ref":"#/components/parameters/DetailsParam"},{"$ref":"#/components/parameters/DetailsLimitParam"},{"$ref":"#/components/parameters/ParsedParam"}],"responses":{"200":{"description":"Artist concerts"},"400":{"description":"Artist ID is required / invalid format"}}}},"/partner/search-concert-artists":{"get":{"summary":"Search concerts by artist name","description":"Resolve an artist by free-text name and return their upcoming concerts in one call —\nuseful when you don't know the Spotify artist ID. `limit > 1` returns concerts for\nthe top N matched artists (handy for ambiguous names).\n","tags":["Concerts"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Artist name to search."},{"name":"geoHash","in":"query","schema":{"type":"string","default":"0"}},{"name":"includeNearby","in":"query","schema":{"type":"boolean","default":true}},{"name":"limit","in":"query","schema":{"type":"integer","default":1,"minimum":1,"maximum":10},"description":"Number of artist matches to return concerts for."},{"$ref":"#/components/parameters/DetailsParam"},{"$ref":"#/components/parameters/DetailsLimitParam"},{"$ref":"#/components/parameters/ParsedParam"}],"responses":{"200":{"description":"Matched artists with concerts"},"400":{"description":"Query is required"}}}},"/webhooks":{"get":{"summary":"List webhooks","tags":["Webhooks"],"responses":{"200":{"description":"Webhook list"}}}},"/webhooks/register":{"post":{"summary":"Register webhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Registered"}}}},"/webhooks/stats":{"get":{"summary":"Webhook stats","tags":["Webhooks"],"responses":{"200":{"description":"Aggregate webhook stats"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/webhooks/{id}/test":{"post":{"summary":"Trigger test webhook delivery","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivered"}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"Webhook delivery log","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deliveries"}}}},"/cache/stats":{"get":{"summary":"Cache stats","tags":["Cache"],"responses":{"200":{"description":"Stats"}}}},"/cache/invalidate":{"post":{"summary":"Invalidate cache","tags":["Cache"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"pattern":{"type":"string"}}}}}},"responses":{"200":{"description":"Invalidated"}}}},"/tracking/track":{"get":{"summary":"Track item","tags":["Tracking"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["track","album","artist","playlist"]}},{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tracking enabled"}}},"post":{"summary":"Track item","tags":["Tracking"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}}}}}},"responses":{"200":{"description":"Tracking enabled"}}}},"/tracking/untrack":{"get":{"summary":"Untrack item","tags":["Tracking"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Untracked"}}},"delete":{"summary":"Untrack item","tags":["Tracking"],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Untracked"}}}},"/tracking/items":{"get":{"summary":"List tracked items","tags":["Tracking"],"parameters":[{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Tracked items"}}}},"/tracking/items/{spotifyType}/{spotifyId}":{"get":{"summary":"Tracked item detail","tags":["Tracking"],"parameters":[{"name":"spotifyType","in":"path","required":true,"schema":{"type":"string"}},{"name":"spotifyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item detail"}}}},"/tracking/logs":{"get":{"summary":"Tracking change log","tags":["Tracking"],"parameters":[{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Logs"}}}},"/tracking/stats":{"get":{"summary":"Tracking stats","tags":["Tracking"],"responses":{"200":{"description":"Stats"}}}},"/tracking/health":{"get":{"summary":"Tracking health","tags":["Tracking"],"responses":{"200":{"description":"Health"}}}},"/ai/health":{"get":{"summary":"AI module health","tags":["AI"],"responses":{"200":{"description":"Health"}}}},"/ai/types":{"get":{"summary":"Supported AI analysis types","tags":["AI"],"responses":{"200":{"description":"Supported types"}}}},"/ai/analyze":{"get":{"summary":"Generic AI analysis","tags":["AI"],"responses":{"200":{"description":"Analysis"}}},"post":{"summary":"Generic AI analysis","tags":["AI"],"responses":{"200":{"description":"Analysis"}}}},"/ai/chart-trends":{"get":{"summary":"Chart trends analysis","tags":["AI"],"responses":{"200":{"description":"Trends"}}},"post":{"summary":"Chart trends analysis","tags":["AI"],"responses":{"200":{"description":"Trends"}}}},"/ai/artist-summary":{"get":{"summary":"Artist summary","tags":["AI"],"responses":{"200":{"description":"Summary"}}},"post":{"summary":"Artist summary","tags":["AI"],"responses":{"200":{"description":"Summary"}}}},"/ai/album-review":{"get":{"summary":"Album review","tags":["AI"],"responses":{"200":{"description":"Review"}}},"post":{"summary":"Album review","tags":["AI"],"responses":{"200":{"description":"Review"}}}},"/ai/track-deep-dive":{"get":{"summary":"Track deep dive","tags":["AI"],"responses":{"200":{"description":"Deep dive"}}},"post":{"summary":"Track deep dive","tags":["AI"],"responses":{"200":{"description":"Deep dive"}}}},"/ai/playlist-curator":{"get":{"summary":"Playlist curator","tags":["AI"],"responses":{"200":{"description":"Curated playlist"}}},"post":{"summary":"Playlist curator","tags":["AI"],"responses":{"200":{"description":"Curated playlist"}}}},"/ai/market-comparison":{"get":{"summary":"Market comparison","tags":["AI"],"responses":{"200":{"description":"Comparison"}}},"post":{"summary":"Market comparison","tags":["AI"],"responses":{"200":{"description":"Comparison"}}}},"/ai/genre-landscape":{"get":{"summary":"Genre landscape","tags":["AI"],"responses":{"200":{"description":"Landscape"}}},"post":{"summary":"Genre landscape","tags":["AI"],"responses":{"200":{"description":"Landscape"}}}},"/ai/mood-profile":{"get":{"summary":"Mood profile","tags":["AI"],"responses":{"200":{"description":"Profile"}}},"post":{"summary":"Mood profile","tags":["AI"],"responses":{"200":{"description":"Profile"}}}},"/ai/viral-potential":{"get":{"summary":"Viral potential","tags":["AI"],"responses":{"200":{"description":"Score"}}},"post":{"summary":"Viral potential","tags":["AI"],"responses":{"200":{"description":"Score"}}}},"/ai/custom":{"get":{"summary":"Custom AI prompt","tags":["AI"],"responses":{"200":{"description":"Result"}}},"post":{"summary":"Custom AI prompt","tags":["AI"],"responses":{"200":{"description":"Result"}}}}}}