# Pod Engine API Reference > Optimized for LLM consumption. Drop the URL or contents into your AI assistant for accurate API guidance. > Source: https://www.podengine.ai/api-docs/llms-full.txt > Auto-generated from the source-of-truth endpoint registry — kept in sync with the live API. ## Overview Pod Engine is a podcast intelligence platform with access to 4M+ podcasts. The API enables: - Searching podcasts and episodes by title, description, topic, or transcript content - Retrieving detailed podcast/episode metadata including contact information - Accessing full episode transcripts (when available) - Tracking chart rankings across countries and categories - Managing projects and organizing podcast research - AI-powered guest profile generation, relevancy scoring, and outreach drafting ## Quick Start 1. Sign up at https://www.podengine.ai/get-started 2. Get your API key from your dashboard 3. Add to requests: `Authorization: Bearer YOUR_API_KEY` **Base URL:** `http://localhost:4000` **Interactive docs:** https://www.podengine.ai/api-docs **OpenAPI 3.1 spec:** https://www.podengine.ai/api-docs/openapi.json **Compact reference:** https://www.podengine.ai/api-docs/llms.txt **Support:** support@podengine.ai ## Authentication Endpoints labeled `(PUBLIC)` need no authentication. All other endpoints require a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` --- ## Endpoints ### Agent #### POST /api/v1/agent/alternative-spellings **Alternative Spellings** Generate phonetically plausible alternate spellings for a name or business. Useful for searching against auto-generated podcast transcripts where names are frequently misspelled. ```bash curl -X POST "http://localhost:4000/api/v1/agent/alternative-spellings" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "value": "Joe Tannorella" }' ``` **Request body schema:** ```json { "type": "object", "properties": { "value": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "value" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "spellings": { "type": "array", "items": { "type": "string" } } }, "required": [ "spellings" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/agent/project/relevancy **Project Podcast Relevancy** Analyze the relevancy of a podcast to a project using AI ```bash curl -X POST "http://localhost:4000/api/v1/agent/project/relevancy" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "projectId": "example-project-id", "podcastId": "example-podcast-id", "forceRegenerate": false }' ``` **Request body schema:** ```json { "type": "object", "properties": { "projectId": { "type": "string" }, "podcastId": { "type": "string" }, "searchOptions": { "anyOf": [ { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "description": "Terms to search for in podcast title and description", "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } } }, "additionalProperties": false }, { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description", "episode-title", "episode-description", "transcript" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } }, "includeTranscriptSnippet": { "type": "boolean" }, "transcriptSnippetLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "transcriptHighlightLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "includeEpisodeIds": { "type": "array", "items": { "type": "string" } }, "publishedSince": {}, "hasTranscript": { "type": "boolean" }, "episodeUpdatedSince": {}, "episodeCreatedSince": {} }, "additionalProperties": false } ] }, "forceRegenerate": { "type": "boolean" } }, "required": [ "projectId", "podcastId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "answer": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "justification": { "type": "string" }, "strengths": {}, "concerns": {} }, "required": [ "rating", "justification", "strengths", "concerns" ], "additionalProperties": false } }, "required": [ "answer" ], "additionalProperties": false } }, "required": [ "result" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Alerts #### GET /api/v1/alerts/history **Alert Match History** Get the paginated history of alert matches for the team, optionally scoped to a single alert config. ```bash curl -X GET "http://localhost:4000/api/v1/alerts/history" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "alertConfigId": { "type": "string" }, "page": { "type": "number" }, "sinceDate": {} }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "alertConfigId": { "type": "string" }, "page": { "type": "number" }, "sinceDate": {} }, "additionalProperties": false }, "totalAlertMatches": { "type": "number" }, "alertMatches": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "advertisementLLMHistoryId": { "nullable": true, "type": "number" }, "contextLLMHistoryId": { "nullable": true, "type": "number" }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "processedDate": {}, "id": { "type": "string" }, "alertConfig": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "teamId": { "type": "string" }, "createdByUserId": { "type": "string" } }, "required": [ "id", "name", "value", "teamId", "createdByUserId" ], "additionalProperties": false }, "emailHistoryId": { "nullable": true, "type": "number" }, "episodeSlug": { "type": "string" }, "episodeTitle": { "type": "string" }, "filteredOut": { "type": "boolean" }, "imageUrl": { "nullable": true, "type": "string" }, "podcastSlug": { "type": "string" }, "podcastTitle": { "type": "string" }, "text": { "type": "string" } }, "required": [ "advertisementLLMHistoryId", "contextLLMHistoryId", "episodeDate", "episodeId", "filteredOutReason", "podcastId", "processedDate", "id", "alertConfig", "emailHistoryId", "episodeSlug", "episodeTitle", "filteredOut", "imageUrl", "podcastSlug", "podcastTitle", "text" ], "additionalProperties": false }, { "oneOf": [ { "type": "object", "properties": { "advertisementLLMHistoryId": { "nullable": true, "type": "number" }, "contextLLMHistoryId": { "nullable": true, "type": "number" }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "processedDate": {}, "type": { "type": "string", "enum": [ "EPISODE" ] } }, "required": [ "advertisementLLMHistoryId", "contextLLMHistoryId", "episodeDate", "episodeId", "filteredOutReason", "podcastId", "processedDate", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "advertisementLLMHistoryId": { "nullable": true, "type": "number" }, "contextLLMHistoryId": { "nullable": true, "type": "number" }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "processedDate": {}, "type": { "type": "string", "enum": [ "TRANSCRIPT" ] }, "endSecond": { "type": "number" }, "startSecond": { "type": "number" }, "transcriptEmbeddingId": { "type": "string" }, "transcriptId": { "type": "string" }, "transcriptionDate": {} }, "required": [ "advertisementLLMHistoryId", "contextLLMHistoryId", "episodeDate", "episodeId", "filteredOutReason", "podcastId", "processedDate", "type", "endSecond", "startSecond", "transcriptEmbeddingId", "transcriptId", "transcriptionDate" ], "additionalProperties": false } ] } ] } } }, "required": [ "options", "totalAlertMatches", "alertMatches" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/alerts/alert-config **Create Alert Config** Create a new alert configuration to monitor podcasts for mentions of a person, company, or custom keyword. ```bash curl -X POST "http://localhost:4000/api/v1/alerts/alert-config" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "alertName": "Example Alert", "alertType": "person", "value": "Jason Calacanis" }' ``` **Request body schema:** ```json { "type": "object", "properties": { "alertName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "person", "company", "custom-keyword" ] }, "value": { "type": "string" }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "enabled": { "type": "boolean" }, "generateAlternativeSpellings": { "type": "boolean" }, "additionalAlertSettings": { "type": "object", "properties": { "otherEmails": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "alertName", "alertType", "value" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "createdAlertConfig": { "type": "object", "properties": { "id": { "type": "string" }, "createdByUserId": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "updatedAt": {}, "alertName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "person", "company", "custom-keyword" ] }, "enabled": { "type": "boolean" }, "alertSettings": { "allOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ] }, "value": { "type": "string" }, "trackGuestAppearances": { "type": "boolean" }, "trackHostAppearances": { "type": "boolean" }, "trackMentions": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-keyword" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "genresToSkip": { "type": "array", "items": { "type": "string" } }, "genresToInclude": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } }, "otherEmails": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "contextAwareQuestion": { "type": "string" }, "contextAwareDetails": { "type": "object", "properties": { "what": { "type": "string" }, "relevantClues": { "type": "string" }, "commonFalsePositives": { "type": "string" } }, "additionalProperties": false }, "filterAdvertisements": { "type": "boolean" } }, "additionalProperties": false } ] }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "lastRunDate": { "nullable": true } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "createdAlertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### DELETE /api/v1/alerts/alert-config/:alertConfigId **Delete Alert Config** Soft-delete an alert configuration. ```bash curl -X DELETE "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "alertConfigId": { "type": "string" } }, "required": [ "alertConfigId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "deletedAlertConfigId": { "type": "string" } }, "required": [ "deletedAlertConfigId" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/alerts/alert-config/:alertConfigId **Get Alert Config** Get a single alert configuration by ID. ```bash curl -X GET "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "alertConfigId": { "type": "string" } }, "required": [ "alertConfigId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "alertConfig": { "type": "object", "properties": { "id": { "type": "string" }, "createdByUserId": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "updatedAt": {}, "alertName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "person", "company", "custom-keyword" ] }, "enabled": { "type": "boolean" }, "alertSettings": { "allOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ] }, "value": { "type": "string" }, "trackGuestAppearances": { "type": "boolean" }, "trackHostAppearances": { "type": "boolean" }, "trackMentions": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-keyword" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "genresToSkip": { "type": "array", "items": { "type": "string" } }, "genresToInclude": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } }, "otherEmails": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "contextAwareQuestion": { "type": "string" }, "contextAwareDetails": { "type": "object", "properties": { "what": { "type": "string" }, "relevantClues": { "type": "string" }, "commonFalsePositives": { "type": "string" } }, "additionalProperties": false }, "filterAdvertisements": { "type": "boolean" } }, "additionalProperties": false } ] }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "lastRunDate": { "nullable": true } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "alertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/alerts/alert-configs **List Alert Configs** Get all of the team's alert configurations. ```bash curl -X GET "http://localhost:4000/api/v1/alerts/alert-configs" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "enabled": { "type": "boolean" }, "alertConfigId": { "type": "string" }, "sortBy": { "type": "string", "enum": [ "lastRunDate", "alertName" ] }, "sortDirection": { "type": "string", "enum": [ "asc", "desc" ] } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "alertConfigId": { "type": "string" }, "sortBy": { "type": "string", "enum": [ "lastRunDate", "alertName" ] }, "sortDirection": { "type": "string", "enum": [ "asc", "desc" ] } }, "additionalProperties": false }, "alertConfigs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdByUserId": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "updatedAt": {}, "alertName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "person", "company", "custom-keyword" ] }, "enabled": { "type": "boolean" }, "alertSettings": { "allOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ] }, "value": { "type": "string" }, "trackGuestAppearances": { "type": "boolean" }, "trackHostAppearances": { "type": "boolean" }, "trackMentions": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-keyword" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "genresToSkip": { "type": "array", "items": { "type": "string" } }, "genresToInclude": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } }, "otherEmails": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "contextAwareQuestion": { "type": "string" }, "contextAwareDetails": { "type": "object", "properties": { "what": { "type": "string" }, "relevantClues": { "type": "string" }, "commonFalsePositives": { "type": "string" } }, "additionalProperties": false }, "filterAdvertisements": { "type": "boolean" } }, "additionalProperties": false } ] }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "lastRunDate": { "nullable": true } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } } }, "required": [ "options", "alertConfigs" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PATCH /api/v1/alerts/alert-config/:alertConfigId **Update Alert Config** Update an existing alert configuration (name, settings, email frequency, or enabled state). ```bash curl -X PATCH "http://localhost:4000/api/v1/alerts/alert-config/:alertConfigId" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "alertConfigId": { "type": "string" } }, "required": [ "alertConfigId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "updates": { "type": "object", "properties": { "alertName": { "type": "string" }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "alertSettings": { "allOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ] }, "value": { "type": "string" }, "trackGuestAppearances": { "type": "boolean" }, "trackHostAppearances": { "type": "boolean" }, "trackMentions": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-keyword" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "genresToSkip": { "type": "array", "items": { "type": "string" } }, "genresToInclude": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } }, "otherEmails": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "contextAwareQuestion": { "type": "string" }, "contextAwareDetails": { "type": "object", "properties": { "what": { "type": "string" }, "relevantClues": { "type": "string" }, "commonFalsePositives": { "type": "string" } }, "additionalProperties": false }, "filterAdvertisements": { "type": "boolean" } }, "additionalProperties": false } ] }, "enabled": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "updates" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "updatedAlertConfig": { "type": "object", "properties": { "id": { "type": "string" }, "createdByUserId": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "updatedAt": {}, "alertName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "person", "company", "custom-keyword" ] }, "enabled": { "type": "boolean" }, "alertSettings": { "allOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ] }, "value": { "type": "string" }, "trackGuestAppearances": { "type": "boolean" }, "trackHostAppearances": { "type": "boolean" }, "trackMentions": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-keyword" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "genresToSkip": { "type": "array", "items": { "type": "string" } }, "genresToInclude": { "type": "array", "items": { "type": "string" } }, "otherSpellings": { "type": "array", "items": { "type": "string" } }, "otherEmails": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "contextAwareQuestion": { "type": "string" }, "contextAwareDetails": { "type": "object", "properties": { "what": { "type": "string" }, "relevantClues": { "type": "string" }, "commonFalsePositives": { "type": "string" } }, "additionalProperties": false }, "filterAdvertisements": { "type": "boolean" } }, "additionalProperties": false } ] }, "emailSettings": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] } }, "required": [ "frequency" ], "additionalProperties": false }, "lastRunDate": { "nullable": true } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "updatedAlertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Autocomplete #### GET /api/v1/autocomplete/podcasts (PUBLIC) **Podcasts** Get autocomplete suggestions for podcasts ```bash curl -X GET "http://localhost:4000/api/v1/autocomplete/podcasts?query=this" \ -H "Content-Type: application/json" ``` **Query schema:** ```json { "type": "object", "properties": { "query": { "type": "string", "description": "The fuzzy search query to match against the podcast title" } }, "required": [ "query" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } }, "words": { "type": "array", "items": { "type": "string" } } }, "required": [ "podcasts", "words" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Charts #### GET /api/v1/charts/:chartType/categories (PUBLIC) **Chart Categories** Get the categories for a chart ```bash curl -X GET "http://localhost:4000/api/v1/charts/apple/categories" \ -H "Content-Type: application/json" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } }, "required": [ "chartType" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "categories" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/charts/:chartType/countries (PUBLIC) **Chart Countries** Get the available countries for a chart type ```bash curl -X GET "http://localhost:4000/api/v1/charts/apple/countries" \ -H "Content-Type: application/json" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } }, "required": [ "chartType" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "countries" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/charts **Historical Chart** Get a historical chart ```bash curl -X GET "http://localhost:4000/api/v1/charts?category=top+podcasts&chartType=apple&country=us&date=2026-06-09" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 }, "date": { "description": "The date of the chart in YYYY-MM-DD format. If null will return the latest chart", "nullable": true, "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "additionalProperties": false, "description": "Get a specific podcast chart" } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 }, "date": { "description": "The date of the chart in YYYY-MM-DD format. If null will return the latest chart", "nullable": true, "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "additionalProperties": false, "description": "Get a specific podcast chart" }, "chart": { "nullable": true, "type": "object", "properties": { "chart": { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "chartDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the chart in YYYY-MM-DD format" } }, "required": [ "chartType", "category", "country", "chartDate" ], "additionalProperties": false }, "positions": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "podcastOnChart": { "type": "object", "properties": { "podcastOnChartId": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "podcastOnChartId", "title", "imageUrl" ], "additionalProperties": false }, "podenginePodcast": { "nullable": true, "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } }, "required": [ "position", "podcastOnChart", "podenginePodcast" ], "additionalProperties": false } } }, "required": [ "chart", "positions" ], "additionalProperties": false } }, "required": [ "options", "chart" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/charts/latest (PUBLIC) **Latest Chart** Get the latest chart ```bash curl -X GET "http://localhost:4000/api/v1/charts/latest?category=top+podcasts&chartType=apple&country=us" \ -H "Content-Type: application/json" ``` **Query schema:** ```json { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "chart": { "nullable": true, "type": "object", "properties": { "chart": { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "chartDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the chart in YYYY-MM-DD format" } }, "required": [ "chartType", "category", "country", "chartDate" ], "additionalProperties": false }, "positions": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "podcastOnChart": { "type": "object", "properties": { "podcastOnChartId": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "podcastOnChartId", "title", "imageUrl" ], "additionalProperties": false }, "podenginePodcast": { "nullable": true, "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } }, "required": [ "position", "podcastOnChart", "podenginePodcast" ], "additionalProperties": false } } }, "required": [ "chart", "positions" ], "additionalProperties": false } }, "required": [ "options", "chart" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Episodes #### GET /api/v1/episodes/:episodeId/details **Episode Details** Get the details of an episode ```bash curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/details" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "episodeId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "episode": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "nullable": true }, "description": { "nullable": true, "type": "string" }, "durationSeconds": { "nullable": true, "type": "number" }, "enclosureUrl": { "type": "string" }, "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "episodeGuestsAndHosts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "nullable": true, "type": "string" }, "episodeSponsors": { "nullable": true, "type": "array", "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "nullable": true, "type": "string" }, "episodeThumbnailRssUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "podcastSlug": { "type": "string" }, "publishedAt": {}, "title": { "type": "string" }, "transcriptId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transcriptionRequestedAt": { "nullable": true }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "nullable": true, "type": "object", "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "nullable": true, "type": "number" }, "youtubeDataFetchedAt": { "nullable": true } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "deepAnalysisRequestedAt", "description", "durationSeconds", "enclosureUrl", "episodeId", "episodeGuestsAndHosts", "episodeSlug", "episodeShortDescription", "episodeSponsors", "hasTranscript", "imageUrl", "episodeThumbnailRssUrl", "podcastId", "podcastSlug", "publishedAt", "title", "transcriptId", "transcriptionRequestedAt", "youtubeEpisodeDetails", "applePodcastsUrl" ], "additionalProperties": false } }, "required": [ "episode" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/episodes/:episodeId/download/transcript **Episode Transcript Download** File download the transcript of an episode ```bash curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/download/transcript?format=txt" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "episodeId" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "format": { "default": "txt", "type": "string", "enum": [ "txt", "vtt", "sentence-vtt" ] } }, "required": [ "format" ], "additionalProperties": false } ``` **Response schema:** ```json { "description": "Binary file download — response body is the raw file (no JSON schema).", "contentType": "application/octet-stream" } ``` --- #### GET /api/v1/episodes/:episodeId/transcript-text **Episode Transcript Text** Get the transcript text of an episode ```bash curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcript-text" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "episodeId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "episodeTranscriptText": { "type": "object", "properties": { "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transcriptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "text": { "nullable": true, "type": "string" } }, "required": [ "podcastId", "episodeId", "transcriptId", "text" ], "additionalProperties": false } }, "required": [ "episodeTranscriptText" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/episodes/:episodeId/transcript-timestamps **Episode Transcript Timestamps** Get the transcript of an episode with word-level timestamps in a structured JSON format ```bash curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcript-timestamps" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "episodeId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "episodeId": { "type": "string" }, "podcastId": { "type": "string" }, "sentences": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "startSecond": { "type": "number" }, "endSecond": { "type": "number" } }, "required": [ "text", "startSecond", "endSecond" ], "additionalProperties": false } } }, "required": [ "episodeId", "podcastId", "sentences" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/episodes/latest (PUBLIC) **Latest Episodes** Get the latest 150 episodes ```bash curl -X GET "http://localhost:4000/api/v1/episodes/latest?categories=technology%2Cbusiness%2Cnews&hasTranscript=true&language=en" \ -H "Content-Type: application/json" ``` **Query schema:** ```json { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "podcastImageRequired": { "type": "boolean" }, "hasTranscript": { "type": "boolean" }, "language": { "default": "en", "type": "string" } }, "required": [ "language" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "latestPodcasts": { "type": "array", "items": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "episodes": { "type": "array", "items": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "nullable": true }, "description": { "nullable": true, "type": "string" }, "durationSeconds": { "nullable": true, "type": "number" }, "enclosureUrl": { "type": "string" }, "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "episodeGuestsAndHosts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "nullable": true, "type": "string" }, "episodeSponsors": { "nullable": true, "type": "array", "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "nullable": true, "type": "string" }, "episodeThumbnailRssUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "podcastSlug": { "type": "string" }, "publishedAt": {}, "title": { "type": "string" }, "transcriptId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transcriptionRequestedAt": { "nullable": true }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "nullable": true, "type": "object", "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "nullable": true, "type": "number" }, "youtubeDataFetchedAt": { "nullable": true } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "deepAnalysisRequestedAt", "description", "durationSeconds", "enclosureUrl", "episodeId", "episodeGuestsAndHosts", "episodeSlug", "episodeShortDescription", "episodeSponsors", "hasTranscript", "imageUrl", "episodeThumbnailRssUrl", "podcastId", "podcastSlug", "publishedAt", "title", "transcriptId", "transcriptionRequestedAt", "youtubeEpisodeDetails", "applePodcastsUrl" ], "additionalProperties": false } } }, "required": [ "podcast", "episodes" ], "additionalProperties": false } } }, "required": [ "latestPodcasts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Guest Profiles #### POST /api/v1/guest-profiles/:guestProfileId/archive **Archive Guest Profile** Archive a guest profile and its associated project. This sets the status to ARCHIVED. ```bash curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/archive" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/guest-profiles **Create Guest Profile** Create a new guest profile with basic information. The profile is created in ACTIVE status along with an associated project. Required fields are firstName, lastName, and shortBio. Optional fields include contact details, social links, and bio details. When provided, LinkedIn URLs trigger a profile scrape, website URLs trigger a website crawl, and company names trigger a SERP search — all run asynchronously in the background. A guest appearances search is also triggered automatically. ```bash curl -X POST "http://localhost:4000/api/v1/guest-profiles" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "firstName": "Jane", "lastName": "Doe", "shortBio": "Jane Doe is a marketing expert with 10 years of experience in B2B SaaS." }' ``` **Request body schema:** ```json { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "description": "First name of the guest" }, "lastName": { "type": "string", "minLength": 1, "description": "Last name of the guest" }, "shortBio": { "type": "string", "minLength": 1, "description": "A short bio for the guest" }, "longBio": { "description": "A longer bio for the guest", "type": "string" }, "email": { "description": "Email address", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "Phone number", "type": "string" }, "companyName": { "description": "Company name", "type": "string" }, "websiteUrl": { "description": "Website URL", "type": "string", "format": "uri" }, "bookingUrl": { "description": "Calendar booking URL", "type": "string", "format": "uri" }, "linkedIn": { "description": "LinkedIn profile URL", "type": "string", "format": "uri" }, "onePagerUrl": { "description": "One-pager document URL", "type": "string", "format": "uri" }, "topicsToDiscuss": { "description": "Topics the guest wants to discuss", "type": "array", "items": { "type": "string" } }, "areasOfExpertise": { "description": "Areas of expertise", "type": "array", "items": { "type": "string" } }, "goals": { "description": "Goals for podcast appearances", "type": "array", "items": { "type": "string" } }, "thingsToAvoid": { "description": "Topics or things to avoid", "type": "array", "items": { "type": "string" } }, "additionalContext": { "description": "Any additional context about the guest", "type": "string" }, "createAlert": { "description": "Optionally create a person alert for this guest, defaults to true", "type": "boolean" } }, "required": [ "firstName", "lastName", "shortBio" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "guestProfileId": { "type": "string" }, "guestProfileSlug": { "type": "string" }, "projectId": { "type": "string" }, "projectSlug": { "type": "string" } }, "required": [ "guestProfileId", "guestProfileSlug", "projectId", "projectSlug" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/guest-profiles/:guestProfileId/download **Download Guest Profile** Download a guest profile as a document. Supported formats are HTML, DOCX, and PDF. ```bash curl -X GET "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/download" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "format": { "type": "string", "enum": [ "html", "docx", "pdf" ], "description": "The format to download the guest profile in. Supported formats: html, docx, pdf" } }, "required": [ "format" ], "additionalProperties": false } ``` **Response schema:** ```json { "description": "Binary file download — response body is the raw file (no JSON schema).", "contentType": "application/octet-stream" } ``` --- #### GET /api/v1/guest-profiles/:guestProfileIdOrProjectId **Get Guest Profile Details** Get detailed information about a specific guest profile including bio, contact details, social media links, and documents ```bash curl -X GET "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileIdOrProjectId": { "type": "string", "description": "The id of the project associated with the guest profile or the guest profile id." } }, "required": [ "guestProfileIdOrProjectId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "projectId": { "type": "string" }, "projectSlug": { "type": "string" }, "guestProfileId": { "type": "string" }, "guestProfileSlug": { "type": "string" }, "publicSlug": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "createdAt": {}, "updatedAt": {}, "documents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "number" }, "status": { "type": "string" }, "fileType": { "type": "string" }, "dateExtracted": { "nullable": true } }, "required": [ "name", "id", "size", "status", "fileType", "dateExtracted" ], "additionalProperties": false } }, "listedPodcastsCount": { "type": "number" }, "bookingUrl": { "nullable": true, "type": "string" }, "companyName": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "firstName": { "nullable": true, "type": "string" }, "lastName": { "nullable": true, "type": "string" }, "onePagerUrl": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "websiteUrl": { "nullable": true, "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" } }, "required": [ "userId", "email" ], "additionalProperties": false }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "lastScrapedAt": { "nullable": true }, "lastScrapeFailedAt": { "nullable": true }, "isScraping": { "type": "boolean" } }, "required": [ "socialMediaType", "url", "lastScrapedAt", "lastScrapeFailedAt", "isScraping" ], "additionalProperties": false } }, "guestBio": { "nullable": true, "type": "object", "properties": { "additionalContext": { "nullable": true, "type": "string" }, "areasOfExpertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "longBio": { "type": "string" }, "shortBio": { "type": "string" }, "thingsToAvoid": { "type": "array", "items": { "type": "string" } }, "topicsToDiscuss": { "type": "array", "items": { "type": "string" } } }, "required": [ "additionalContext", "areasOfExpertise", "goals", "longBio", "shortBio", "thingsToAvoid", "topicsToDiscuss" ], "additionalProperties": false }, "publicViewSettings": { "nullable": true, "type": "object", "properties": { "displayLinkedIn": { "type": "boolean" }, "displaySocials": { "type": "boolean" }, "displayPreviousPodcastAppearances": { "type": "boolean" }, "marketingLetterMarkdownText": { "nullable": true, "type": "string" }, "publicSlug": { "nullable": true, "type": "string" } }, "required": [ "displayLinkedIn", "displaySocials", "displayPreviousPodcastAppearances", "marketingLetterMarkdownText", "publicSlug" ], "additionalProperties": false } }, "required": [ "projectId", "projectSlug", "guestProfileId", "guestProfileSlug", "publicSlug", "name", "status", "createdAt", "updatedAt", "documents", "listedPodcastsCount", "bookingUrl", "companyName", "email", "firstName", "lastName", "onePagerUrl", "phone", "websiteUrl", "imageUrl", "createdBy", "socialMediaLinks", "guestBio", "publicViewSettings" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/guest-profiles/:guestProfileId/regenerate-bio **Regenerate Guest Bio** Use AI to regenerate the guest bio based on all available profile data including documents, LinkedIn data, and website content. Returns the generated bio fields. ```bash curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/regenerate-bio" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "answer": { "type": "object", "properties": { "shortBio": { "type": "string" }, "longBio": { "type": "string" }, "goals": {}, "thingsToAvoid": {}, "areasOfExpertise": {}, "topicsToDiscuss": {} }, "required": [ "shortBio", "longBio", "goals", "thingsToAvoid", "areasOfExpertise", "topicsToDiscuss" ], "additionalProperties": false } }, "required": [ "answer" ], "additionalProperties": false } }, "required": [ "result" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PUT /api/v1/guest-profiles/:guestProfileId/bio **Update Guest Profile Bio** Update the bio fields of a guest profile including short bio, long bio, goals, areas of expertise, topics to discuss, things to avoid, and additional context. ```bash curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/bio" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "additionalContext": { "description": "Any additional context about the guest", "type": "string" }, "areasOfExpertise": { "description": "Areas of expertise", "type": "array", "items": { "type": "string" } }, "goals": { "description": "Goals for podcast appearances", "type": "array", "items": { "type": "string" } }, "longBio": { "description": "A longer bio for the guest", "type": "string" }, "shortBio": { "description": "A short bio for the guest", "type": "string" }, "thingsToAvoid": { "description": "Topics or things to avoid", "type": "array", "items": { "type": "string" } }, "topicsToDiscuss": { "description": "Topics the guest wants to discuss", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PUT /api/v1/guest-profiles/:guestProfileId/contact-details **Update Guest Profile Contact Details** Update the contact details of a guest profile including name, email, phone, company, website URL, booking URL, LinkedIn, and one-pager URL. ```bash curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/contact-details" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "bookingUrl": { "description": "Calendar booking URL", "type": "string" }, "onePagerUrl": { "description": "One-pager document URL", "type": "string" }, "companyName": { "description": "Company name", "type": "string" }, "email": { "description": "Email address", "type": "string" }, "firstName": { "description": "First name", "type": "string" }, "lastName": { "description": "Last name", "type": "string" }, "linkedIn": { "description": "LinkedIn profile URL", "type": "string" }, "name": { "description": "Full name", "type": "string" }, "phone": { "description": "Phone number", "type": "string" }, "websiteUrl": { "description": "Website URL", "type": "string" } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PUT /api/v1/guest-profiles/:guestProfileId/social-media-links **Update Guest Profile Social Media Links** Update the social media links associated with a guest profile. ```bash curl -X PUT "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/social-media-links" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "socialMediaType", "url" ], "additionalProperties": false } } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "linkedInScrapeTriggerFailures": { "description": "LinkedIn URLs for which a scrape job could not be started.", "type": "array", "items": { "type": "string" } } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/guest-profiles/:guestProfileId/documents **Upload Guest Profile Documents** Upload files (PDF, DOCX, TXT, CSV, JPG, JPEG, PNG) to a guest profile. Documents are automatically analyzed in the background. Send files as multipart form data with field name "documents". Maximum 5 files per request. ```bash curl -X POST "http://localhost:4000/api/v1/guest-profiles/example-guest-profile-id/documents" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "guestProfileId": { "type": "string", "description": "The guest profile ID" } }, "required": [ "guestProfileId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "uploadedDocuments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The document ID" }, "fileName": { "type": "string", "description": "Original file name" }, "fileSize": { "type": "number", "description": "File size in bytes" } }, "required": [ "id", "fileName", "fileSize" ], "additionalProperties": false } } }, "required": [ "uploadedDocuments" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Podcasts #### GET /api/v1/podcasts/apple-id/lookup **Apple ID Comprehensive Lookup** Comprehensive lookup by Apple ID - checks Podcast, PodcastAppleId, PodcastNewRequest, and scraper database ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/apple-id/lookup?id=315114957" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Apple Podcasts ID" } }, "required": [ "id" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "appleId": { "type": "number" }, "status": { "type": "string", "enum": [ "found", "linked", "apple_details_not_found", "apple_not_scraped", "create_podcast_failed", "duplicate_apple_id", "duplicate_podcast_guid", "duplicate_rss_url", "malformed_apple_url", "no_episodes_count", "no_podcast_image", "non_us_apple_url", "not_active", "request_not_found", "rss_download_failed", "rss_parsing_failed", "rss_url_not_found", "import_error_unknown", "pending_import", "scraped_not_imported_non_english", "scraped_not_imported_no_rss_url", "scraped_not_imported_not_fully_scraped", "scraped_not_imported_too_few_episodes", "scraped_not_imported_inactive", "scraped_not_imported_low_engagement", "scraped_not_imported_unknown", "not_found" ] }, "podcast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "isPrimaryAppleId": { "type": "boolean" }, "primaryAppleId": { "type": "number" }, "createdAt": {}, "podEngineUrl": { "type": "string", "description": "Direct link to the podcast in the Pod Engine app" } }, "required": [ "id", "slug", "title", "imageUrl", "isPrimaryAppleId", "primaryAppleId", "createdAt", "podEngineUrl" ], "additionalProperties": false }, "importRequest": { "nullable": true, "type": "object", "properties": { "id": { "type": "number" }, "appleTitle": { "type": "string" }, "rssUrl": { "type": "string" }, "creationSource": { "type": "string" }, "createdAt": {}, "importedAt": { "nullable": true }, "podcastId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "importErrorAt": { "nullable": true }, "importError": { "nullable": true, "type": "string" }, "importErrorType": { "nullable": true, "type": "string" } }, "required": [ "id", "appleTitle", "rssUrl", "creationSource", "createdAt", "importedAt", "podcastId", "importErrorAt", "importError", "importErrorType" ], "additionalProperties": false }, "scraperData": { "nullable": true, "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "country": { "type": "string" }, "podcastTitle": { "type": "string" }, "createdAt": {}, "lastScrapedAt": { "nullable": true }, "lastSuccessAt": { "nullable": true }, "lastErrorAt": { "nullable": true }, "rssUrl": { "nullable": true, "type": "string" }, "ratingsCount": { "nullable": true, "type": "number" }, "averageRating": { "nullable": true, "type": "number" }, "episodesCount": { "nullable": true, "type": "number" }, "lastEpisodeDate": { "nullable": true }, "isLikelyNonEnglishTitle": { "type": "boolean" }, "skippedPodcastImportReason": { "nullable": true, "type": "string" }, "skippedPodcastImportAt": { "nullable": true } }, "required": [ "id", "country", "podcastTitle", "createdAt", "lastScrapedAt", "lastSuccessAt", "lastErrorAt", "rssUrl", "ratingsCount", "averageRating", "episodesCount", "lastEpisodeDate", "isLikelyNonEnglishTitle", "skippedPodcastImportReason", "skippedPodcastImportAt" ], "additionalProperties": false } }, "countries": { "type": "array", "items": { "type": "string" } }, "mostRecentScrape": { "nullable": true }, "recentAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "createdAt": {}, "type": { "type": "string" }, "url": { "type": "string" }, "appleId": { "nullable": true, "type": "number" }, "spotifyId": { "nullable": true, "type": "string" }, "podcastId": { "nullable": true, "type": "string" }, "errorType": { "nullable": true, "type": "string" }, "errorDetails": { "nullable": true, "type": "string" }, "timeTakenMs": { "type": "number" } }, "required": [ "id", "createdAt", "type", "url", "appleId", "spotifyId", "podcastId", "errorType", "errorDetails", "timeTakenMs" ], "additionalProperties": false } } }, "required": [ "entries", "countries", "mostRecentScrape", "recentAttempts" ], "additionalProperties": false } }, "required": [ "appleId", "status", "podcast", "importRequest", "scraperData" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/latest (PUBLIC) **Latest Podcasts** Get the latest podcasts ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/latest?hasTranscripts=true" \ -H "Content-Type: application/json" ``` **Query schema:** ```json { "type": "object", "properties": { "hasTranscripts": { "type": "boolean" } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } } }, "required": [ "podcasts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/multiple **Multiple Podcasts** Get multiple podcasts by their IDs in a single request ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/multiple?podcastIds=58bb043a-ad45-4844-a6d8-7492d901dc30%2C7b09a744-f2ed-458e-9b04-0c0c48651c2a&details=basic" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "podcastIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Array of podcast IDs to fetch" }, "details": { "default": "basic", "description": "Level of detail to return for each podcast", "type": "string", "enum": [ "basic", "full" ] } }, "required": [ "podcastIds", "details" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "podcastIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Array of podcast IDs to fetch" }, "details": { "default": "basic", "description": "Level of detail to return for each podcast", "type": "string", "enum": [ "basic", "full" ] } }, "required": [ "podcastIds", "details" ], "additionalProperties": false }, "totalRequested": { "type": "number" }, "totalFound": { "type": "number" }, "podcasts": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" }, "appleId": { "type": "number" }, "blocked": { "type": "object", "properties": { "blockedDate": {}, "blockedReason": { "type": "string" } }, "required": [ "blockedDate" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "nullable": true, "type": "boolean" }, "hostNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "nullable": true, "type": "object", "properties": { "affiliateOrganizationName": { "nullable": true, "description": "The name of the affiliate organization", "type": "string" }, "affiliationType": { "nullable": true, "description": "The type of affiliation from the list: academic, branded, celebrity, government, independent, legacy media, podcast company, new media, not for profit, religious, other, unknown", "type": "string", "enum": [ "academic", "branded", "celebrity", "government", "independent", "legacy media", "podcast company", "new media", "not for profit", "religious", "other", "unknown" ] } }, "additionalProperties": false }, "podcastDirectoryLinks": { "type": "object", "properties": { "amazonmusic": { "type": "string", "format": "uri" }, "anchor": { "type": "string", "format": "uri" }, "antennapod": { "type": "string", "format": "uri" }, "anytimeplayer": { "type": "string", "format": "uri" }, "apollo": { "type": "string", "format": "uri" }, "apple": { "type": "string", "format": "uri" }, "audible": { "type": "string", "format": "uri" }, "breez": { "type": "string", "format": "uri" }, "castamatic": { "type": "string", "format": "uri" }, "castbox": { "type": "string", "format": "uri" }, "castro": { "type": "string", "format": "uri" }, "curiocaster": { "type": "string", "format": "uri" }, "fountain": { "type": "string", "format": "uri" }, "goodpods": { "type": "string", "format": "uri" }, "google": { "type": "string", "format": "uri" }, "gpodder": { "type": "string", "format": "uri" }, "iheartradio": { "type": "string", "format": "uri" }, "listennotes": { "type": "string", "format": "uri" }, "lnbeats": { "type": "string", "format": "uri" }, "moonfm": { "type": "string", "format": "uri" }, "overcast": { "type": "string", "format": "uri" }, "playerfm": { "type": "string", "format": "uri" }, "pocketcasts": { "type": "string", "format": "uri" }, "podbean": { "type": "string", "format": "uri" }, "podcastaddict": { "type": "string", "format": "uri" }, "podcastguru": { "type": "string", "format": "uri" }, "podcastrepublic": { "type": "string", "format": "uri" }, "podchaser": { "type": "string", "format": "uri" }, "podfriend": { "type": "string", "format": "uri" }, "podknife": { "type": "string", "format": "uri" }, "podlp": { "type": "string", "format": "uri" }, "podnews": { "type": "string", "format": "uri" }, "podscan": { "type": "string", "format": "uri" }, "podscribe": { "type": "string", "format": "uri" }, "podstation": { "type": "string", "format": "uri" }, "podurama": { "type": "string", "format": "uri" }, "podverse": { "type": "string", "format": "uri" }, "radiopublic": { "type": "string", "format": "uri" }, "rephonic": { "type": "string", "format": "uri" }, "sonnet": { "type": "string", "format": "uri" }, "spotify": { "type": "string", "format": "uri" }, "stenofm": { "type": "string", "format": "uri" }, "truefans": { "type": "string", "format": "uri" }, "tunein": { "type": "string", "format": "uri" }, "youtubemusic": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "podcastHasGuests": { "nullable": true, "type": "boolean" }, "podcastHasSponsors": { "nullable": true, "type": "boolean" }, "podcastLocations": { "nullable": true, "type": "array", "items": { "type": "string" } }, "primaryContactEmail": { "nullable": true, "type": "string" }, "rssFeedUrl": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "spotifyId": { "nullable": true, "type": "string" }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "nullable": true }, "firstEpisodePublishedAt": { "nullable": true }, "transcriptsCount": { "type": "number" }, "updateFrequency": { "type": "string", "enum": [ "daily", "weekly", "bi-weekly", "monthly", "stale", "very-stale" ] } }, "required": [ "downloadCount", "episodeCount", "latestPublishedAt", "firstEpisodePublishedAt", "transcriptsCount", "updateFrequency" ], "additionalProperties": false }, "titleLatestCleaned": { "nullable": true, "type": "string" }, "transcriptionMode": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "episodes-since" ] }, "transcribeSince": {} }, "required": [ "mode", "transcribeSince" ], "additionalProperties": false } ] }, "websiteUrl": { "nullable": true, "type": "string" }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "nullable": true, "type": "number" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest", "appleId", "description", "emails", "explicitRss", "hostNames", "ignore", "isClaimed", "podcastAffiliation", "podcastDirectoryLinks", "podcastHasGuests", "podcastHasSponsors", "podcastLocations", "primaryContactEmail", "rssFeedUrl", "socialMediaLinks", "spotifyId", "stats", "titleLatestCleaned", "transcriptionMode", "websiteUrl" ], "additionalProperties": false } ] } } }, "required": [ "options", "totalRequested", "totalFound", "podcasts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/all-details **Podcast All Details** This wraps all the other endpoints for a podcast so you can get all the details in a single request. ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/all-details" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" }, "appleId": { "type": "number" }, "blocked": { "type": "object", "properties": { "blockedDate": {}, "blockedReason": { "type": "string" } }, "required": [ "blockedDate" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "nullable": true, "type": "boolean" }, "hostNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "nullable": true, "type": "object", "properties": { "affiliateOrganizationName": { "nullable": true, "description": "The name of the affiliate organization", "type": "string" }, "affiliationType": { "nullable": true, "description": "The type of affiliation from the list: academic, branded, celebrity, government, independent, legacy media, podcast company, new media, not for profit, religious, other, unknown", "type": "string", "enum": [ "academic", "branded", "celebrity", "government", "independent", "legacy media", "podcast company", "new media", "not for profit", "religious", "other", "unknown" ] } }, "additionalProperties": false }, "podcastDirectoryLinks": { "type": "object", "properties": { "amazonmusic": { "type": "string", "format": "uri" }, "anchor": { "type": "string", "format": "uri" }, "antennapod": { "type": "string", "format": "uri" }, "anytimeplayer": { "type": "string", "format": "uri" }, "apollo": { "type": "string", "format": "uri" }, "apple": { "type": "string", "format": "uri" }, "audible": { "type": "string", "format": "uri" }, "breez": { "type": "string", "format": "uri" }, "castamatic": { "type": "string", "format": "uri" }, "castbox": { "type": "string", "format": "uri" }, "castro": { "type": "string", "format": "uri" }, "curiocaster": { "type": "string", "format": "uri" }, "fountain": { "type": "string", "format": "uri" }, "goodpods": { "type": "string", "format": "uri" }, "google": { "type": "string", "format": "uri" }, "gpodder": { "type": "string", "format": "uri" }, "iheartradio": { "type": "string", "format": "uri" }, "listennotes": { "type": "string", "format": "uri" }, "lnbeats": { "type": "string", "format": "uri" }, "moonfm": { "type": "string", "format": "uri" }, "overcast": { "type": "string", "format": "uri" }, "playerfm": { "type": "string", "format": "uri" }, "pocketcasts": { "type": "string", "format": "uri" }, "podbean": { "type": "string", "format": "uri" }, "podcastaddict": { "type": "string", "format": "uri" }, "podcastguru": { "type": "string", "format": "uri" }, "podcastrepublic": { "type": "string", "format": "uri" }, "podchaser": { "type": "string", "format": "uri" }, "podfriend": { "type": "string", "format": "uri" }, "podknife": { "type": "string", "format": "uri" }, "podlp": { "type": "string", "format": "uri" }, "podnews": { "type": "string", "format": "uri" }, "podscan": { "type": "string", "format": "uri" }, "podscribe": { "type": "string", "format": "uri" }, "podstation": { "type": "string", "format": "uri" }, "podurama": { "type": "string", "format": "uri" }, "podverse": { "type": "string", "format": "uri" }, "radiopublic": { "type": "string", "format": "uri" }, "rephonic": { "type": "string", "format": "uri" }, "sonnet": { "type": "string", "format": "uri" }, "spotify": { "type": "string", "format": "uri" }, "stenofm": { "type": "string", "format": "uri" }, "truefans": { "type": "string", "format": "uri" }, "tunein": { "type": "string", "format": "uri" }, "youtubemusic": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "podcastHasGuests": { "nullable": true, "type": "boolean" }, "podcastHasSponsors": { "nullable": true, "type": "boolean" }, "podcastLocations": { "nullable": true, "type": "array", "items": { "type": "string" } }, "primaryContactEmail": { "nullable": true, "type": "string" }, "rssFeedUrl": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "spotifyId": { "nullable": true, "type": "string" }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "nullable": true }, "firstEpisodePublishedAt": { "nullable": true }, "transcriptsCount": { "type": "number" }, "updateFrequency": { "type": "string", "enum": [ "daily", "weekly", "bi-weekly", "monthly", "stale", "very-stale" ] } }, "required": [ "downloadCount", "episodeCount", "latestPublishedAt", "firstEpisodePublishedAt", "transcriptsCount", "updateFrequency" ], "additionalProperties": false }, "titleLatestCleaned": { "nullable": true, "type": "string" }, "transcriptionMode": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "episodes-since" ] }, "transcribeSince": {} }, "required": [ "mode", "transcribeSince" ], "additionalProperties": false } ] }, "websiteUrl": { "nullable": true, "type": "string" }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "nullable": true, "type": "number" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest", "appleId", "description", "emails", "explicitRss", "hostNames", "ignore", "isClaimed", "podcastAffiliation", "podcastDirectoryLinks", "podcastHasGuests", "podcastHasSponsors", "podcastLocations", "primaryContactEmail", "rssFeedUrl", "socialMediaLinks", "spotifyId", "stats", "titleLatestCleaned", "transcriptionMode", "websiteUrl" ], "additionalProperties": false }, "recentEpisodes": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "nullable": true }, "description": { "nullable": true, "type": "string" }, "durationSeconds": { "nullable": true, "type": "number" }, "enclosureUrl": { "type": "string" }, "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "episodeGuestsAndHosts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "nullable": true, "type": "string" }, "episodeSponsors": { "nullable": true, "type": "array", "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "nullable": true, "type": "string" }, "episodeThumbnailRssUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "podcastSlug": { "type": "string" }, "publishedAt": {}, "title": { "type": "string" }, "transcriptId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transcriptionRequestedAt": { "nullable": true }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "nullable": true, "type": "object", "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "nullable": true, "type": "number" }, "youtubeDataFetchedAt": { "nullable": true } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "deepAnalysisRequestedAt", "description", "durationSeconds", "enclosureUrl", "episodeId", "episodeGuestsAndHosts", "episodeSlug", "episodeShortDescription", "episodeSponsors", "hasTranscript", "imageUrl", "episodeThumbnailRssUrl", "podcastId", "podcastSlug", "publishedAt", "title", "transcriptId", "transcriptionRequestedAt", "youtubeEpisodeDetails", "applePodcastsUrl" ], "additionalProperties": false } }, "contacts": { "nullable": true, "type": "object", "properties": { "podcastId": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address associated with the podcast contact" }, "verifiedAt": { "nullable": true, "description": "The timestamp when the email was last verified, or null if it has not been verified" }, "syntaxValid": { "nullable": true, "description": "Whether the email address has valid syntax (e.g. correctly formatted local and domain parts), or null if not yet checked", "type": "boolean" }, "mxValid": { "nullable": true, "description": "Whether the email's domain has valid MX records indicating it can receive mail, or null if not yet checked", "type": "boolean" }, "deepVerifiedAt": { "nullable": true, "description": "The timestamp when the email was last deep-verified for deliverability, or null if not run" }, "deliverabilityStatus": { "nullable": true, "description": "Deep deliverability status: valid, invalid, catch-all, unknown, spamtrap, abuse, or do_not_mail", "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown", "spamtrap", "abuse", "do_not_mail" ] }, "deliverabilityReason": { "nullable": true, "description": "Sub-classification providing more detail on the deliverability result", "type": "string" }, "isFreeEmailProvider": { "nullable": true, "description": "Whether the address belongs to a known free-email provider (e.g. gmail, yahoo)", "type": "boolean" }, "suggestedCorrection": { "nullable": true, "description": "Suggested correction for likely typos, e.g. gmial.com -> gmail.com", "type": "string" } }, "required": [ "email", "verifiedAt", "syntaxValid", "mxValid", "deepVerifiedAt", "deliverabilityStatus", "deliverabilityReason", "isFreeEmailProvider", "suggestedCorrection" ], "additionalProperties": false } }, "phoneNumbers": { "type": "array", "items": { "type": "string" } }, "websites": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "verified": { "type": "boolean" }, "contactUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "verified", "contactUrls" ], "additionalProperties": false } } }, "required": [ "podcastId", "emails", "phoneNumbers", "websites" ], "additionalProperties": false }, "guests": { "nullable": true, "type": "object", "properties": { "episodesCount": { "type": "number" }, "episodesWithGuestsCount": { "type": "number" }, "mostRecentEpisodeDate": {}, "oldestEpisodeDate": {}, "guests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "nullable": true, "type": "string" }, "appearancesCount": { "type": "number", "minimum": 1 }, "mostRecentAppearanceDate": {}, "oldestAppearanceDate": {} }, "required": [ "name", "type", "imageUrl", "appearancesCount", "mostRecentAppearanceDate", "oldestAppearanceDate" ], "additionalProperties": false } } }, "required": [ "episodesCount", "episodesWithGuestsCount", "mostRecentEpisodeDate", "oldestEpisodeDate", "guests" ], "additionalProperties": false }, "reviews": { "nullable": true, "type": "object", "properties": { "podcastId": { "type": "string" }, "appleId": { "type": "number" }, "spotifyId": { "nullable": true, "type": "string" }, "applePodcastsReview": { "nullable": true, "type": "object", "properties": { "appleId": { "type": "number" }, "scrapedAt": {}, "country": { "type": "string" }, "reviewsCount": { "type": "number" }, "rating": { "nullable": true, "type": "number" }, "oneStarCount": { "type": "number" }, "twoStarCount": { "type": "number" }, "threeStarCount": { "type": "number" }, "fourStarCount": { "type": "number" }, "fiveStarCount": { "type": "number" } }, "required": [ "appleId", "scrapedAt", "country", "reviewsCount", "rating", "oneStarCount", "twoStarCount", "threeStarCount", "fourStarCount", "fiveStarCount" ], "additionalProperties": false }, "spotifyReview": { "nullable": true, "type": "object", "properties": { "spotifyId": { "type": "string" }, "scrapedAt": {}, "reviewsCount": { "type": "number" }, "rating": { "nullable": true, "type": "number" } }, "required": [ "spotifyId", "scrapedAt", "reviewsCount", "rating" ], "additionalProperties": false }, "castbox": { "nullable": true, "type": "object", "properties": { "scrapedAt": {}, "plays": { "type": "number" }, "subscribers": { "type": "number" } }, "required": [ "scrapedAt", "plays", "subscribers" ], "additionalProperties": false } }, "required": [ "podcastId", "appleId", "spotifyId", "applePodcastsReview", "spotifyReview", "castbox" ], "additionalProperties": false }, "socialMedia": { "nullable": true, "type": "object", "properties": { "podcastId": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "facebookPageData": { "type": "array", "items": { "type": "object", "properties": { "facebookPageId": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "followers": { "type": "number", "minimum": 0 }, "likes": { "type": "number", "minimum": 0 }, "following": { "type": "number", "minimum": 0 }, "talkingAboutCount": { "nullable": true, "type": "number" }, "facebookPageUrl": { "type": "string" }, "scrapedAt": {} }, "required": [ "facebookPageId", "profilePhotoUrl", "name", "followers", "likes", "following", "talkingAboutCount", "facebookPageUrl", "scrapedAt" ], "additionalProperties": false } }, "instagramData": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "number" }, "followers": { "type": "number" }, "following": { "type": "number" }, "posts": { "type": "number" }, "instagramProfileName": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "scrapedAt": {} }, "required": [ "profileId", "followers", "following", "posts", "instagramProfileName", "profilePhotoUrl", "scrapedAt" ], "additionalProperties": false } }, "linkedInCompanyData": { "type": "array", "items": { "type": "object", "properties": { "scrapedAt": {}, "linkedInCompanyId": { "type": "string" }, "linkedInUrl": { "type": "string" }, "name": { "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "employeesInLinkedin": { "type": "number" }, "about": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "companySize": { "nullable": true, "type": "string" }, "industries": { "nullable": true, "type": "string" }, "logoImageUrl": { "nullable": true, "type": "string" }, "mostRecentUpdate": { "nullable": true, "type": "object", "properties": { "postId": { "type": "string" }, "likesCount": { "type": "number" }, "commentsCount": { "type": "number" }, "title": { "type": "string" }, "text": { "type": "string" }, "postUrl": { "type": "string" }, "date": {} }, "required": [ "postId", "likesCount", "commentsCount", "title", "text", "postUrl", "date" ], "additionalProperties": false } }, "required": [ "scrapedAt", "linkedInCompanyId", "linkedInUrl", "name", "countryCode", "followers", "employeesInLinkedin", "about", "description", "companySize", "industries", "logoImageUrl", "mostRecentUpdate" ], "additionalProperties": false } }, "linkedInPersonData": { "type": "array", "items": { "type": "object", "properties": { "scrapedAt": {}, "name": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "linkedInProfileId": { "type": "string" }, "linkedInNumericId": { "type": "number" }, "avatarUrl": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "about": { "nullable": true, "type": "string" }, "location": { "nullable": true, "type": "string" }, "followerCount": { "type": "number" }, "connectionsCount": { "type": "number" }, "recommendationsCount": { "type": "number" } }, "required": [ "scrapedAt", "name", "profilePhotoUrl", "linkedInProfileId", "linkedInNumericId", "avatarUrl", "city", "countryCode", "description", "about", "location", "followerCount", "connectionsCount", "recommendationsCount" ], "additionalProperties": false } }, "tiktokData": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "awgEngagementRate": { "nullable": true, "type": "number" }, "biography": { "nullable": true, "type": "string" }, "commentEngagementRate": { "nullable": true, "type": "number" }, "dateJoined": {}, "followers": { "type": "number" }, "following": { "type": "number" }, "isPrivate": { "type": "boolean" }, "isVerified": { "type": "boolean" }, "likeEngagementRate": { "nullable": true, "type": "number" }, "likes": { "type": "number" }, "nickname": { "type": "string" }, "handle": { "type": "string" }, "profilePicUrl": { "nullable": true, "type": "string", "format": "uri" }, "videosCount": { "type": "number" }, "scrapedAt": {} }, "required": [ "accountId", "awgEngagementRate", "biography", "commentEngagementRate", "dateJoined", "followers", "following", "isPrivate", "isVerified", "likeEngagementRate", "likes", "nickname", "handle", "profilePicUrl", "videosCount", "scrapedAt" ], "additionalProperties": false } }, "twitterData": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string" }, "profileName": { "type": "string" }, "profileUrl": { "type": "string", "format": "uri" }, "profileImageUrl": { "nullable": true, "type": "string", "format": "uri" }, "biography": { "nullable": true, "type": "string" }, "followingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "followerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "postsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dateJoined": { "nullable": true }, "scrapedAt": {} }, "required": [ "profileId", "profileName", "profileUrl", "profileImageUrl", "biography", "followingCount", "followerCount", "postsCount", "dateJoined", "scrapedAt" ], "additionalProperties": false } } }, "required": [ "podcastId", "socialMediaLinks", "facebookPageData", "instagramData", "linkedInCompanyData", "linkedInPersonData", "tiktokData", "twitterData" ], "additionalProperties": false }, "sponsors": { "nullable": true, "type": "object", "properties": { "episodesCount": { "type": "number" }, "episodesWithSponsorsCount": { "type": "number" }, "mostRecentEpisodeDate": {}, "oldestEpisodeDate": {}, "sponsors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "appearancesCount": { "type": "number", "minimum": 1 }, "mostRecentAppearanceDate": {}, "oldestAppearanceDate": {} }, "required": [ "name", "imageUrl", "appearancesCount", "mostRecentAppearanceDate", "oldestAppearanceDate" ], "additionalProperties": false } } }, "required": [ "episodesCount", "episodesWithSponsorsCount", "mostRecentEpisodeDate", "oldestEpisodeDate", "sponsors" ], "additionalProperties": false }, "relatedPodcasts": { "nullable": true, "type": "object", "properties": { "podcastId": { "type": "string" }, "similarPodcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } } }, "required": [ "podcastId", "similarPodcasts" ], "additionalProperties": false }, "chartPositions": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "chartDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the chart in YYYY-MM-DD format" }, "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "position": { "type": "number" } }, "required": [ "chartDate", "chartType", "country", "category", "position" ], "additionalProperties": false } }, "youtubeData": { "nullable": true, "type": "object", "properties": { "podcastId": { "type": "string" }, "youtubeData": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "subscriberCount": { "type": "number" }, "viewCount": { "type": "number" }, "videoCount": { "type": "number" }, "publishedAt": { "nullable": true }, "thumbnails": { "type": "object", "properties": { "default": { "nullable": true, "type": "string" }, "medium": { "nullable": true, "type": "string" }, "high": { "nullable": true, "type": "string" } }, "required": [ "default", "medium", "high" ], "additionalProperties": false }, "country": { "nullable": true, "type": "string" }, "customUrl": { "nullable": true, "type": "string" }, "links": { "nullable": true, "type": "array", "items": { "type": "string" } }, "isPodcastChannel": { "nullable": true, "type": "boolean" }, "discoverInputKeyword": { "nullable": true, "type": "string" }, "bannerImageUrl": { "nullable": true, "type": "string" }, "videos": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "imageUrl": { "type": "string" }, "isShort": { "type": "boolean" }, "postedAt": {}, "postedAtRelative": { "type": "string" }, "scrapedAt": {}, "title": { "type": "string" }, "videoUrl": { "type": "string" }, "views": { "type": "number" } }, "required": [ "imageUrl", "isShort", "postedAt", "postedAtRelative", "scrapedAt", "title", "videoUrl", "views" ], "additionalProperties": false } }, "profileImageUrl": { "nullable": true, "type": "string" }, "dataLastUpdated": {}, "lastVideoUploadDate": { "nullable": true }, "lastVideoUploadDateSource": { "nullable": true, "type": "string" }, "lastVideoUploadDateCheckedAt": { "nullable": true } }, "required": [ "id", "title", "description", "subscriberCount", "viewCount", "videoCount", "publishedAt", "thumbnails", "country", "customUrl", "links", "isPodcastChannel", "discoverInputKeyword", "bannerImageUrl", "videos", "profileImageUrl", "dataLastUpdated", "lastVideoUploadDate", "lastVideoUploadDateSource", "lastVideoUploadDateCheckedAt" ], "additionalProperties": false } } }, "required": [ "podcastId", "youtubeData" ], "additionalProperties": false } }, "required": [ "podcast", "recentEpisodes", "contacts", "guests", "reviews", "socialMedia", "sponsors", "relatedPodcasts", "chartPositions", "youtubeData" ], "additionalProperties": false } }, "required": [ "podcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/charts **Podcast Chart Position** Get the latest positions of a podcast in a chart ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/charts?country=us" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 }, "limit": { "description": "The number of charts to return", "type": "number" } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "options": { "type": "object", "properties": { "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "positionsLimit": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 }, "limit": { "description": "The number of charts to return", "type": "number" } }, "additionalProperties": false }, "totalCharts": { "type": "number" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "chartDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The date of the chart in YYYY-MM-DD format" }, "chartType": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" }, "country": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." }, "category": { "type": "string", "description": "The chart category defaulting to 'top podcasts'. Apple podcasts supports the following: \"top podcasts\", \"arts\", \"business\", \"comedy\", \"education\", \"fiction\", \"government\", \"health & fitness\", \"history\", \"kids & family\", \"leisure\", \"music\", \"news\", \"religion & spirituality\", \"science\", \"society & culture\", \"sports\", \"technology\", \"true crime\", \"tv & film\"" }, "position": { "type": "number" } }, "required": [ "chartDate", "chartType", "country", "category", "position" ], "additionalProperties": false } } }, "required": [ "podcast", "options", "totalCharts", "positions" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/contacts **Podcast Contacts** Get the contacts for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/contacts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "podcastContacts": { "type": "object", "properties": { "podcastId": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address associated with the podcast contact" }, "verifiedAt": { "nullable": true, "description": "The timestamp when the email was last verified, or null if it has not been verified" }, "syntaxValid": { "nullable": true, "description": "Whether the email address has valid syntax (e.g. correctly formatted local and domain parts), or null if not yet checked", "type": "boolean" }, "mxValid": { "nullable": true, "description": "Whether the email's domain has valid MX records indicating it can receive mail, or null if not yet checked", "type": "boolean" }, "deepVerifiedAt": { "nullable": true, "description": "The timestamp when the email was last deep-verified for deliverability, or null if not run" }, "deliverabilityStatus": { "nullable": true, "description": "Deep deliverability status: valid, invalid, catch-all, unknown, spamtrap, abuse, or do_not_mail", "type": "string", "enum": [ "valid", "invalid", "catch-all", "unknown", "spamtrap", "abuse", "do_not_mail" ] }, "deliverabilityReason": { "nullable": true, "description": "Sub-classification providing more detail on the deliverability result", "type": "string" }, "isFreeEmailProvider": { "nullable": true, "description": "Whether the address belongs to a known free-email provider (e.g. gmail, yahoo)", "type": "boolean" }, "suggestedCorrection": { "nullable": true, "description": "Suggested correction for likely typos, e.g. gmial.com -> gmail.com", "type": "string" } }, "required": [ "email", "verifiedAt", "syntaxValid", "mxValid", "deepVerifiedAt", "deliverabilityStatus", "deliverabilityReason", "isFreeEmailProvider", "suggestedCorrection" ], "additionalProperties": false } }, "phoneNumbers": { "type": "array", "items": { "type": "string" } }, "websites": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "verified": { "type": "boolean" }, "contactUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "verified", "contactUrls" ], "additionalProperties": false } } }, "required": [ "podcastId", "emails", "phoneNumbers", "websites" ], "additionalProperties": false } }, "required": [ "podcast", "podcastContacts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug **Podcast Details** Get a podcast by ID or slug ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" }, "appleId": { "type": "number" }, "blocked": { "type": "object", "properties": { "blockedDate": {}, "blockedReason": { "type": "string" } }, "required": [ "blockedDate" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "nullable": true, "type": "boolean" }, "hostNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "nullable": true, "type": "object", "properties": { "affiliateOrganizationName": { "nullable": true, "description": "The name of the affiliate organization", "type": "string" }, "affiliationType": { "nullable": true, "description": "The type of affiliation from the list: academic, branded, celebrity, government, independent, legacy media, podcast company, new media, not for profit, religious, other, unknown", "type": "string", "enum": [ "academic", "branded", "celebrity", "government", "independent", "legacy media", "podcast company", "new media", "not for profit", "religious", "other", "unknown" ] } }, "additionalProperties": false }, "podcastDirectoryLinks": { "type": "object", "properties": { "amazonmusic": { "type": "string", "format": "uri" }, "anchor": { "type": "string", "format": "uri" }, "antennapod": { "type": "string", "format": "uri" }, "anytimeplayer": { "type": "string", "format": "uri" }, "apollo": { "type": "string", "format": "uri" }, "apple": { "type": "string", "format": "uri" }, "audible": { "type": "string", "format": "uri" }, "breez": { "type": "string", "format": "uri" }, "castamatic": { "type": "string", "format": "uri" }, "castbox": { "type": "string", "format": "uri" }, "castro": { "type": "string", "format": "uri" }, "curiocaster": { "type": "string", "format": "uri" }, "fountain": { "type": "string", "format": "uri" }, "goodpods": { "type": "string", "format": "uri" }, "google": { "type": "string", "format": "uri" }, "gpodder": { "type": "string", "format": "uri" }, "iheartradio": { "type": "string", "format": "uri" }, "listennotes": { "type": "string", "format": "uri" }, "lnbeats": { "type": "string", "format": "uri" }, "moonfm": { "type": "string", "format": "uri" }, "overcast": { "type": "string", "format": "uri" }, "playerfm": { "type": "string", "format": "uri" }, "pocketcasts": { "type": "string", "format": "uri" }, "podbean": { "type": "string", "format": "uri" }, "podcastaddict": { "type": "string", "format": "uri" }, "podcastguru": { "type": "string", "format": "uri" }, "podcastrepublic": { "type": "string", "format": "uri" }, "podchaser": { "type": "string", "format": "uri" }, "podfriend": { "type": "string", "format": "uri" }, "podknife": { "type": "string", "format": "uri" }, "podlp": { "type": "string", "format": "uri" }, "podnews": { "type": "string", "format": "uri" }, "podscan": { "type": "string", "format": "uri" }, "podscribe": { "type": "string", "format": "uri" }, "podstation": { "type": "string", "format": "uri" }, "podurama": { "type": "string", "format": "uri" }, "podverse": { "type": "string", "format": "uri" }, "radiopublic": { "type": "string", "format": "uri" }, "rephonic": { "type": "string", "format": "uri" }, "sonnet": { "type": "string", "format": "uri" }, "spotify": { "type": "string", "format": "uri" }, "stenofm": { "type": "string", "format": "uri" }, "truefans": { "type": "string", "format": "uri" }, "tunein": { "type": "string", "format": "uri" }, "youtubemusic": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "podcastHasGuests": { "nullable": true, "type": "boolean" }, "podcastHasSponsors": { "nullable": true, "type": "boolean" }, "podcastLocations": { "nullable": true, "type": "array", "items": { "type": "string" } }, "primaryContactEmail": { "nullable": true, "type": "string" }, "rssFeedUrl": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "spotifyId": { "nullable": true, "type": "string" }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "nullable": true }, "firstEpisodePublishedAt": { "nullable": true }, "transcriptsCount": { "type": "number" }, "updateFrequency": { "type": "string", "enum": [ "daily", "weekly", "bi-weekly", "monthly", "stale", "very-stale" ] } }, "required": [ "downloadCount", "episodeCount", "latestPublishedAt", "firstEpisodePublishedAt", "transcriptsCount", "updateFrequency" ], "additionalProperties": false }, "titleLatestCleaned": { "nullable": true, "type": "string" }, "transcriptionMode": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "episodes-since" ] }, "transcribeSince": {} }, "required": [ "mode", "transcribeSince" ], "additionalProperties": false } ] }, "websiteUrl": { "nullable": true, "type": "string" }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "nullable": true, "type": "number" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest", "appleId", "description", "emails", "explicitRss", "hostNames", "ignore", "isClaimed", "podcastAffiliation", "podcastDirectoryLinks", "podcastHasGuests", "podcastHasSponsors", "podcastLocations", "primaryContactEmail", "rssFeedUrl", "socialMediaLinks", "spotifyId", "stats", "titleLatestCleaned", "transcriptionMode", "websiteUrl" ], "additionalProperties": false } }, "required": [ "podcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/episodes **Podcast Episodes** Get the episodes for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/episodes" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "hasTranscript": { "type": "boolean" }, "skip": { "type": "number" }, "limit": { "type": "number", "maximum": 100 } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "hasTranscript": { "type": "boolean" }, "skip": { "type": "number" }, "limit": { "type": "number", "maximum": 100 } }, "additionalProperties": false }, "totalEpisodes": { "type": "number" }, "totalTranscripts": { "type": "number" }, "podcastWithEpisodes": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "episodes": { "type": "array", "items": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "nullable": true }, "description": { "nullable": true, "type": "string" }, "durationSeconds": { "nullable": true, "type": "number" }, "enclosureUrl": { "type": "string" }, "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "episodeGuestsAndHosts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "nullable": true, "type": "string" }, "episodeSponsors": { "nullable": true, "type": "array", "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "nullable": true, "type": "string" }, "episodeThumbnailRssUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "podcastSlug": { "type": "string" }, "publishedAt": {}, "title": { "type": "string" }, "transcriptId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transcriptionRequestedAt": { "nullable": true }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "nullable": true, "type": "object", "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "nullable": true, "type": "number" }, "youtubeDataFetchedAt": { "nullable": true } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "nullable": true, "type": "string", "format": "uri" } }, "required": [ "deepAnalysisRequestedAt", "description", "durationSeconds", "enclosureUrl", "episodeId", "episodeGuestsAndHosts", "episodeSlug", "episodeShortDescription", "episodeSponsors", "hasTranscript", "imageUrl", "episodeThumbnailRssUrl", "podcastId", "podcastSlug", "publishedAt", "title", "transcriptId", "transcriptionRequestedAt", "youtubeEpisodeDetails", "applePodcastsUrl" ], "additionalProperties": false } } }, "required": [ "podcast", "episodes" ], "additionalProperties": false } }, "required": [ "options", "totalEpisodes", "totalTranscripts", "podcastWithEpisodes" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/id/lookup **Podcast ID Lookup** Lookup a podcast by ID ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/id/lookup?appleId=315114957" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "appleId": { "description": "Apple Podcasts ID", "type": "number" }, "spotifyId": { "description": "Spotify ID", "type": "string" }, "slug": { "description": "The Pod Engine slug of the podcast", "type": "string" }, "podEngineId": { "description": "The Pod Engine id of the podcast", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false, "description": "Only one of the parameters can be provided." } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "nullable": true, "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } }, "required": [ "podcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/related-podcasts **Podcast Related Podcasts** Get the related podcasts for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/related-podcasts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "relatedPodcasts": { "type": "object", "properties": { "podcastId": { "type": "string" }, "similarPodcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false } } }, "required": [ "podcastId", "similarPodcasts" ], "additionalProperties": false } }, "required": [ "podcast", "relatedPodcasts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/reviews **Podcast Reviews** Get the reviews for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/reviews" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "podcastReviews": { "type": "object", "properties": { "podcastId": { "type": "string" }, "appleId": { "type": "number" }, "spotifyId": { "nullable": true, "type": "string" }, "applePodcastsReview": { "nullable": true, "type": "object", "properties": { "appleId": { "type": "number" }, "scrapedAt": {}, "country": { "type": "string" }, "reviewsCount": { "type": "number" }, "rating": { "nullable": true, "type": "number" }, "oneStarCount": { "type": "number" }, "twoStarCount": { "type": "number" }, "threeStarCount": { "type": "number" }, "fourStarCount": { "type": "number" }, "fiveStarCount": { "type": "number" } }, "required": [ "appleId", "scrapedAt", "country", "reviewsCount", "rating", "oneStarCount", "twoStarCount", "threeStarCount", "fourStarCount", "fiveStarCount" ], "additionalProperties": false }, "spotifyReview": { "nullable": true, "type": "object", "properties": { "spotifyId": { "type": "string" }, "scrapedAt": {}, "reviewsCount": { "type": "number" }, "rating": { "nullable": true, "type": "number" } }, "required": [ "spotifyId", "scrapedAt", "reviewsCount", "rating" ], "additionalProperties": false }, "castbox": { "nullable": true, "type": "object", "properties": { "scrapedAt": {}, "plays": { "type": "number" }, "subscribers": { "type": "number" } }, "required": [ "scrapedAt", "plays", "subscribers" ], "additionalProperties": false } }, "required": [ "podcastId", "appleId", "spotifyId", "applePodcastsReview", "spotifyReview", "castbox" ], "additionalProperties": false } }, "required": [ "podcast", "podcastReviews" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/social-media **Podcast Social Media** Get the social media data for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/social-media" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "socialMediaData": { "type": "object", "properties": { "podcastId": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "facebookPageData": { "type": "array", "items": { "type": "object", "properties": { "facebookPageId": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "followers": { "type": "number", "minimum": 0 }, "likes": { "type": "number", "minimum": 0 }, "following": { "type": "number", "minimum": 0 }, "talkingAboutCount": { "nullable": true, "type": "number" }, "facebookPageUrl": { "type": "string" }, "scrapedAt": {} }, "required": [ "facebookPageId", "profilePhotoUrl", "name", "followers", "likes", "following", "talkingAboutCount", "facebookPageUrl", "scrapedAt" ], "additionalProperties": false } }, "instagramData": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "number" }, "followers": { "type": "number" }, "following": { "type": "number" }, "posts": { "type": "number" }, "instagramProfileName": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "scrapedAt": {} }, "required": [ "profileId", "followers", "following", "posts", "instagramProfileName", "profilePhotoUrl", "scrapedAt" ], "additionalProperties": false } }, "linkedInCompanyData": { "type": "array", "items": { "type": "object", "properties": { "scrapedAt": {}, "linkedInCompanyId": { "type": "string" }, "linkedInUrl": { "type": "string" }, "name": { "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "followers": { "type": "number" }, "employeesInLinkedin": { "type": "number" }, "about": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "companySize": { "nullable": true, "type": "string" }, "industries": { "nullable": true, "type": "string" }, "logoImageUrl": { "nullable": true, "type": "string" }, "mostRecentUpdate": { "nullable": true, "type": "object", "properties": { "postId": { "type": "string" }, "likesCount": { "type": "number" }, "commentsCount": { "type": "number" }, "title": { "type": "string" }, "text": { "type": "string" }, "postUrl": { "type": "string" }, "date": {} }, "required": [ "postId", "likesCount", "commentsCount", "title", "text", "postUrl", "date" ], "additionalProperties": false } }, "required": [ "scrapedAt", "linkedInCompanyId", "linkedInUrl", "name", "countryCode", "followers", "employeesInLinkedin", "about", "description", "companySize", "industries", "logoImageUrl", "mostRecentUpdate" ], "additionalProperties": false } }, "linkedInPersonData": { "type": "array", "items": { "type": "object", "properties": { "scrapedAt": {}, "name": { "type": "string" }, "profilePhotoUrl": { "nullable": true, "type": "string" }, "linkedInProfileId": { "type": "string" }, "linkedInNumericId": { "type": "number" }, "avatarUrl": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "about": { "nullable": true, "type": "string" }, "location": { "nullable": true, "type": "string" }, "followerCount": { "type": "number" }, "connectionsCount": { "type": "number" }, "recommendationsCount": { "type": "number" } }, "required": [ "scrapedAt", "name", "profilePhotoUrl", "linkedInProfileId", "linkedInNumericId", "avatarUrl", "city", "countryCode", "description", "about", "location", "followerCount", "connectionsCount", "recommendationsCount" ], "additionalProperties": false } }, "tiktokData": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "awgEngagementRate": { "nullable": true, "type": "number" }, "biography": { "nullable": true, "type": "string" }, "commentEngagementRate": { "nullable": true, "type": "number" }, "dateJoined": {}, "followers": { "type": "number" }, "following": { "type": "number" }, "isPrivate": { "type": "boolean" }, "isVerified": { "type": "boolean" }, "likeEngagementRate": { "nullable": true, "type": "number" }, "likes": { "type": "number" }, "nickname": { "type": "string" }, "handle": { "type": "string" }, "profilePicUrl": { "nullable": true, "type": "string", "format": "uri" }, "videosCount": { "type": "number" }, "scrapedAt": {} }, "required": [ "accountId", "awgEngagementRate", "biography", "commentEngagementRate", "dateJoined", "followers", "following", "isPrivate", "isVerified", "likeEngagementRate", "likes", "nickname", "handle", "profilePicUrl", "videosCount", "scrapedAt" ], "additionalProperties": false } }, "twitterData": { "type": "array", "items": { "type": "object", "properties": { "profileId": { "type": "string" }, "profileName": { "type": "string" }, "profileUrl": { "type": "string", "format": "uri" }, "profileImageUrl": { "nullable": true, "type": "string", "format": "uri" }, "biography": { "nullable": true, "type": "string" }, "followingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "followerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "postsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dateJoined": { "nullable": true }, "scrapedAt": {} }, "required": [ "profileId", "profileName", "profileUrl", "profileImageUrl", "biography", "followingCount", "followerCount", "postsCount", "dateJoined", "scrapedAt" ], "additionalProperties": false } } }, "required": [ "podcastId", "socialMediaLinks", "facebookPageData", "instagramData", "linkedInCompanyData", "linkedInPersonData", "tiktokData", "twitterData" ], "additionalProperties": false } }, "required": [ "podcast", "socialMediaData" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/youtube **Podcast Youtube Details** Get the youtube data for a podcast ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/youtube" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "youtubeData": { "type": "object", "properties": { "podcastId": { "type": "string" }, "youtubeData": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "subscriberCount": { "type": "number" }, "viewCount": { "type": "number" }, "videoCount": { "type": "number" }, "publishedAt": { "nullable": true }, "thumbnails": { "type": "object", "properties": { "default": { "nullable": true, "type": "string" }, "medium": { "nullable": true, "type": "string" }, "high": { "nullable": true, "type": "string" } }, "required": [ "default", "medium", "high" ], "additionalProperties": false }, "country": { "nullable": true, "type": "string" }, "customUrl": { "nullable": true, "type": "string" }, "links": { "nullable": true, "type": "array", "items": { "type": "string" } }, "isPodcastChannel": { "nullable": true, "type": "boolean" }, "discoverInputKeyword": { "nullable": true, "type": "string" }, "bannerImageUrl": { "nullable": true, "type": "string" }, "videos": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "imageUrl": { "type": "string" }, "isShort": { "type": "boolean" }, "postedAt": {}, "postedAtRelative": { "type": "string" }, "scrapedAt": {}, "title": { "type": "string" }, "videoUrl": { "type": "string" }, "views": { "type": "number" } }, "required": [ "imageUrl", "isShort", "postedAt", "postedAtRelative", "scrapedAt", "title", "videoUrl", "views" ], "additionalProperties": false } }, "profileImageUrl": { "nullable": true, "type": "string" }, "dataLastUpdated": {}, "lastVideoUploadDate": { "nullable": true }, "lastVideoUploadDateSource": { "nullable": true, "type": "string" }, "lastVideoUploadDateCheckedAt": { "nullable": true } }, "required": [ "id", "title", "description", "subscriberCount", "viewCount", "videoCount", "publishedAt", "thumbnails", "country", "customUrl", "links", "isPodcastChannel", "discoverInputKeyword", "bannerImageUrl", "videos", "profileImageUrl", "dataLastUpdated", "lastVideoUploadDate", "lastVideoUploadDateSource", "lastVideoUploadDateCheckedAt" ], "additionalProperties": false } } }, "required": [ "podcastId", "youtubeData" ], "additionalProperties": false } }, "required": [ "podcast", "youtubeData" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastIdOrSlug/refresh **Refresh Podcast** Refresh podcast metadata and thumbnail from RSS feed. Rate limited to once per minute per podcast. ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/refresh?updatePodcastThumbnail=true" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastIdOrSlug": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, "required": [ "podcastIdOrSlug" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "updatePodcastThumbnail": { "type": "boolean" } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" }, "appleId": { "type": "number" }, "blocked": { "type": "object", "properties": { "blockedDate": {}, "blockedReason": { "type": "string" } }, "required": [ "blockedDate" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "nullable": true, "type": "boolean" }, "hostNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "nullable": true, "type": "object", "properties": { "affiliateOrganizationName": { "nullable": true, "description": "The name of the affiliate organization", "type": "string" }, "affiliationType": { "nullable": true, "description": "The type of affiliation from the list: academic, branded, celebrity, government, independent, legacy media, podcast company, new media, not for profit, religious, other, unknown", "type": "string", "enum": [ "academic", "branded", "celebrity", "government", "independent", "legacy media", "podcast company", "new media", "not for profit", "religious", "other", "unknown" ] } }, "additionalProperties": false }, "podcastDirectoryLinks": { "type": "object", "properties": { "amazonmusic": { "type": "string", "format": "uri" }, "anchor": { "type": "string", "format": "uri" }, "antennapod": { "type": "string", "format": "uri" }, "anytimeplayer": { "type": "string", "format": "uri" }, "apollo": { "type": "string", "format": "uri" }, "apple": { "type": "string", "format": "uri" }, "audible": { "type": "string", "format": "uri" }, "breez": { "type": "string", "format": "uri" }, "castamatic": { "type": "string", "format": "uri" }, "castbox": { "type": "string", "format": "uri" }, "castro": { "type": "string", "format": "uri" }, "curiocaster": { "type": "string", "format": "uri" }, "fountain": { "type": "string", "format": "uri" }, "goodpods": { "type": "string", "format": "uri" }, "google": { "type": "string", "format": "uri" }, "gpodder": { "type": "string", "format": "uri" }, "iheartradio": { "type": "string", "format": "uri" }, "listennotes": { "type": "string", "format": "uri" }, "lnbeats": { "type": "string", "format": "uri" }, "moonfm": { "type": "string", "format": "uri" }, "overcast": { "type": "string", "format": "uri" }, "playerfm": { "type": "string", "format": "uri" }, "pocketcasts": { "type": "string", "format": "uri" }, "podbean": { "type": "string", "format": "uri" }, "podcastaddict": { "type": "string", "format": "uri" }, "podcastguru": { "type": "string", "format": "uri" }, "podcastrepublic": { "type": "string", "format": "uri" }, "podchaser": { "type": "string", "format": "uri" }, "podfriend": { "type": "string", "format": "uri" }, "podknife": { "type": "string", "format": "uri" }, "podlp": { "type": "string", "format": "uri" }, "podnews": { "type": "string", "format": "uri" }, "podscan": { "type": "string", "format": "uri" }, "podscribe": { "type": "string", "format": "uri" }, "podstation": { "type": "string", "format": "uri" }, "podurama": { "type": "string", "format": "uri" }, "podverse": { "type": "string", "format": "uri" }, "radiopublic": { "type": "string", "format": "uri" }, "rephonic": { "type": "string", "format": "uri" }, "sonnet": { "type": "string", "format": "uri" }, "spotify": { "type": "string", "format": "uri" }, "stenofm": { "type": "string", "format": "uri" }, "truefans": { "type": "string", "format": "uri" }, "tunein": { "type": "string", "format": "uri" }, "youtubemusic": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "podcastHasGuests": { "nullable": true, "type": "boolean" }, "podcastHasSponsors": { "nullable": true, "type": "boolean" }, "podcastLocations": { "nullable": true, "type": "array", "items": { "type": "string" } }, "primaryContactEmail": { "nullable": true, "type": "string" }, "rssFeedUrl": { "type": "string" }, "socialMediaLinks": { "type": "array", "items": { "type": "object", "properties": { "socialMediaType": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "apple-podcasts", "bright-data-dataset", "google-search", "linktree", "podcast-website", "podchaser", "rephonic", "rss" ] } } }, "required": [ "socialMediaType", "url", "sources" ], "additionalProperties": false } }, "spotifyId": { "nullable": true, "type": "string" }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "nullable": true }, "firstEpisodePublishedAt": { "nullable": true }, "transcriptsCount": { "type": "number" }, "updateFrequency": { "type": "string", "enum": [ "daily", "weekly", "bi-weekly", "monthly", "stale", "very-stale" ] } }, "required": [ "downloadCount", "episodeCount", "latestPublishedAt", "firstEpisodePublishedAt", "transcriptsCount", "updateFrequency" ], "additionalProperties": false }, "titleLatestCleaned": { "nullable": true, "type": "string" }, "transcriptionMode": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "none" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] }, "transcribeSince": { "not": {} } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "episodes-since" ] }, "transcribeSince": {} }, "required": [ "mode", "transcribeSince" ], "additionalProperties": false } ] }, "websiteUrl": { "nullable": true, "type": "string" }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "nullable": true, "type": "object", "properties": { "ageRange": { "type": "string", "enum": [ "Under 18", "18-24", "25-34", "35-44", "45-54", "55+" ], "description": "The age range of the audience as a string." }, "genderSkew": { "type": "string", "enum": [ "Male 0% Female 100%", "Male 20% Female 80%", "Male 40% Female 60%", "Male 50% Female 50%", "Male 60% Female 40%", "Male 80% Female 20%", "Male 100% Female 0%" ], "description": "How the audience is skewed in terms of gender." }, "educationLevel": { "type": "string", "enum": [ "No High School", "High School", "Some College", "Bachelors Degree", "Masters Degree", "Doctorate" ], "description": "The probable education levels of the audience." }, "incomeLevel": { "type": "string", "enum": [ "Under $25K", "$25K-$50K", "$50K-$75K", "$75K-$100K", "$100K-$150K", "$150K-$200K", "$200K+" ], "description": "The probable income levels of the audience." }, "exampleListenerProfile": { "type": "string", "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser." } }, "required": [ "ageRange", "genderSkew", "educationLevel", "incomeLevel", "exampleListenerProfile" ], "additionalProperties": false }, "estimatedMonthlyListeners": { "nullable": true, "type": "number" }, "estimatedMonthyListenersCalculatedAt": { "nullable": true } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "nullable": true, "type": "number" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest", "appleId", "description", "emails", "explicitRss", "hostNames", "ignore", "isClaimed", "podcastAffiliation", "podcastDirectoryLinks", "podcastHasGuests", "podcastHasSponsors", "podcastLocations", "primaryContactEmail", "rssFeedUrl", "socialMediaLinks", "spotifyId", "stats", "titleLatestCleaned", "transcriptionMode", "websiteUrl" ], "additionalProperties": false } }, "required": [ "success", "podcast" ], "additionalProperties": false }, { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "errorCode": { "type": "string", "enum": [ "rss_not_found", "rss_parse_error", "rss_fetch_failed", "update_failed", "unknown_error" ] }, "errorMessage": { "type": "string" }, "errorDetails": { "type": "object", "properties": { "rssUrl": { "type": "string" }, "attemptId": { "type": "number" } }, "additionalProperties": false } }, "required": [ "success", "errorCode", "errorMessage" ], "additionalProperties": false } ] } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Polling #### GET /api/v1/polling/updates **Poll for Updates** Poll for updates across your team. Returns a chronological feed of events (completed requests, new guest appearances, podcasts added to projects, alert matches) since a given timestamp or cursor. Designed for regular polling — use the returned cursor for efficient subsequent calls. ```bash curl -X GET "http://localhost:4000/api/v1/polling/updates?limit=10" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "since": { "description": "ISO 8601 timestamp. Return events after this point. Ignored if cursor is provided. Max lookback: 30 days.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "cursor": { "description": "Opaque cursor from a previous response. Takes precedence over since.", "type": "string" }, "eventTypes": { "description": "Comma-separated list of event types to include: request_completed, guest_appearance, listed_podcast_added, alert_match. Default: all.", "type": "array", "items": { "type": "string", "enum": [ "request_completed", "guest_appearance", "listed_podcast_added", "alert_match" ] } }, "projectId": { "description": "Filter listed_podcast_added events to a specific project.", "type": "string" }, "guestProfileId": { "description": "Filter guest_appearance events to a specific guest profile.", "type": "string" }, "alertConfigId": { "description": "Filter alert_match events to a specific alert configuration.", "type": "string" }, "limit": { "description": "Max events per page (1-100, default 50).", "type": "number", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "options": { "type": "object", "properties": { "since": { "nullable": true, "description": "The resolved since timestamp used for this query.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "cursor": { "nullable": true, "description": "The cursor provided in this request, if any.", "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "request_completed", "guest_appearance", "listed_podcast_added", "alert_match" ] }, "description": "The event types included in this query." }, "limit": { "type": "number", "description": "The maximum number of events per page." }, "projectId": { "nullable": true, "description": "Project filter applied, if any.", "type": "string" }, "guestProfileId": { "nullable": true, "description": "Guest profile filter applied, if any.", "type": "string" }, "alertConfigId": { "nullable": true, "description": "Alert config filter applied, if any.", "type": "string" } }, "required": [ "since", "cursor", "eventTypes", "limit", "projectId", "guestProfileId", "alertConfigId" ], "additionalProperties": false, "description": "The resolved options used for this query." }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this event occurred (ISO 8601)." }, "eventType": { "type": "string", "enum": [ "request_completed" ] }, "data": { "type": "object", "properties": { "requestId": { "type": "string" }, "requestType": { "type": "string", "enum": [ "autoOutreach", "deepAnalysis", "diarization", "guestPrep", "transcription" ] }, "podcastId": { "type": "string" }, "episodeId": { "nullable": true, "type": "string" }, "guestProfileId": { "nullable": true, "type": "string" }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "error": { "nullable": true, "type": "string" } }, "required": [ "requestId", "requestType", "podcastId", "episodeId", "guestProfileId", "completedAt", "error" ], "additionalProperties": false } }, "required": [ "id", "occurredAt", "eventType", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this event occurred (ISO 8601)." }, "eventType": { "type": "string", "enum": [ "guest_appearance" ] }, "data": { "type": "object", "properties": { "guestAppearanceId": { "type": "string" }, "guestProfileId": { "type": "string" }, "episodeId": { "type": "string" }, "aiVerified": { "nullable": true, "type": "boolean" }, "humanVerified": { "nullable": true, "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "guestAppearanceId", "guestProfileId", "episodeId", "aiVerified", "humanVerified", "createdAt" ], "additionalProperties": false } }, "required": [ "id", "occurredAt", "eventType", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this event occurred (ISO 8601)." }, "eventType": { "type": "string", "enum": [ "listed_podcast_added" ] }, "data": { "type": "object", "properties": { "listedPodcastId": { "type": "string" }, "projectId": { "type": "string" }, "podcastId": { "type": "string" }, "status": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "listedPodcastId", "projectId", "podcastId", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "id", "occurredAt", "eventType", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this event occurred (ISO 8601)." }, "eventType": { "type": "string", "enum": [ "alert_match" ] }, "data": { "type": "object", "properties": { "alertMatchId": { "type": "string" }, "alertConfigId": { "type": "string" }, "alertConfigName": { "type": "string" }, "alertType": { "type": "string", "enum": [ "TRANSCRIPT", "EPISODE" ] }, "episodeId": { "type": "string" }, "podcastId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "alertMatchId", "alertConfigId", "alertConfigName", "alertType", "episodeId", "podcastId", "createdAt" ], "additionalProperties": false } }, "required": [ "id", "occurredAt", "eventType", "data" ], "additionalProperties": false } ] } }, "cursor": { "nullable": true, "description": "Pass this value as the cursor query parameter on your next poll. Null if no results.", "type": "string" }, "hasMore": { "type": "boolean", "description": "True if there are more events beyond this page." } }, "required": [ "events", "cursor", "hasMore" ], "additionalProperties": false } }, "required": [ "status", "options", "data" ], "additionalProperties": false } ``` --- ### Projects #### POST /api/v1/projects/:projectSlug/podcasts **Add Podcast to Project** Add a single podcast to a project's list ```bash curl -X POST "http://localhost:4000/api/v1/projects/example-project/podcasts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" } }, "required": [ "projectSlug" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "podcastId": { "type": "string" }, "state": { "default": "prospect", "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "labels": { "type": "array", "items": { "type": "string", "enum": [ "automated", "guest-appearance", "mcp" ] } } }, "required": [ "podcastId", "state" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "listedPodcast": { "type": "object", "properties": { "listedPodcastId": { "type": "string" }, "projectId": { "type": "string" }, "podcast": { "type": "object", "properties": { "podcastId": { "type": "string" }, "titleOriginal": { "type": "string" }, "titleLatest": { "type": "string" }, "slug": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "podcastId", "titleOriginal", "titleLatest", "slug", "imageUrl" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "addedAt": {}, "updatedAt": {}, "addedByUser": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "nullable": true, "type": "string" } }, "required": [ "userId", "email", "displayName" ], "additionalProperties": false }, "activityHistory": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "added-to-list", "update-labels", "update-priority", "update-state" ] }, "activityDate": {}, "fromValue": { "nullable": true, "type": "string" }, "toValue": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "userDisplayName": { "type": "string" } }, "required": [ "actionType", "activityDate", "fromValue", "toValue", "userId", "userDisplayName" ], "additionalProperties": false } }, "analysis": { "type": "object", "properties": { "relevancyScore": { "nullable": true, "type": "number" }, "deepRelevancyScore": { "nullable": true, "type": "number" }, "hostRelevancyScore": { "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "listedPodcastId", "projectId", "podcast", "status", "priority", "labels", "addedAt", "updatedAt", "addedByUser", "activityHistory", "analysis" ], "additionalProperties": false } }, "required": [ "listedPodcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/projects/:projectSlug/details **Get Project Details** Get detailed information about a specific project including metadata and statistics ```bash curl -X GET "http://localhost:4000/api/v1/projects/example-project/details" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" } }, "required": [ "projectSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "project": { "type": "object", "properties": { "projectId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "lastUpdated": {}, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false }, "projectTypes": { "type": "array", "items": { "type": "string", "enum": [ "advertisers", "api", "content-creation", "guest-booking", "interesting-podcasts", "lead-generation", "monitoring", "other", "transcriptions" ] } }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "ARCHIVED", "ERROR" ] }, "listedPodcastsCount": { "type": "number" }, "linkedGuestProfile": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "nullable": true, "type": "string" }, "linkedinUrl": { "nullable": true, "type": "string" }, "appearancesCount": { "type": "number" } }, "required": [ "id", "name", "slug", "status", "imageUrl", "linkedinUrl", "appearancesCount" ], "additionalProperties": false }, "stateCounts": { "type": "object", "properties": { "prospect": { "type": "number" }, "qualified": { "type": "number" }, "pitched": { "type": "number" }, "booked": { "type": "number" }, "lost": { "type": "number" }, "ignored": { "type": "number" } }, "required": [ "prospect", "qualified", "pitched", "booked", "lost", "ignored" ], "additionalProperties": false }, "documentsCount": { "type": "object", "properties": { "total": { "type": "number" }, "processed": { "type": "number" } }, "required": [ "total", "processed" ], "additionalProperties": false }, "recentActivities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added-to-list", "update-labels", "update-priority", "update-state" ] }, "date": {}, "podcastTitle": { "nullable": true, "type": "string" }, "podcastSlug": { "nullable": true, "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "toValue": { "nullable": true, "type": "string" }, "user": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false } }, "required": [ "type", "date", "podcastTitle", "podcastSlug", "podcastImageUrl", "toValue", "user" ], "additionalProperties": false } }, "projectTypeOtherReason": { "nullable": true, "type": "string" }, "projectPurpose": { "nullable": true, "type": "string" }, "projectKeywords": { "type": "array", "items": { "type": "string" } }, "publicTitle": { "nullable": true, "type": "string" }, "publicDescription": { "nullable": true, "type": "string" }, "publicSlug": { "nullable": true, "type": "string" }, "isPublicListicle": { "type": "boolean" }, "publicPodcastLimit": { "type": "number" }, "isPublicForTeam": { "type": "boolean" }, "goHighLevelIntegration": { "nullable": true, "type": "object", "properties": { "locationId": { "type": "string" }, "hasApiKey": { "type": "boolean" }, "enabled": { "type": "boolean" }, "onlyPushRelevantPodcasts": { "type": "boolean" } }, "required": [ "locationId", "hasApiKey", "enabled", "onlyPushRelevantPodcasts" ], "additionalProperties": false } }, "required": [ "projectId", "name", "slug", "teamId", "createdAt", "lastUpdated", "createdBy", "projectTypes", "status", "listedPodcastsCount", "linkedGuestProfile", "stateCounts", "documentsCount", "recentActivities", "projectTypeOtherReason", "projectPurpose", "projectKeywords", "publicTitle", "publicDescription", "publicSlug", "isPublicListicle", "publicPodcastLimit", "isPublicForTeam", "goHighLevelIntegration" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/projects/:projectSlug/strategies **Get Project Strategies** Get all strategies associated with a project ```bash curl -X GET "http://localhost:4000/api/v1/projects/example-project/strategies" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" } }, "required": [ "projectSlug" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "strategies": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "shortDescription": { "type": "string" }, "strategyBlurb": { "type": "string" }, "audiencePersonaTarget": { "type": "string" }, "whyItsEffective": { "type": "string" }, "strategyTrainingDocumentation": { "type": "string" }, "keywordInspiration": { "type": "array", "items": { "type": "string" } }, "exampleGoogleSearches": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "createdAt": {}, "updatedAt": {}, "strategyApproach": { "nullable": true, "type": "string", "enum": [ "straightforward", "unconventional", "longshot" ] }, "strategyFocus": { "nullable": true, "type": "string" }, "priority": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "autoSearchEnabled": { "type": "boolean" } }, "required": [ "title", "shortDescription", "strategyBlurb", "audiencePersonaTarget", "whyItsEffective", "strategyTrainingDocumentation", "keywordInspiration", "exampleGoogleSearches", "id", "createdAt", "updatedAt", "strategyApproach", "strategyFocus", "priority", "autoSearchEnabled" ], "additionalProperties": false } } }, "required": [ "strategies" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/projects **Get Projects** Get a list of projects for the authenticated user ```bash curl -X GET "http://localhost:4000/api/v1/projects?states=ACTIVE" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "states": {}, "sortBy": { "type": "string", "enum": [ "recent-activity", "name", "created" ] } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "options": { "type": "object", "properties": { "states": {}, "sortBy": { "type": "string", "enum": [ "recent-activity", "name", "created" ] } }, "additionalProperties": false }, "projects": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "lastUpdated": {}, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false }, "projectTypes": { "type": "array", "items": { "type": "string", "enum": [ "advertisers", "api", "content-creation", "guest-booking", "interesting-podcasts", "lead-generation", "monitoring", "other", "transcriptions" ] } }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "ARCHIVED", "ERROR" ] }, "listedPodcastsCount": { "type": "number" }, "linkedGuestProfile": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "nullable": true, "type": "string" }, "linkedinUrl": { "nullable": true, "type": "string" }, "appearancesCount": { "type": "number" } }, "required": [ "id", "name", "slug", "status", "imageUrl", "linkedinUrl", "appearancesCount" ], "additionalProperties": false }, "stateCounts": { "type": "object", "properties": { "prospect": { "type": "number" }, "qualified": { "type": "number" }, "pitched": { "type": "number" }, "booked": { "type": "number" }, "lost": { "type": "number" }, "ignored": { "type": "number" } }, "required": [ "prospect", "qualified", "pitched", "booked", "lost", "ignored" ], "additionalProperties": false }, "documentsCount": { "type": "object", "properties": { "total": { "type": "number" }, "processed": { "type": "number" } }, "required": [ "total", "processed" ], "additionalProperties": false }, "recentActivities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added-to-list", "update-labels", "update-priority", "update-state" ] }, "date": {}, "podcastTitle": { "nullable": true, "type": "string" }, "podcastSlug": { "nullable": true, "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "toValue": { "nullable": true, "type": "string" }, "user": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false } }, "required": [ "type", "date", "podcastTitle", "podcastSlug", "podcastImageUrl", "toValue", "user" ], "additionalProperties": false } } }, "required": [ "projectId", "name", "slug", "teamId", "createdAt", "lastUpdated", "createdBy", "projectTypes", "status", "listedPodcastsCount", "linkedGuestProfile", "stateCounts", "documentsCount", "recentActivities" ], "additionalProperties": false } } }, "required": [ "options", "projects" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### DELETE /api/v1/projects/:projectSlug/podcasts/:listedPodcastId **Remove Podcast on Project** Remove a podcast from a project's list ```bash curl -X DELETE "http://localhost:4000/api/v1/projects/example-project/podcasts/123" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" }, "listedPodcastId": { "type": "string" } }, "required": [ "projectSlug", "listedPodcastId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "projectSlug": { "type": "string" }, "listedPodcastId": { "type": "string" } }, "required": [ "projectSlug", "listedPodcastId" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PATCH /api/v1/projects/:projectSlug/podcasts/:listedPodcastId **Update Podcast on Project** Update the details or status of a podcast within a project ```bash curl -X PATCH "http://localhost:4000/api/v1/projects/example-project/podcasts/123" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" }, "listedPodcastId": { "type": "string" } }, "required": [ "projectSlug", "listedPodcastId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "state": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "projectSlug": { "type": "string" }, "listedPodcastId": { "type": "string" }, "options": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } }, "additionalProperties": false }, "updatedListedPodcast": { "type": "object", "properties": { "listedPodcastId": { "type": "string" }, "projectId": { "type": "string" }, "podcast": { "type": "object", "properties": { "podcastId": { "type": "string" }, "titleOriginal": { "type": "string" }, "titleLatest": { "type": "string" }, "slug": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" } }, "required": [ "podcastId", "titleOriginal", "titleLatest", "slug", "imageUrl" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "addedAt": {}, "updatedAt": {}, "addedByUser": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "nullable": true, "type": "string" } }, "required": [ "userId", "email", "displayName" ], "additionalProperties": false }, "activityHistory": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "added-to-list", "update-labels", "update-priority", "update-state" ] }, "activityDate": {}, "fromValue": { "nullable": true, "type": "string" }, "toValue": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "userDisplayName": { "type": "string" } }, "required": [ "actionType", "activityDate", "fromValue", "toValue", "userId", "userDisplayName" ], "additionalProperties": false } }, "analysis": { "type": "object", "properties": { "relevancyScore": { "nullable": true, "type": "number" }, "deepRelevancyScore": { "nullable": true, "type": "number" }, "hostRelevancyScore": { "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "listedPodcastId", "projectId", "podcast", "status", "priority", "labels", "addedAt", "updatedAt", "addedByUser", "activityHistory", "analysis" ], "additionalProperties": false } }, "required": [ "projectSlug", "listedPodcastId", "options", "updatedListedPodcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### PATCH /api/v1/projects/:projectSlug **Update Project** Update an existing project's details ```bash curl -X PATCH "http://localhost:4000/api/v1/projects/example-project" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "projectSlug": { "type": "string" } }, "required": [ "projectSlug" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "state": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "ARCHIVED", "ERROR" ] }, "projectPurpose": { "nullable": true, "type": "string" }, "projectKeywords": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "project": { "type": "object", "properties": { "projectId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "teamId": { "type": "string" }, "createdAt": {}, "lastUpdated": {}, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false }, "projectTypes": { "type": "array", "items": { "type": "string", "enum": [ "advertisers", "api", "content-creation", "guest-booking", "interesting-podcasts", "lead-generation", "monitoring", "other", "transcriptions" ] } }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "ARCHIVED", "ERROR" ] }, "listedPodcastsCount": { "type": "number" }, "linkedGuestProfile": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "nullable": true, "type": "string" }, "linkedinUrl": { "nullable": true, "type": "string" }, "appearancesCount": { "type": "number" } }, "required": [ "id", "name", "slug", "status", "imageUrl", "linkedinUrl", "appearancesCount" ], "additionalProperties": false }, "stateCounts": { "type": "object", "properties": { "prospect": { "type": "number" }, "qualified": { "type": "number" }, "pitched": { "type": "number" }, "booked": { "type": "number" }, "lost": { "type": "number" }, "ignored": { "type": "number" } }, "required": [ "prospect", "qualified", "pitched", "booked", "lost", "ignored" ], "additionalProperties": false }, "documentsCount": { "type": "object", "properties": { "total": { "type": "number" }, "processed": { "type": "number" } }, "required": [ "total", "processed" ], "additionalProperties": false }, "recentActivities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "added-to-list", "update-labels", "update-priority", "update-state" ] }, "date": {}, "podcastTitle": { "nullable": true, "type": "string" }, "podcastSlug": { "nullable": true, "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "toValue": { "nullable": true, "type": "string" }, "user": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "avatarSeed": { "nullable": true, "type": "string" } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false } }, "required": [ "type", "date", "podcastTitle", "podcastSlug", "podcastImageUrl", "toValue", "user" ], "additionalProperties": false } } }, "required": [ "projectId", "name", "slug", "teamId", "createdAt", "lastUpdated", "createdBy", "projectTypes", "status", "listedPodcastsCount", "linkedGuestProfile", "stateCounts", "documentsCount", "recentActivities" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Search #### POST /api/v1/search/episodes **Search Episodes** Search for episodes by title, description, or transcript text ```bash curl -X POST "http://localhost:4000/api/v1/search/episodes" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "searchTerms": [ { "searchTargets": [ "podcast-title" ], "searchTerm": "This Week In Startups", "searchType": "text", "searchTermOptions": { "phraseMatch": true, "matchMode": "must" } }, { "searchTargets": [ "transcript" ], "searchTerm": "podcast", "searchType": "text", "searchTermOptions": { "matchMode": "optional" } } ], "languages": [ "en" ], "lastEpisodeDateSince": "2026-05-12T22:56:23.652Z", "sortOrder": [ { "field": "recentActivity", "direction": "desc" } ] }' ``` **Request body schema:** ```json { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description", "episode-title", "episode-description", "transcript" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } }, "includeTranscriptSnippet": { "type": "boolean" }, "transcriptSnippetLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "transcriptHighlightLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "includeEpisodeIds": { "type": "array", "items": { "type": "string" } }, "publishedSince": {}, "hasTranscript": { "type": "boolean" }, "episodeUpdatedSince": {}, "episodeCreatedSince": {} }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "searchMode": { "type": "string", "enum": [ "episodes" ] }, "searchId": { "type": "string" }, "searchOptions": { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description", "episode-title", "episode-description", "transcript" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } }, "includeTranscriptSnippet": { "type": "boolean" }, "transcriptSnippetLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "transcriptHighlightLength": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "includeEpisodeIds": { "type": "array", "items": { "type": "string" } }, "publishedSince": {}, "hasTranscript": { "type": "boolean" }, "episodeUpdatedSince": {}, "episodeCreatedSince": {} }, "additionalProperties": false }, "seachResultsStats": { "type": "object", "properties": { "time": { "type": "object", "properties": { "totalTimeTakenMs": { "type": "number" }, "totalSearchTimeMs": { "type": "number" }, "totalPostProcessingTimeMs": { "type": "number" } }, "required": [ "totalTimeTakenMs", "totalSearchTimeMs", "totalPostProcessingTimeMs" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "blacklistedPodcasts": { "type": "number" }, "projectExcludedPodcasts": { "type": "number" }, "totalResultsAvailable": { "type": "number" }, "resultsProcessed": { "type": "number" }, "resultsFiltered": { "type": "number" }, "resultsReturned": { "type": "number" } }, "required": [ "blacklistedPodcasts", "projectExcludedPodcasts", "totalResultsAvailable", "resultsProcessed", "resultsFiltered", "resultsReturned" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "relevancyScoresTotals": { "type": "object", "additionalProperties": { "type": "number" }, "required": [ "1", "2", "3", "4", "5" ] }, "projectPodcastRelevancyScores": { "description": "If includePodcastRelevancy is true this will be included with 1 record for each unique podcast in the results", "type": "object", "additionalProperties": { "nullable": true, "description": "The project podcast relevancy. If null means something went wrong calculating it.", "type": "object", "properties": { "answer": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "justification": { "type": "string" }, "strengths": {}, "concerns": {} }, "required": [ "rating", "justification", "strengths", "concerns" ], "additionalProperties": false } }, "required": [ "answer" ], "additionalProperties": false } } }, "required": [ "relevancyScoresTotals" ], "additionalProperties": false } }, "required": [ "time", "totals", "filters" ], "additionalProperties": false }, "result": {}, "cursor": { "nullable": true, "type": "string" } }, "required": [ "searchMode", "searchId", "searchOptions", "seachResultsStats", "result", "cursor" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### POST /api/v1/search/podcasts **Search Podcasts** Search for podcasts by title, description, or RSS feed URL ```bash curl -X POST "http://localhost:4000/api/v1/search/podcasts" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "searchTerms": [ { "searchTargets": [ "podcast-title", "podcast-title" ], "searchTerm": "podcast creation", "searchType": "text", "searchTermOptions": { "matchMode": "must", "phraseMatch": true, "slop": 1 } } ], "languages": [ "en" ], "lastEpisodeDateSince": "2026-05-12", "sortOrder": [ { "field": "recentActivity", "direction": "desc" } ] }' ``` **Request body schema:** ```json { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "description": "Terms to search for in podcast title and description", "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "searchMode": { "type": "string", "enum": [ "podcasts" ] }, "searchId": { "type": "string" }, "searchOptions": { "type": "object", "properties": { "cursor": { "nullable": true, "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).", "type": "string" }, "pageSize": { "description": "Number of results to return per page", "type": "integer", "minimum": 1, "maximum": 1000 }, "project": { "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.", "type": "object", "properties": { "projectId": { "type": "string", "description": "The Pod Engine Project ID" }, "excludeIgnoredPodcasts": { "description": "If true, will not include any podcasts marked as ignored on this project in the results.", "type": "boolean" }, "excludePodcastsOnList": { "description": "If true, will not include any podcasts on the project list in the results.", "type": "boolean" }, "includePodcastRelevancy": { "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response", "type": "boolean" }, "excludeRelvancyValues": { "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.", "type": "array", "items": { "type": "number", "minimum": 1, "maximum": 5 } }, "forceRecalculateRelevancy": { "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.", "type": "boolean" } }, "required": [ "projectId" ], "additionalProperties": false }, "projectId": { "description": "[DEPRECATED] Project ID to associate the search with", "type": "string" }, "searchTerms": { "description": "Terms to search for in podcast title and description", "type": "array", "items": { "type": "object", "properties": { "searchTerm": { "type": "string", "minLength": 2 }, "searchType": { "type": "string", "enum": [ "text", "embeddings" ] }, "searchTargets": { "type": "array", "items": { "type": "string", "enum": [ "podcast-title", "podcast-description" ] } }, "searchTermOptions": { "default": { "matchMode": "optional", "phraseMatch": false, "fuzzy": false }, "type": "object", "properties": { "matchMode": { "default": "optional", "type": "string", "enum": [ "must", "not", "optional" ] }, "phraseMatch": { "description": "Whether to match the search term as a phrase", "type": "boolean" }, "slop": { "description": "How many words apart tokens can appear in a document to be considered a match", "type": "number" }, "fuzzy": { "description": "Whether to use fuzzy matching", "type": "boolean" } }, "required": [ "matchMode" ], "additionalProperties": false } }, "required": [ "searchTerm", "searchType", "searchTargets", "searchTermOptions" ], "additionalProperties": false } }, "excludeItunesGenres": { "description": "iTunes genres to exclude from results", "type": "array", "items": { "type": "string" } }, "excludePodcastIds": { "description": "Specific podcast IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "excludeEpisodeIds": { "description": "Specific episode IDs to exclude from results", "type": "array", "items": { "type": "string" } }, "explicit": { "description": "Filter by explicit content rating", "type": "string", "enum": [ "clean", "explicit" ] }, "foundedSince": { "description": "Filter podcasts founded after this date" }, "hasPrimaryContact": { "description": "Filter podcasts that have primary contact information", "type": "boolean" }, "hasSocials": { "description": "Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube", "type": "array", "items": { "type": "string", "enum": [ "beehiiv", "behance", "bluesky", "discord", "facebook", "github", "instagram", "linkedin", "linktree", "mastodon", "medium", "patreon", "pinterest", "reddit", "snapchat", "soundcloud", "substack", "threads", "tiktok", "tumblr", "twitch", "twitter", "vimeo", "whatsapp", "youtube" ] } }, "includeItunesGenres": { "description": "iTunes genres to include in results", "type": "array", "items": { "type": "string" } }, "includePodcastIds": { "description": "Specific podcast IDs to include in results", "type": "array", "items": { "type": "string" } }, "languages": { "description": "Filter podcasts by language", "type": "array", "items": { "type": "string" } }, "lastEpisodeDateSince": { "description": "Filter podcasts with episodes published after this date" }, "maxTotalEpisodes": { "description": "Maximum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxPlays": { "description": "Minimum number of Castbox plays", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minCastboxSubscribers": { "description": "Minimum number of Castbox subscribers", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minItunesRating": { "description": "Minimum iTunes rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minItunesRatingCount": { "description": "Minimum number of iTunes ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minSpotifyRating": { "description": "Minimum Spotify rating score", "type": "number", "minimum": 0, "maximum": 5 }, "minSpotifyRatingCount": { "description": "Minimum number of Spotify ratings", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minTotalEpisodes": { "description": "Minimum number of total episodes", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "podcastCountries": { "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us", "type": "array", "items": { "type": "string" } }, "podcastHasGuests": { "description": "Filter podcasts that feature guests", "type": "boolean" }, "podcastAuthorityScore": { "description": "Filter podcasts by their Authority Score", "type": "object", "properties": { "authorityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 }, "max": { "nullable": true, "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false } }, "additionalProperties": false }, "sortOrder": { "description": "Specify how results should be sorted", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "relevance", "recentActivity", "title", "appleReviews", "spotifyReviews" ] }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "nullOrder": { "type": "string", "enum": [ "first", "last" ] } }, "required": [ "field" ], "additionalProperties": false } } }, "additionalProperties": false }, "seachResultsStats": { "type": "object", "properties": { "time": { "type": "object", "properties": { "totalTimeTakenMs": { "type": "number" }, "totalSearchTimeMs": { "type": "number" }, "totalPostProcessingTimeMs": { "type": "number" } }, "required": [ "totalTimeTakenMs", "totalSearchTimeMs", "totalPostProcessingTimeMs" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "blacklistedPodcasts": { "type": "number" }, "projectExcludedPodcasts": { "type": "number" }, "totalResultsAvailable": { "type": "number" }, "resultsProcessed": { "type": "number" }, "resultsFiltered": { "type": "number" }, "resultsReturned": { "type": "number" } }, "required": [ "blacklistedPodcasts", "projectExcludedPodcasts", "totalResultsAvailable", "resultsProcessed", "resultsFiltered", "resultsReturned" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "relevancyScoresTotals": { "type": "object", "additionalProperties": { "type": "number" }, "required": [ "1", "2", "3", "4", "5" ] }, "projectPodcastRelevancyScores": { "description": "If includePodcastRelevancy is true this will be included with 1 record for each unique podcast in the results", "type": "object", "additionalProperties": { "nullable": true, "description": "The project podcast relevancy. If null means something went wrong calculating it.", "type": "object", "properties": { "answer": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "justification": { "type": "string" }, "strengths": {}, "concerns": {} }, "required": [ "rating", "justification", "strengths", "concerns" ], "additionalProperties": false } }, "required": [ "answer" ], "additionalProperties": false } } }, "required": [ "relevancyScoresTotals" ], "additionalProperties": false } }, "required": [ "time", "totals", "filters" ], "additionalProperties": false }, "result": {}, "cursor": { "nullable": true, "type": "string" } }, "required": [ "searchMode", "searchId", "searchOptions", "seachResultsStats", "result", "cursor" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Stats #### GET /api/v1/rss/stats/public/podcast2 (PUBLIC) **Podcast 2 Stats** We track the number of podcasts that have implemented podcast2 rss fields and the number of episodes that have transcripts ```bash curl -X GET "http://localhost:4000/api/v1/rss/stats/public/podcast2" \ -H "Content-Type: application/json" ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast2Stats": { "type": "object", "properties": { "podcastLevelStats": { "type": "object", "properties": { "totalRssFeeds": { "type": "number" }, "fieldFrequency": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "frequency": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "field", "frequency", "percentage" ], "additionalProperties": false } } }, "required": [ "totalRssFeeds", "fieldFrequency" ], "additionalProperties": false }, "episodeLevelStats": { "type": "object", "properties": { "totalRssFeeds": { "type": "number" }, "fieldFrequency": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "frequency": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "field", "frequency", "percentage" ], "additionalProperties": false } } }, "required": [ "totalRssFeeds", "fieldFrequency" ], "additionalProperties": false }, "topPodcast2Podcasts": { "type": "array", "items": { "type": "object", "properties": { "podcastId": { "type": "string" }, "host": { "type": "string" }, "podcastSlug": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "rssFeedUrl": { "type": "string" }, "numPodcast20Fields": { "type": "number" }, "implementedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "podcastId", "host", "podcastSlug", "podcastImageUrl", "rssFeedUrl", "numPodcast20Fields", "implementedFields" ], "additionalProperties": false } }, "topHosts": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "totalPodcasts": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "host", "totalPodcasts", "percentage" ], "additionalProperties": false } }, "topHostsWithPodcast2Transcripts": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "totalPodcasts": { "type": "number" }, "numPodcastsWithTranscripts": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "host", "totalPodcasts", "numPodcastsWithTranscripts", "percentage" ], "additionalProperties": false } }, "topHostsWithPodcast2Stats": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "totalPodcasts": { "type": "number" }, "averageNumPodcast2Fields": { "type": "number" } }, "required": [ "host", "totalPodcasts", "averageNumPodcast2Fields" ], "additionalProperties": false } } }, "required": [ "podcastLevelStats", "episodeLevelStats", "topPodcast2Podcasts", "topHosts", "topHostsWithPodcast2Transcripts", "topHostsWithPodcast2Stats" ], "additionalProperties": false } }, "required": [ "podcast2Stats" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Teams #### PUT /api/v1/teams/podcasts/:podcastId **Add Podcast to Team** Add a podcast to your team ```bash curl -X PUT "http://localhost:4000/api/v1/teams/podcasts/58bb043a-ad45-4844-a6d8-7492d901dc30" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "sync": false, "blacklist": false }' ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Podengine ID" } }, "required": [ "podcastId" ], "additionalProperties": false } ``` **Request body schema:** ```json { "type": "object", "properties": { "sync": { "nullable": true, "type": "boolean" }, "blacklist": { "nullable": true, "type": "boolean" } }, "required": [ "sync", "blacklist" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "teamPodcast": { "type": "object", "properties": { "addedByUserId": { "nullable": true, "type": "string" }, "addedReason": { "type": "string", "enum": [ "add-to-team-podcasts-button", "listed-podcast", "migration", "script", "search-export" ] }, "blacklist": { "type": "boolean" }, "createdAt": {}, "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "podcastId": { "type": "string" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string" }, "addedByUserId": { "type": "string" }, "listedPodcastState": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] } }, "required": [ "projectId", "addedByUserId", "listedPodcastState" ], "additionalProperties": false } }, "sync": { "type": "boolean" }, "teamId": { "type": "string" }, "lastAirtableSync": {}, "lastAirtableErrorSyncDate": {}, "airtableRecordId": { "type": "string" } }, "required": [ "addedByUserId", "addedReason", "blacklist", "createdAt", "podcast", "podcastId", "projects", "sync", "teamId" ], "additionalProperties": false } }, "required": [ "teamPodcast" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/podcasts **Get Team Podcasts** Get all podcasts associated with your team ```bash curl -X GET "http://localhost:4000/api/v1/teams/podcasts?limit=10&offset=0" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "blacklist": { "type": "boolean" }, "sync": { "type": "boolean" }, "hasAirtableError": { "type": "boolean" }, "limit": { "default": 100, "type": "number", "maximum": 100 }, "offset": { "default": 0, "type": "number" }, "textFilter": { "description": "Can be a partial podcast title, apple id, apple podcast url, or airtable record id", "type": "string" }, "sortOrder": { "type": "string", "enum": [ "podcastTitle", "addedAt", "lastAirtableSync" ] } }, "required": [ "limit", "offset" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "total": { "type": "number" }, "totalFiltered": { "type": "number" }, "teamPodcasts": { "type": "array", "items": { "type": "object", "properties": { "addedByUserId": { "nullable": true, "type": "string" }, "addedReason": { "type": "string", "enum": [ "add-to-team-podcasts-button", "listed-podcast", "migration", "script", "search-export" ] }, "blacklist": { "type": "boolean" }, "createdAt": {}, "podcast": { "type": "object", "properties": { "author": { "nullable": true, "type": "string" }, "authorityScore": { "nullable": true, "type": "object", "properties": { "calculatedAt": {}, "authorityScore": { "type": "number", "description": "This is the weighted total authority score of the podcast, out of 100" }, "qualityScore": { "type": "number", "description": "This is the quality score of the podcast, out of 100" }, "youtubeScore": { "type": "number", "description": "This is the YouTube score of the podcast, out of 100" }, "socialScore": { "type": "number", "description": "This is the social score of the podcast, out of 100" }, "engagementScore": { "type": "number", "description": "This is the engagement score of the podcast, out of 100" } }, "required": [ "calculatedAt", "authorityScore", "qualityScore", "youtubeScore", "socialScore", "engagementScore" ], "additionalProperties": false }, "genres": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "imageUrl": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "lastEpisodePublishedAt": {}, "slug": { "type": "string" }, "title": { "type": "string" }, "titleLatest": { "type": "string" } }, "required": [ "author", "authorityScore", "genres", "id", "imageUrl", "language", "lastEpisodePublishedAt", "slug", "title", "titleLatest" ], "additionalProperties": false }, "podcastId": { "type": "string" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string" }, "addedByUserId": { "type": "string" }, "listedPodcastState": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] } }, "required": [ "projectId", "addedByUserId", "listedPodcastState" ], "additionalProperties": false } }, "sync": { "type": "boolean" }, "teamId": { "type": "string" }, "lastAirtableSync": {}, "lastAirtableErrorSyncDate": {}, "airtableRecordId": { "type": "string" } }, "required": [ "addedByUserId", "addedReason", "blacklist", "createdAt", "podcast", "podcastId", "projects", "sync", "teamId" ], "additionalProperties": false } } }, "required": [ "total", "totalFiltered", "teamPodcasts" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### DELETE /api/v1/teams/podcasts/multiple **Remove Multiple Podcasts from Team** Remove multiple podcasts from your team by PodEngine IDs or Apple IDs ```bash curl -X DELETE "http://localhost:4000/api/v1/teams/podcasts/multiple" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Request body schema:** ```json { "type": "object", "properties": { "podcastIds": { "type": "array", "items": { "type": "string" } }, "appleIds": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } } }, "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "notFoundAppleIds": { "type": "array", "items": { "type": "number" } }, "errors": { "type": "number" }, "removedPodcasts": { "type": "number" }, "notOnList": { "default": 0, "type": "number" } }, "required": [ "notFoundAppleIds", "errors", "removedPodcasts", "notOnList" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### DELETE /api/v1/teams/podcasts/:podcastId **Remove Podcast from Team** Remove a podcast from your team ```bash curl -X DELETE "http://localhost:4000/api/v1/teams/podcasts/58bb043a-ad45-4844-a6d8-7492d901dc30" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Podengine ID" } }, "required": [ "podcastId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/request-history **Request History** Get team request history ```bash curl -X GET "http://localhost:4000/api/v1/teams/request-history?limit=10&skip=0&filterCompleted=false&requestType=transcription" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "limit": { "type": "number", "maximum": 50 }, "skip": { "type": "number" }, "filterCompleted": { "type": "boolean" }, "requestType": { "type": "string", "enum": [ "autoOutreach", "deepAnalysis", "diarization", "guestPrep", "transcription" ] } }, "required": [ "limit", "requestType" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalRequests": { "type": "number" }, "requests": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "transcription", "deepAnalysis", "diarization" ] }, "episodeId": { "type": "string" }, "episodeTitle": { "nullable": true, "type": "string" }, "episodeImageUrl": { "nullable": true, "type": "string" }, "episodeSlug": { "type": "string" } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "guestPrep" ] }, "episodeId": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeTitle": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeImageUrl": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeSlug": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "autoOutreach" ] }, "episodeId": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeTitle": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeImageUrl": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeSlug": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false } ] } } }, "required": [ "totalRequests", "requests" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Transcriptions #### GET /api/v1/episodes/:episodeId/transcription-request **Request Episode Transcription** Request an episode to be transcribed. This typically takes 1-2 hours and you can check progress using the Requests History endpoint. ```bash curl -X GET "http://localhost:4000/api/v1/episodes/cbd08a7c-b936-4ee8-87d1-12df08da1c9f/transcription-request" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "episodeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "episodeId" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/podcasts/:podcastId/transcription-request **Request Podcast Transcription** Request multiple episodes for a Podcast to be transcribed and optionally the future Podcast episodes to be transcribed automatically. ```bash curl -X GET "http://localhost:4000/api/v1/podcasts/:podcastId/transcription-request?type=since&requestFutureEpisodes=false" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Path parameters schema:** ```json { "type": "object", "properties": { "podcastId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Podengine ID" } }, "required": [ "podcastId" ], "additionalProperties": false } ``` **Query schema:** ```json { "type": "object", "properties": { "type": { "type": "string", "enum": [ "since", "latest", "recent" ] }, "requestFutureEpisodes": { "default": false, "description": "If true, future episodes will be transcribed automatically.", "type": "boolean" } }, "required": [ "type", "requestFutureEpisodes" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "episodeIds": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the episodes that were requested." } }, "required": [ "message", "episodeIds" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/transcriptions **Transcription Requests** Get transcription request history for your team ```bash curl -X GET "http://localhost:4000/api/v1/teams/transcriptions?limit=10&filterCompleted=false" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "limit": { "type": "number", "maximum": 50 }, "skip": { "type": "number" }, "filterCompleted": { "type": "boolean" } }, "required": [ "limit" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalRequests": { "type": "number" }, "requests": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "transcription", "deepAnalysis", "diarization" ] }, "episodeId": { "type": "string" }, "episodeTitle": { "nullable": true, "type": "string" }, "episodeImageUrl": { "nullable": true, "type": "string" }, "episodeSlug": { "type": "string" } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "guestPrep" ] }, "episodeId": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeTitle": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeImageUrl": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeSlug": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "nullable": true, "type": "string" }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true }, "requestType": { "type": "string", "enum": [ "autoOutreach" ] }, "episodeId": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeTitle": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeImageUrl": { "type": "string", "nullable": true, "enum": [ null ] }, "episodeSlug": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false } ] } } }, "required": [ "totalRequests", "requests" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ### Usage #### GET /api/v1/teams/usage/current **Current Month Usage** Get your team's current month API usage and limits for each usage category, along with enabled feature flags and plan information. ```bash curl -X GET "http://localhost:4000/api/v1/teams/usage/current" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Current month in YYYY-MM format" }, "plan": { "type": "string", "description": "Current team plan tier" }, "featureFlags": { "type": "object", "properties": { "s3Integration": { "type": "boolean" }, "airtableIntegration": { "type": "boolean" }, "automatedSearch": { "type": "boolean" }, "applyPage": { "type": "boolean" }, "goHighLevelIntegration": { "type": "boolean" } }, "additionalProperties": false, "description": "Enabled feature flags for the team" }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "enum": [ "deepResearchRequests", "diarizationRequests", "episodeLookups", "exportCount", "podcastLookups", "searchCount", "transcriptDownloadCount", "transcriptionRequests" ], "description": "The usage category identifier" }, "label": { "type": "string", "description": "Human-readable label for this usage category" }, "used": { "type": "number", "minimum": 0, "description": "Number of requests used this month" }, "limit": { "nullable": true, "description": "Monthly limit (null = unlimited, 0 = disabled)", "type": "number", "minimum": 0 } }, "required": [ "alias", "label", "used", "limit" ], "additionalProperties": false }, "description": "Usage breakdown per category" }, "totalUsed": { "type": "number", "description": "Total requests used across all categories this month" }, "projectUsage": { "description": "Monthly active project and guest profile usage", "type": "object", "properties": { "projects": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "nullable": true, "type": "number" } }, "required": [ "used", "limit" ], "additionalProperties": false }, "guestProfiles": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "nullable": true, "type": "number" } }, "required": [ "used", "limit" ], "additionalProperties": false } }, "required": [ "projects", "guestProfiles" ], "additionalProperties": false } }, "required": [ "month", "plan", "featureFlags", "aliases", "totalUsed" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/usage/daily **Daily Usage Trend** Get daily usage breakdown for your team over a time window (7, 30, or 90 days), with limit thresholds for comparison. ```bash curl -X GET "http://localhost:4000/api/v1/teams/usage/daily" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "window": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ], "description": "Time window for usage data" } }, "required": [ "window" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date in YYYY-MM-DD format" }, "totalUsage": { "type": "number", "minimum": 0, "description": "Total requests on this day" }, "usageByAlias": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Usage count per alias for this day" } }, "required": [ "date", "totalUsage", "usageByAlias" ], "additionalProperties": false }, "description": "Daily usage entries sorted by date ascending" }, "limits": { "type": "object", "additionalProperties": { "nullable": true, "type": "number", "minimum": 0 }, "required": [ "deepResearchRequests", "diarizationRequests", "episodeLookups", "exportCount", "podcastLookups", "searchCount", "transcriptDownloadCount", "transcriptionRequests" ], "description": "Current monthly limits per alias" } }, "required": [ "days", "limits" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/usage/monthly **Monthly Usage History** Get monthly usage history for your team over the past N months. ```bash curl -X GET "http://localhost:4000/api/v1/teams/usage/monthly" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "months": { "default": 6, "description": "Number of months of history to return", "type": "number", "minimum": 1, "maximum": 24 } }, "required": [ "months" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "Month in YYYY-MM format" }, "totalUsage": { "type": "number", "minimum": 0, "description": "Total requests in this month" }, "usageByAlias": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Usage count per alias for this month" } }, "required": [ "month", "totalUsage", "usageByAlias" ], "additionalProperties": false }, "description": "Monthly usage entries sorted by month ascending" }, "limits": { "type": "object", "additionalProperties": { "nullable": true, "type": "number", "minimum": 0 }, "required": [ "deepResearchRequests", "diarizationRequests", "episodeLookups", "exportCount", "podcastLookups", "searchCount", "transcriptDownloadCount", "transcriptionRequests" ], "description": "Current monthly limits per alias" } }, "required": [ "months", "limits" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- #### GET /api/v1/teams/usage/members **Team Member Usage** Get usage breakdown by team member over a time window. ```bash curl -X GET "http://localhost:4000/api/v1/teams/usage/members" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Query schema:** ```json { "type": "object", "properties": { "window": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ], "description": "Time window for usage data" } }, "required": [ "window" ], "additionalProperties": false } ``` **Response schema:** ```json { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID" }, "email": { "nullable": true, "description": "User email address (null if user not found)", "type": "string" }, "displayName": { "nullable": true, "description": "User display name", "type": "string" }, "totalUsage": { "type": "number", "minimum": 0, "description": "Total requests by this member" }, "usageByAlias": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Usage count per alias for this member" } }, "required": [ "userId", "email", "displayName", "totalUsage", "usageByAlias" ], "additionalProperties": false }, "description": "Usage breakdown per team member" } }, "required": [ "members" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } ``` --- ## Response Format All responses follow this structure: ```json { "status": "OK", "data": { ... } } ``` Errors: ```json { "status": "ERROR", "error": { "code": "ERROR_CODE", "message": "..." } } ``` ## Error Codes - `400` Bad request — check params/body - `401` Unauthorized — invalid or missing API key - `403` Forbidden — plan does not include this endpoint - `404` Not found - `429` Rate limited — back off and retry with exponential backoff - `500` Server error — contact support@podengine.ai if persistent ## Tips for AI assistants - All resource IDs are UUIDs - Dates use ISO 8601 (e.g., `2024-01-15T00:00:00Z`) - Pagination is via `pageSize` and `page` query params - Always check `hasTranscript` on an episode before requesting transcript text - Use the OpenAPI spec at `/api-docs/openapi.json` for full machine-readable schemas - Use `/api-docs/llms-full.txt` if you want every request/response field inlined