{"openapi":"3.1.0","info":{"title":"Viberate (BYOK) API","version":"0.1.0","description":"Viberate (BYOK) lets an AI assistant read your own Viberate data through the Viberate API with a key you supply (Viberate API token). Read-only: 12 tools (get_rate_limit_status, search_artists, get_artist_details, get_artist_ranks, get_artist_stats, get_artist_chart, search_tracks, get_track_all_time_stats, get_track_chart, list_spotify_trending_tracks, search_festivals, get_festival_lineup). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-viberate.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-viberate/docs"},"termsOfService":"https://connectorbay.com/byok-viberate/terms"},"servers":[{"url":"https://byok-viberate.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-viberate/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_rate_limit_status":{"post":{"operationId":"get_rate_limit_status","summary":"Show the key's per-minute call limit, how many calls remain and whether it is over the limit. Use for \"How many Viberate","description":"Show the key's per-minute call limit, how many calls remain and whether it is over the limit. Use for \"How many Viberate API calls do I have left this minute\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_rate_limit_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_artists":{"post":{"operationId":"search_artists","summary":"Search artists by name; returns UUID, Viberate rank, country, city, genre and subgenres. Use for \"Find the Viberate UUID","description":"Search artists by name; returns UUID, Viberate rank, country, city, genre and subgenres. Use for \"Find the Viberate UUID of the artist UMEK\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Artist name to search for (approximate matches are returned).","maxLength":200,"title":"Q","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"required":["q"],"title":"search_artistsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_artist_details":{"post":{"operationId":"get_artist_details","summary":"Get one artist's profile: name, rank, verification, country, city, genre, subgenres and Spotify genres. Use for \"Give me","description":"Get one artist's profile: name, rank, verification, country, city, genre, subgenres and Spotify genres. Use for \"Give me the Viberate profile of artist c803da56-c6bd-4c61-addb-f1063544a1a2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_uuid":{"description":"Viberate artist UUID from search_artists, for example 'c803da56-c6bd-4c61-addb-f1063544a1a2'.","maxLength":200,"title":"Artist Uuid","type":"string"}},"required":["artist_uuid"],"title":"get_artist_detailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_artist_ranks":{"post":{"operationId":"get_artist_ranks","summary":"Get an artist's current and previous-month Viberate ranks overall, in country, genre and subgenre, per channel (Viberate","description":"Get an artist's current and previous-month Viberate ranks overall, in country, genre and subgenre, per channel (Viberate, social, Spotify, YouTube). Use for \"How did artist c803da56-c6bd-4c61-addb-f1063544a1a2 move in the Viberate ranks this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_uuid":{"description":"Viberate artist UUID from search_artists, for example 'c803da56-c6bd-4c61-addb-f1063544a1a2'.","maxLength":200,"title":"Artist Uuid","type":"string"}},"required":["artist_uuid"],"title":"get_artist_ranksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_artist_stats":{"post":{"operationId":"get_artist_stats","summary":"Get an artist's history of one metric (such as spotify_followers, instagram_followers, youtube_views, tiktok_followers, ","description":"Get an artist's history of one metric (such as spotify_followers, instagram_followers, youtube_views, tiktok_followers, soundcloud_plays, airplay_spins, deezer_followers, shazam_shazams) as totals, changes or both, by day, week or month. Use for \"How have artist c803da56-c6bd-4c61-addb-f1063544a1a2's Spotify followers grown weekly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_uuid":{"description":"Viberate artist UUID from search_artists, for example 'c803da56-c6bd-4c61-addb-f1063544a1a2'.","maxLength":200,"title":"Artist Uuid","type":"string"},"metric":{"description":"Metric name, channel_metric style, for example spotify_followers, spotify_listeners, spotify_streams, instagram_followers, tiktok_views, youtube_subscribers, soundcloud_plays, airplay_spins, deezer_followers, facebook_followers, shazam_shazams.","maxLength":60,"title":"Metric","type":"string"},"graph_mode":{"anyOf":[{"enum":["","total","diff"],"type":"string"},{"type":"null"}],"default":null,"description":"total for totals only, diff for changes only, empty for both.","title":"Graph Mode"},"period":{"anyOf":[{"enum":["daily","weekly","monthly"],"type":"string"},{"type":"null"}],"default":"daily","description":"Aggregation period.","title":"Period"},"date_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First date, YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last date, YYYY-MM-DD.","title":"Date To"}},"required":["artist_uuid","metric"],"title":"get_artist_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_artist_chart":{"post":{"operationId":"get_artist_chart","summary":"Get the Viberate artist chart ranked by a chosen metric and timeframe, filterable by genre, subgenre, country and verifi","description":"Get the Viberate artist chart ranked by a chosen metric and timeframe, filterable by genre, subgenre, country and verification. Use for \"Which verified US artists lead the Viberate Spotify listeners chart over the last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"viberate-rank","description":"Metric to rank by, for example viberate-rank, spotify-streams, spotify-listeners, spotify-followers, youtube-views, instagram-followers, tiktok-followers, shazam-shazams, deezer-followers.","title":"Sort"},"timeframe":{"anyOf":[{"enum":["1w","1m","3m","12m","total"],"type":"string"},{"type":"null"}],"default":"total","description":"Period the ranking metric covers.","title":"Timeframe"},"genres":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Viberate genre ids to keep, for example '2,5'.","title":"Genres"},"subgenres":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Viberate subgenre ids to keep, for example '6,10'.","title":"Subgenres"},"countries":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ISO country codes to keep, for example 'US,DE'.","title":"Countries"},"status":{"anyOf":[{"enum":["active","inactive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only active or inactive artists.","title":"Status"},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for verified artists only, false for unverified only.","title":"Verified"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"title":"get_artist_chartArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_tracks":{"post":{"operationId":"search_tracks","summary":"Search tracks by title; returns UUID, ISRC, release date, genre and artists. Use for \"Find the Viberate UUID of the trac","description":"Search tracks by title; returns UUID, ISRC, release date, genre and artists. Use for \"Find the Viberate UUID of the track Love Yourself\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Track title to search for (approximate matches are returned).","maxLength":200,"title":"Q","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"required":["q"],"title":"search_tracksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_track_all_time_stats":{"post":{"operationId":"get_track_all_time_stats","summary":"Get a track's all-time totals across channels: Spotify streams, YouTube views, TikTok views, SoundCloud plays, Shazams a","description":"Get a track's all-time totals across channels: Spotify streams, YouTube views, TikTok views, SoundCloud plays, Shazams and airplay spins. Use for \"How many streams and views does track aa0abd00-3af4-4c6d-8f45-989059a6a92c have in total\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"track_uuid":{"description":"Viberate track UUID from search_tracks.","maxLength":200,"title":"Track Uuid","type":"string"}},"required":["track_uuid"],"title":"get_track_all_time_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_track_chart":{"post":{"operationId":"get_track_chart","summary":"Get the Viberate track chart ranked by a chosen metric and timeframe, filterable by artist, genre and release date. Use ","description":"Get the Viberate track chart ranked by a chosen metric and timeframe, filterable by artist, genre and release date. Use for \"What were the top tracks by Spotify streams over the last three months\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sort":{"anyOf":[{"enum":["viberate-performance_score","spotify-streams","youtube-views","airplay-spins","soundcloud-plays","shazam-shazams"],"type":"string"},{"type":"null"}],"default":"viberate-performance_score","description":"Metric to rank by.","title":"Sort"},"timeframe":{"anyOf":[{"enum":["1w","1m","3m","12m","total"],"type":"string"},{"type":"null"}],"default":"total","description":"Period the ranking metric covers.","title":"Timeframe"},"artists":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated artist UUIDs to keep.","title":"Artists"},"genres":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Viberate genre ids to keep, for example '2,5'.","title":"Genres"},"subgenres":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated Viberate subgenre ids to keep, for example '6,10'.","title":"Subgenres"},"released_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only tracks released on or after this date, YYYY-MM-DD.","title":"Released From"},"released_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only tracks released on or before this date, YYYY-MM-DD.","title":"Released To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"title":"get_track_chartArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_spotify_trending_tracks":{"post":{"operationId":"list_spotify_trending_tracks","summary":"List the tracks with the most Spotify streams for a country today, with one-day streams, change and rank. Use for \"What ","description":"List the tracks with the most Spotify streams for a country today, with one-day streams, change and rank. Use for \"What are the trending tracks on Spotify in Germany\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":"US","description":"ISO country code, for example DE.","title":"Country"},"sort":{"anyOf":[{"enum":["streams_1d","streams_1d_pct","release_date"],"type":"string"},{"type":"null"}],"default":"streams_1d","description":"Order by streams_1d, streams_1d_pct or release_date.","title":"Sort"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc or desc.","title":"Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"title":"list_spotify_trending_tracksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_festivals":{"post":{"operationId":"search_festivals","summary":"Search festivals by name; returns UUID, rank, country, city, genres and dates. Use for \"Find the Viberate UUID of Coache","description":"Search festivals by name; returns UUID, rank, country, city, genres and dates. Use for \"Find the Viberate UUID of Coachella\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Festival name to search for (approximate matches are returned).","maxLength":200,"title":"Q","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (default 20).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging. The plan caps the highest offset.","title":"Offset"}},"required":["q"],"title":"search_festivalsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_festival_lineup":{"post":{"operationId":"get_festival_lineup","summary":"Get a festival's lineup of artists with their rank, country and genre, optionally for one edition. Use for \"Who is in th","description":"Get a festival's lineup of artists with their rank, country and genre, optionally for one edition. Use for \"Who is in the lineup of festival 58da9a7c-ff11-4dee-909d-f10156096be0\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"festival_uuid":{"description":"Viberate festival UUID from search_festivals.","maxLength":200,"title":"Festival Uuid","type":"string"},"edition_uuid":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"UUID of one festival edition; leave out for the default edition.","title":"Edition Uuid"}},"required":["festival_uuid"],"title":"get_festival_lineupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}