{"openapi":"3.1.0","info":{"title":"Taddy (BYOK) API","version":"0.1.0","description":"Taddy (BYOK) lets an AI assistant read your own Taddy data through the Taddy API with a key you supply (Taddy API key). Read-only: 9 tools (search_podcasts, search_podcast_episodes, get_podcast, list_podcast_episodes, get_podcast_episode, get_top_charts_by_country, get_top_charts_by_genre, get_popular_podcasts, get_api_requests_remaining). 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-taddy.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-taddy/docs"},"termsOfService":"https://connectorbay.com/byok-taddy/terms"},"servers":[{"url":"https://byok-taddy.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-taddy/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_podcasts":{"post":{"operationId":"search_podcasts","summary":"Search the Taddy directory for podcast shows by keywords. Returns name, author, description, feed URL, language, genres ","description":"Search the Taddy directory for podcast shows by keywords. Returns name, author, description, feed URL, language, genres and episode count. Each call counts as one API request of your monthly plan. Use for \"Find podcasts about the history of India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"Search words, for example 'history of india'.","maxLength":200,"title":"Term","type":"string"},"sort_by":{"anyOf":[{"enum":["EXACTNESS","POPULARITY"],"type":"string"},{"type":"null"}],"default":"EXACTNESS","description":"Order of search results: EXACTNESS (best text match, default) or POPULARITY.","title":"Sort By"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"},"safe_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to leave out explicit content.","title":"Safe Mode"}},"required":["term"],"title":"search_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/search_podcast_episodes":{"post":{"operationId":"search_podcast_episodes","summary":"Search podcast episodes by keywords, optionally only episodes that have a transcript. Returns title, description, durati","description":"Search podcast episodes by keywords, optionally only episodes that have a transcript. Returns title, description, duration, publish time, audio link and the show. Each call counts as one API request of your monthly plan. Use for \"Find podcast episodes that discuss sourdough baking\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"Search words, for example 'sourdough baking'.","maxLength":200,"title":"Term","type":"string"},"sort_by":{"anyOf":[{"enum":["EXACTNESS","POPULARITY"],"type":"string"},{"type":"null"}],"default":"EXACTNESS","description":"Order of search results: EXACTNESS (best text match, default) or POPULARITY.","title":"Sort By"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"},"safe_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to leave out explicit content.","title":"Safe Mode"},"has_transcript":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only episodes that already have a transcript available.","title":"Has Transcript"}},"required":["term"],"title":"search_podcast_episodesArguments","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 one podcast show by name, iTunes ID, RSS feed URL or Taddy uuid (give exactly one), with details and its most recent","description":"Get one podcast show by name, iTunes ID, RSS feed URL or Taddy uuid (give exactly one), with details and its most recent episodes. Use for \"Show me the podcast 'This American Life' and its latest episodes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Show title; when several shows share it, the most popular is returned.","title":"Name"},"itunes_id":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Apple Podcasts numeric ID.","title":"Itunes Id"},"rss_url":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The show's RSS feed URL.","title":"Rss Url"},"uuid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Taddy's own show identifier.","title":"Uuid"},"recent_episodes":{"anyOf":[{"maximum":25,"minimum":0,"type":"integer"},{"type":"null"}],"default":5,"description":"How many of the newest episodes to include (0 to 25).","title":"Recent Episodes"}},"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/list_podcast_episodes":{"post":{"operationId":"list_podcast_episodes","summary":"List episodes of one podcast show (by Taddy uuid), newest first by default, optionally filtered by words in the episode ","description":"List episodes of one podcast show (by Taddy uuid), newest first by default, optionally filtered by words in the episode title or description. Use for \"List the oldest episodes of the show with Taddy uuid abc-1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Taddy's identifier of the show (from search_podcasts or get_podcast).","maxLength":64,"title":"Uuid","type":"string"},"order":{"anyOf":[{"enum":["LATEST","OLDEST","SEARCH"],"type":"string"},{"type":"null"}],"default":"LATEST","description":"LATEST (newest first), OLDEST, or SEARCH (best match when search_term is given).","title":"Order"},"search_term":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only episodes matching these words.","title":"Search Term"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many episodes to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"}},"required":["uuid"],"title":"list_podcast_episodesArguments","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_episode":{"post":{"operationId":"get_podcast_episode","summary":"Get one podcast episode by Taddy uuid, or by RSS guid or title (optionally narrowed to one show with series_uuid). Use f","description":"Get one podcast episode by Taddy uuid, or by RSS guid or title (optionally narrowed to one show with series_uuid). Use for \"Get details of the podcast episode with Taddy uuid ep-1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Taddy's identifier of the episode.","title":"Uuid"},"guid":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Episode guid from the RSS feed (not unique across shows; combine with series_uuid).","title":"Guid"},"name":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Episode title (not unique; combine with series_uuid).","title":"Name"},"series_uuid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Taddy uuid of the show to restrict a guid or name lookup to.","title":"Series Uuid"}},"title":"get_podcast_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/get_top_charts_by_country":{"post":{"operationId":"get_top_charts_by_country","summary":"Get the podcast top chart (Apple Podcasts based) for a country, either shows or episodes. Use for \"What are the top podc","description":"Get the podcast top chart (Apple Podcasts based) for a country, either shows or episodes. Use for \"What are the top podcasts in India right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"Country as a Taddy country name in capitals with underscores, for example UNITED_STATES_OF_AMERICA, INDIA or UNITED_KINGDOM.","maxLength":60,"title":"Country","type":"string"},"chart_type":{"anyOf":[{"enum":["PODCASTSERIES","PODCASTEPISODE"],"type":"string"},{"type":"null"}],"default":"PODCASTSERIES","description":"PODCASTSERIES for shows or PODCASTEPISODE for episodes.","title":"Chart Type"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"}},"required":["country"],"title":"get_top_charts_by_countryArguments","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_top_charts_by_genre":{"post":{"operationId":"get_top_charts_by_genre","summary":"Get the podcast top chart (Apple Podcasts based) for one genre, optionally limited to one country; shows or episodes. Us","description":"Get the podcast top chart (Apple Podcasts based) for one genre, optionally limited to one country; shows or episodes. Use for \"What are the top technology podcasts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre":{"description":"Genre as a Taddy genre such as PODCASTSERIES_TECHNOLOGY, PODCASTSERIES_COMEDY, PODCASTSERIES_NEWS, PODCASTSERIES_SCIENCE or PODCASTSERIES_BUSINESS.","maxLength":80,"title":"Genre","type":"string"},"chart_type":{"anyOf":[{"enum":["PODCASTSERIES","PODCASTEPISODE"],"type":"string"},{"type":"null"}],"default":"PODCASTSERIES","description":"PODCASTSERIES for shows or PODCASTEPISODE for episodes.","title":"Chart Type"},"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Optional country as a Taddy country name in capitals with underscores, for example UNITED_STATES_OF_AMERICA, INDIA or UNITED_KINGDOM (needed for episode charts).","title":"Country"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"}},"required":["genre"],"title":"get_top_charts_by_genreArguments","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_popular_podcasts":{"post":{"operationId":"get_popular_podcasts","summary":"Rank podcast shows by Taddy's popularity score, optionally for one genre and one language. Use for \"Which Spanish-langua","description":"Rank podcast shows by Taddy's popularity score, optionally for one genre and one language. Use for \"Which Spanish-language news podcasts are most popular\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Optional genre as a Taddy genre such as PODCASTSERIES_TECHNOLOGY, PODCASTSERIES_COMEDY, PODCASTSERIES_NEWS, PODCASTSERIES_SCIENCE or PODCASTSERIES_BUSINESS.","title":"Genre"},"language":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional language name in capitals, for example ENGLISH, SPANISH, HINDI or FRENCH.","title":"Language"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 25).","title":"Limit"},"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (Taddy allows up to page 20).","title":"Page"}},"title":"get_popular_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_api_requests_remaining":{"post":{"operationId":"get_api_requests_remaining","summary":"Show how many Taddy API requests are left for the month on the key's plan (the free plan has 500). Use for \"How many Tad","description":"Show how many Taddy API requests are left for the month on the key's plan (the free plan has 500). Use for \"How many Taddy API requests do I have left this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_requests_remainingArguments","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}}}}