{"openapi":"3.1.0","info":{"title":"ListenBrainz (BYOK) API","version":"0.1.0","description":"ListenBrainz (BYOK) lets an AI assistant read your own ListenBrainz data through the ListenBrainz API with a key you supply (ListenBrainz user token). Read-only: 11 tools (validate_token, get_listens, get_listen_count, get_playing_now, top_artists, top_releases, top_recordings, listening_activity, similar_users, sitewide_top_artists, artist_top_listeners). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-listenbrainz.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-listenbrainz/docs"},"termsOfService":"https://connectorbay.com/byok-listenbrainz/terms"},"servers":[{"url":"https://byok-listenbrainz.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-listenbrainz/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/validate_token":{"post":{"operationId":"validate_token","summary":"Check that the user token is valid and show which ListenBrainz user name it belongs to. Use for \"Which ListenBrainz acco","description":"Check that the user token is valid and show which ListenBrainz user name it belongs to. Use for \"Which ListenBrainz account is my token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"validate_tokenArguments","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_listens":{"post":{"operationId":"get_listens","summary":"List a user's recent listens (tracks played), newest first, with listen time, artist, track and release names. Use max_t","description":"List a user's recent listens (tracks played), newest first, with listen time, artist, track and release names. Use max_ts or min_ts (not both) to page through time. Use for \"What did I listen to recently on ListenBrainz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many listens to return (1 to 100).","title":"Count"},"max_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only listens before this UNIX timestamp (seconds), to page back in time. Do not combine with min_ts.","title":"Max Ts"},"min_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only listens after this UNIX timestamp (seconds). Do not combine with max_ts.","title":"Min Ts"}},"required":["user_name"],"title":"get_listensArguments","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_listen_count":{"post":{"operationId":"get_listen_count","summary":"Get the total number of listens a user has submitted to ListenBrainz. Use for \"How many listens do I have on ListenBrain","description":"Get the total number of listens a user has submitted to ListenBrainz. Use for \"How many listens do I have on ListenBrainz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"}},"required":["user_name"],"title":"get_listen_countArguments","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_playing_now":{"post":{"operationId":"get_playing_now","summary":"Show the track a user is playing right now, if any (the listen has no listened_at time). Use for \"What am I listening to","description":"Show the track a user is playing right now, if any (the listen has no listened_at time). Use for \"What am I listening to right now on ListenBrainz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"}},"required":["user_name"],"title":"get_playing_nowArguments","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/top_artists":{"post":{"operationId":"top_artists","summary":"List a user's most listened artists for a time range, with listen counts. Use for \"Who are my top artists on ListenBrain","description":"List a user's most listened artists for a time range, with listen counts. Use for \"Who are my top artists on ListenBrainz this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"},"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entries to return (1 to 100).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip from the start, for paging.","title":"Offset"}},"required":["user_name"],"title":"top_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/top_releases":{"post":{"operationId":"top_releases","summary":"List a user's most listened releases (albums) for a time range, with artist name and listen counts. Use for \"What are my","description":"List a user's most listened releases (albums) for a time range, with artist name and listen counts. Use for \"What are my top albums on ListenBrainz this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"},"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entries to return (1 to 100).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip from the start, for paging.","title":"Offset"}},"required":["user_name"],"title":"top_releasesArguments","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/top_recordings":{"post":{"operationId":"top_recordings","summary":"List a user's most listened tracks for a time range, with artist, release and listen counts. Use for \"What are my most p","description":"List a user's most listened tracks for a time range, with artist, release and listen counts. Use for \"What are my most played tracks on ListenBrainz this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"},"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entries to return (1 to 100).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip from the start, for paging.","title":"Offset"}},"required":["user_name"],"title":"top_recordingsArguments","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/listening_activity":{"post":{"operationId":"listening_activity","summary":"Show how many listens a user submitted per day, week, month or year within a time range, as a series of time buckets. Us","description":"Show how many listens a user submitted per day, week, month or year within a time range, as a series of time buckets. Use for \"How much did I listen per month on ListenBrainz this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"},"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"}},"required":["user_name"],"title":"listening_activityArguments","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/similar_users":{"post":{"operationId":"similar_users","summary":"List other ListenBrainz users with similar music taste to a user, with a similarity score between 0 and 1. Use for \"Whic","description":"List other ListenBrainz users with similar music taste to a user, with a similarity score between 0 and 1. Use for \"Which ListenBrainz users listen like me\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_name":{"description":"ListenBrainz user name (the MusicBrainz account name), for example 'rob'.","maxLength":80,"title":"User Name","type":"string"}},"required":["user_name"],"title":"similar_usersArguments","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/sitewide_top_artists":{"post":{"operationId":"sitewide_top_artists","summary":"List the most listened artists across all of ListenBrainz for a time range (top 1000 per range). Use for \"Who are the mo","description":"List the most listened artists across all of ListenBrainz for a time range (top 1000 per range). Use for \"Who are the most listened artists on ListenBrainz this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entries to return (1 to 100).","title":"Count"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip from the start, for paging.","title":"Offset"}},"title":"sitewide_top_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/artist_top_listeners":{"post":{"operationId":"artist_top_listeners","summary":"List the users who listened most to an artist (by MusicBrainz artist id) in a time range, with the artist's total listen","description":"List the users who listened most to an artist (by MusicBrainz artist id) in a time range, with the artist's total listen count. Use for \"Who listens most to this artist on ListenBrainz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"artist_mbid":{"description":"MusicBrainz artist id (a UUID), for example '00034ede-a1f1-4219-be39-02f36853373e'.","maxLength":36,"title":"Artist Mbid","type":"string"},"range":{"anyOf":[{"enum":["this_week","this_month","this_year","week","month","quarter","half_yearly","year","all_time"],"type":"string"},{"type":"null"}],"default":"all_time","description":"Time range of the statistics: this_week, this_month, this_year, week, month, quarter, half_yearly, year or all_time.","title":"Range"}},"required":["artist_mbid"],"title":"artist_top_listenersArguments","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}}}}