{"openapi":"3.1.0","info":{"title":"Listen Notes (BYOK) API","version":"0.1.0","description":"Listen Notes (BYOK) lets an AI assistant read your own Listen Notes data through the Listen Notes API with a key you supply (Listen API key). Read-only: 11 tools (search, best_podcasts, get_podcast, get_episode, podcast_recommendations, episode_recommendations, list_genres, list_regions, list_languages, trending_searches, random_episode). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-listennotes.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-listennotes/docs"},"termsOfService":"https://connectorbay.com/byok-listennotes/terms"},"servers":[{"url":"https://byok-listennotes.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-listennotes/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/search":{"post":{"operationId":"search","summary":"Search Listen Notes for podcast episodes, podcasts or curated lists by text. Returns titles, publishers, dates, lengths ","description":"Search Listen Notes for podcast episodes, podcasts or curated lists by text. Returns titles, publishers, dates, lengths and links. The free plan shows at most 30 results per query (offset below 30). Use for \"Search podcasts for episodes about the history of the printing press\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search text; wrap in double quotes for an exact phrase, for example '\"game of thrones\"'.","maxLength":200,"title":"Q","type":"string"},"type":{"anyOf":[{"enum":["episode","podcast","curated"],"type":"string"},{"type":"null"}],"default":"episode","description":"What to search: episode, podcast or curated (list of podcasts).","title":"Type"},"sort_by_date":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to sort newest first, 0 to sort by relevance.","title":"Sort By Date"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging: use next_offset from the previous answer (the free plan allows offsets below 30).","title":"Offset"},"page_size":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 10).","title":"Page Size"},"genre_ids":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated genre ids to restrict to (see list_genres), for example '68,82'.","title":"Genre Ids"},"language":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this language, for example 'English' (see list_languages).","title":"Language"},"region":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country code, for example 'us' or 'gb' (see list_regions).","title":"Region"},"len_min":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum audio length in minutes (episode and podcast searches).","title":"Len Min"},"len_max":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum audio length in minutes (episode and podcast searches).","title":"Len Max"},"safe_mode":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to exclude explicit-language podcasts and episodes, 0 to include them.","title":"Safe Mode"}},"required":["q"],"title":"searchArguments","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/best_podcasts":{"post":{"operationId":"best_podcasts","summary":"List curated best podcasts overall or in one genre, optionally per country and language, sorted by recency or Listen Sco","description":"List curated best podcasts overall or in one genre, optionally per country and language, sorted by recency or Listen Score; 20 per page. Use for \"What are the best true crime podcasts in the US\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Genre id from list_genres; leave empty for the overall best podcasts.","title":"Genre Id"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"region":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":"us","description":"Country code the ranking applies to, for example 'us'.","title":"Region"},"language":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this language, for example 'English'.","title":"Language"},"sort":{"anyOf":[{"enum":["recent_added_first","oldest_added_first","recent_published_first","oldest_published_first","listen_score"],"type":"string"},{"type":"null"}],"default":"recent_added_first","description":"Order: recent_added_first, oldest_added_first, recent_published_first, oldest_published_first or listen_score.","title":"Sort"},"safe_mode":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to exclude explicit-language podcasts and episodes, 0 to include them.","title":"Safe Mode"}},"title":"best_podcastsArguments","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_podcast":{"post":{"operationId":"get_podcast","summary":"Get a podcast's details (publisher, description, language, episode count, Listen Score) and up to 10 of its episodes; pa","description":"Get a podcast's details (publisher, description, language, episode count, Listen Score) and up to 10 of its episodes; page with next_episode_pub_date. Use for \"Show the latest episodes of a podcast\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"podcast_id":{"description":"Listen Notes podcast id (the id of a search or best_podcasts result), for example '4d3fe717742d4963a85562e9f84d8c79'.","maxLength":64,"title":"Podcast Id","type":"string"},"sort":{"anyOf":[{"enum":["recent_first","oldest_first"],"type":"string"},{"type":"null"}],"default":"recent_first","description":"Episode order: recent_first or oldest_first.","title":"Sort"},"next_episode_pub_date":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"For the next page of episodes: the next_episode_pub_date value of the previous answer.","title":"Next Episode Pub Date"}},"required":["podcast_id"],"title":"get_podcastArguments","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_episode":{"post":{"operationId":"get_episode","summary":"Get one episode's details by id: title, description, publication time, audio length, links and the parent podcast. Use f","description":"Get one episode's details by id: title, description, publication time, audio length, links and the parent podcast. Use for \"Tell me about this podcast episode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"episode_id":{"description":"Listen Notes episode id (the id of an episode search result or get_podcast episode).","maxLength":64,"title":"Episode Id","type":"string"}},"required":["episode_id"],"title":"get_episodeArguments","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/podcast_recommendations":{"post":{"operationId":"podcast_recommendations","summary":"List up to 8 podcasts similar to a given podcast. Use for \"What podcasts are similar to this one\".","description":"List up to 8 podcasts similar to a given podcast. Use for \"What podcasts are similar to this one\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"podcast_id":{"description":"Listen Notes podcast id (the id of a search or best_podcasts result), for example '4d3fe717742d4963a85562e9f84d8c79'.","maxLength":64,"title":"Podcast Id","type":"string"},"safe_mode":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to exclude explicit-language podcasts and episodes, 0 to include them.","title":"Safe Mode"}},"required":["podcast_id"],"title":"podcast_recommendationsArguments","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/episode_recommendations":{"post":{"operationId":"episode_recommendations","summary":"List up to 8 episodes similar to a given episode. Use for \"What episodes are similar to this one\".","description":"List up to 8 episodes similar to a given episode. Use for \"What episodes are similar to this one\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"episode_id":{"description":"Listen Notes episode id (the id of an episode search result or get_podcast episode).","maxLength":64,"title":"Episode Id","type":"string"},"safe_mode":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to exclude explicit-language podcasts and episodes, 0 to include them.","title":"Safe Mode"}},"required":["episode_id"],"title":"episode_recommendationsArguments","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_genres":{"post":{"operationId":"list_genres","summary":"List podcast genres with id, name and parent id; the ids are the genre_id of best_podcasts and genre_ids of search. Use ","description":"List podcast genres with id, name and parent id; the ids are the genre_id of best_podcasts and genre_ids of search. Use for \"What podcast genres does Listen Notes have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"top_level_only":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"1 to list only top-level genres, 0 for all genres.","title":"Top Level Only"}},"title":"list_genresArguments","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_regions":{"post":{"operationId":"list_regions","summary":"List supported country codes and names for the region parameter of best_podcasts and search. Use for \"Which regions does","description":"List supported country codes and names for the region parameter of best_podcasts and search. Use for \"Which regions does Listen Notes support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_regionsArguments","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_languages":{"post":{"operationId":"list_languages","summary":"List supported podcast languages for the language parameter of search and best_podcasts. Use for \"Which podcast language","description":"List supported podcast languages for the language parameter of search and best_podcasts. Use for \"Which podcast languages does Listen Notes support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_languagesArguments","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/trending_searches":{"post":{"operationId":"trending_searches","summary":"List up to 10 recent trending search terms on Listen Notes. Use for \"What are people searching for on Listen Notes\".","description":"List up to 10 recent trending search terms on Listen Notes. Use for \"What are people searching for on Listen Notes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"trending_searchesArguments","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/random_episode":{"post":{"operationId":"random_episode","summary":"Get one random podcast episode (recently published ones are more likely) with its podcast. Use for \"Give me a random pod","description":"Get one random podcast episode (recently published ones are more likely) with its podcast. Use for \"Give me a random podcast episode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"random_episodeArguments","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}}}}