podcasts

{'type': 'object', 'properties': {'sort': {'enum': ['relevance', 'published_desc', 'published_asc'], 'type': 'string', 'default': 'published_desc', 'description': 'Sort order for results. `relevance` ranks full-text searches first and falls back to newest-first when no query is provided.'}, 'limit': {'type': 'integer', 'default': 5, 'maximum': 50, 'minimum': 1, 'description': 'Maximum number of episodes to return. Must be between 1 and 50.'}, 'cursor': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Zero-based episode offset for pagination. Use the `next_cursor` returned by a prior search/listing call to fetch the next page of results.'}, 'published_after': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive lower publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}, 'published_before': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive upper publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['episodes', 'count', 'total_count'], 'properties': {'count': {'type': 'integer', 'description': 'Number of episodes returned on this page.'}, 'episodes': {'type': 'array', 'items': {'type': 'object', 'required': ['show_guid', 'show_title', 'episode_guid', 'episode_title', 'published_date', 'rss_feed_url', 'description'], 'properties': {'show_guid': {'type': 'string', 'description': 'Podcast show GUID.'}, 'show_title': {'type': 'string', 'description': 'Podcast show title.'}, 'description': {'type': 'string', 'description': 'Episode description, truncated for search result display.'}, 'episode_guid': {'type': 'string', 'description': 'Podcast episode GUID.'}, 'rss_feed_url': {'type': 'string', 'description': 'RSS feed URL for the podcast show.'}, 'episode_title': {'type': 'string', 'description': 'Podcast episode title.'}, 'published_date': {'type': 'string', 'description': 'Episode publication timestamp in ISO 8601 format.'}, 'duration_seconds': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Episode duration in seconds when available from the source feed.'}}}, 'description': 'Matching transcript-ready episodes.'}, 'next_cursor': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Cursor to pass to the next search call to retrieve the next page of results, or null if there are no more pages.'}, 'total_count': {'type': 'integer', 'description': 'Total number of matching transcript-ready episodes across all pages.'}, 'total_count_is_approximate': {'type': 'boolean', 'default': False, 'description': 'When true, `total_count` is a lower bound — more matches may exist than were counted. False for exact lexical/date counts; can be true only for semantic results (e.g. the topic-search fallback).'}}}

{'type': 'object', 'required': ['show_guid', 'episode_guid'], 'properties': {'cursor': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Zero-based character offset into the transcript. Use the `next_cursor` returned by a prior get_transcript call to fetch the next chunk.'}, 'max_chars': {'type': 'integer', 'default': 12000, 'maximum': 20000, 'minimum': 100, 'description': 'Target maximum number of transcript characters to return. Chunks prefer natural boundaries and may be slightly shorter. Must be between 100 and 20000.'}, 'show_guid': {'type': 'string', 'minLength': 1, 'description': 'Podcast show GUID returned by `search_episodes` or `get_latest_episodes`.'}, 'episode_guid': {'type': 'string', 'minLength': 1, 'description': 'Episode GUID returned by `search_episodes` or `get_latest_episodes`.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['show_guid', 'show_title', 'episode_guid', 'episode_title', 'published_date', 'rss_feed_url', 'text', 'total_chars', 'char_start', 'char_end', 'has_more'], 'properties': {'text': {'type': 'string', 'description': 'Transcript chunk text.'}, 'char_end': {'type': 'integer', 'description': 'Exclusive zero-based end offset of this chunk in the complete transcript.'}, 'has_more': {'type': 'boolean', 'description': 'Whether another get_transcript call is needed to continue reading.'}, 'show_guid': {'type': 'string', 'description': 'Podcast show GUID requested by the client.'}, 'char_start': {'type': 'integer', 'description': 'Inclusive zero-based start offset of this chunk in the complete transcript.'}, 'show_title': {'type': 'string', 'description': 'Podcast show title.'}, 'next_cursor': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Cursor to pass to the next get_transcript call, or null at the end.'}, 'total_chars': {'type': 'integer', 'description': 'Total character count of the complete transcript text.'}, 'episode_guid': {'type': 'string', 'description': 'Podcast episode GUID requested by the client.'}, 'rss_feed_url': {'type': 'string', 'description': 'RSS feed URL for the podcast show.'}, 'episode_title': {'type': 'string', 'description': 'Podcast episode title.'}, 'published_date': {'type': 'string', 'description': 'Episode publication timestamp in ISO 8601 format.'}, 'duration_seconds': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Episode duration in seconds when available from the source feed.'}}}

{'type': 'object', 'required': ['feedback'], 'properties': {'feedback': {'type': 'string', 'minLength': 1, 'description': 'Feedback for the server team. Include the problem, missing capability, or suggested improvement without sensitive user data.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['status', 'feedback_id', 'message'], 'properties': {'status': {'enum': ['saved', 'logged'], 'type': 'string', 'description': 'Feedback persistence status.'}, 'message': {'type': 'string', 'description': 'Human-readable result summary.'}, 'feedback_id': {'type': 'string', 'description': 'Stable feedback identifier.'}}}

{'type': 'object', 'properties': {'sort': {'enum': ['relevance', 'published_desc', 'published_asc'], 'type': 'string', 'default': 'relevance', 'description': 'Sort order for results. `relevance` ranks full-text searches first and falls back to newest-first when no query is provided.'}, 'limit': {'type': 'integer', 'default': 5, 'maximum': 50, 'minimum': 1, 'description': 'Maximum number of episodes to return. Must be between 1 and 50.'}, 'query': {'type': 'string', 'default': '', 'description': 'Optional search keywords matched against indexed episode content. Use people, topics, companies, or phrases.'}, 'cursor': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Zero-based episode offset for pagination. Use the `next_cursor` returned by a prior search/listing call to fetch the next page of results.'}, 'podcast_name': {'type': 'string', 'default': '', 'description': 'Optional podcast title or internal label to narrow results to a specific show.'}, 'published_after': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive lower publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}, 'published_before': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive upper publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}, 'published_within_hours': {'anyOf': [{'type': 'integer', 'maximum': 168, 'minimum': 1}, {'type': 'null'}], 'default': None, 'description': 'Filter episodes published in the past X hours. Maximum 168 hours (1 week).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['episodes', 'count', 'total_count'], 'properties': {'count': {'type': 'integer', 'description': 'Number of episodes returned on this page.'}, 'episodes': {'type': 'array', 'items': {'type': 'object', 'required': ['show_guid', 'show_title', 'episode_guid', 'episode_title', 'published_date', 'rss_feed_url', 'description'], 'properties': {'show_guid': {'type': 'string', 'description': 'Podcast show GUID.'}, 'show_title': {'type': 'string', 'description': 'Podcast show title.'}, 'description': {'type': 'string', 'description': 'Episode description, truncated for search result display.'}, 'episode_guid': {'type': 'string', 'description': 'Podcast episode GUID.'}, 'rss_feed_url': {'type': 'string', 'description': 'RSS feed URL for the podcast show.'}, 'episode_title': {'type': 'string', 'description': 'Podcast episode title.'}, 'published_date': {'type': 'string', 'description': 'Episode publication timestamp in ISO 8601 format.'}, 'duration_seconds': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Episode duration in seconds when available from the source feed.'}}}, 'description': 'Matching transcript-ready episodes.'}, 'next_cursor': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Cursor to pass to the next search call to retrieve the next page of results, or null if there are no more pages.'}, 'total_count': {'type': 'integer', 'description': 'Total number of matching transcript-ready episodes across all pages.'}, 'total_count_is_approximate': {'type': 'boolean', 'default': False, 'description': 'When true, `total_count` is a lower bound — more matches may exist than were counted. False for exact lexical/date counts; can be true only for semantic results (e.g. the topic-search fallback).'}}}

{'type': 'object', 'required': ['topic'], 'properties': {'limit': {'type': 'integer', 'default': 5, 'maximum': 50, 'minimum': 1, 'description': 'Maximum number of episodes to return. Must be between 1 and 50.'}, 'topic': {'type': 'string', 'maxLength': 300, 'minLength': 1, 'description': "Semantic topic to find episodes about. Free-form phrasing welcome — the server embeds this string and finds episodes whose extracted topic phrases are closest in meaning. Good examples: 'AI safety', 'EU AI Act regulation', 'GPU supply constraints', 'Theo Epstein on roster construction'. Distinct from `search_episodes`, which performs lexical keyword matching."}, 'cursor': {'type': 'integer', 'default': 0, 'minimum': 0, 'description': 'Zero-based episode offset for pagination. Use the `next_cursor` returned by a prior search/listing call to fetch the next page of results.'}, 'show_guid': {'type': 'string', 'default': '', 'description': 'Optional canonical show GUID (as returned by `search_episodes` or `get_latest_episodes` in the `show_guid` field) to restrict topic search to a single podcast. Leave empty to search across all shows.'}, 'published_after': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive lower publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}, 'published_before': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'default': None, 'description': 'Inclusive upper publication-date bound. Accepts YYYY-MM-DD or ISO 8601 datetime.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['episodes', 'count', 'query', 'total_count'], 'properties': {'count': {'type': 'integer', 'description': 'Number of episodes returned on this page.'}, 'query': {'type': 'string', 'description': 'The topic query that was embedded and searched.'}, 'episodes': {'type': 'array', 'items': {'type': 'object', 'required': ['show_guid', 'show_title', 'episode_guid', 'episode_title', 'published_date', 'rss_feed_url', 'description', 'matched_topics', 'best_similarity'], 'properties': {'show_guid': {'type': 'string', 'description': 'Podcast show GUID.'}, 'show_title': {'type': 'string', 'description': 'Podcast show title.'}, 'description': {'type': 'string', 'description': 'Episode description, truncated for search result display.'}, 'episode_guid': {'type': 'string', 'description': 'Podcast episode GUID.'}, 'rss_feed_url': {'type': 'string', 'description': 'RSS feed URL for the podcast show.'}, 'episode_title': {'type': 'string', 'description': 'Podcast episode title.'}, 'matched_topics': {'type': 'array', 'items': {'type': 'object', 'required': ['phrase', 'similarity'], 'properties': {'phrase': {'type': 'string', 'description': 'The extracted topic phrase that matched. Useful for explaining to the user why this episode came back for their query.'}, 'similarity': {'type': 'number', 'description': 'Cosine similarity between the query and this topic phrase, in [0.0, 1.0]. Higher is more semantically similar.'}}}, 'description': 'Topic phrases from this episode that matched the query, ordered by similarity (best first). Use these to summarize *why* the episode is relevant before fetching the full transcript.'}, 'published_date': {'type': 'string', 'description': 'Episode publication timestamp in ISO 8601 format.'}, 'best_similarity': {'type': 'number', 'description': 'Similarity of the strongest topic match — the value the episodes were sorted by.'}, 'duration_seconds': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Episode duration in seconds when available from the source feed.'}}}, 'description': 'Episodes ranked by best topic-phrase similarity to the query.'}, 'next_cursor': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': 'Cursor to pass to the next search call to retrieve the next page of results, or null if there are no more pages.'}, 'total_count': {'type': 'integer', 'description': 'Number of matching episodes, counted over the nearest-match candidate window rather than the whole catalog. When `total_count_is_approximate` is true, treat this as a lower bound — broad queries may have more matches than reported.'}, 'total_count_is_approximate': {'type': 'boolean', 'default': False, 'description': 'True when the candidate window was exhausted, so `total_count` undercounts the true number of matches. When false, `total_count` is exact. Refine the query for tighter results if this is true and you need a complete set.'}}}