{ "openapi": "3.1.0", "info": { "title": "Pod Engine API", "version": "1.0.0", "description": "Pod Engine podcast intelligence API. Search 4M+ podcasts, retrieve metadata, transcripts, charts, and more. See https://www.podengine.ai/api-docs for the full interactive documentation." }, "servers": [ { "url": "http://localhost:4000" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Pod Engine API key. Get one at https://www.podengine.ai/get-started." } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "agent" }, { "name": "alerts" }, { "name": "autocomplete" }, { "name": "charts" }, { "name": "episodes" }, { "name": "guest-profiles" }, { "name": "podcasts" }, { "name": "polling" }, { "name": "projects" }, { "name": "search" }, { "name": "stats" }, { "name": "teams" }, { "name": "transcriptions" }, { "name": "usage" } ], "paths": { "/api/v1/agent/project/relevancy": { "post": { "tags": [ "agent" ], "summary": "Project Podcast Relevancy", "description": "Analyze the relevancy of a podcast to a project using AI", "operationId": "askAgentProjectPodcastRelevancy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "podcastId": { "type": "string" }, "searchOptions": { "anyOf": [ { "type": "object", "properties": { "cursor": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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 }, "example": { "projectId": "example-project-id", "podcastId": "example-podcast-id", "forceRegenerate": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/agent/alternative-spellings": { "post": { "tags": [ "agent" ], "summary": "Alternative Spellings", "description": "Generate phonetically plausible alternate spellings for a name or business. Useful for searching against auto-generated podcast transcripts where names are frequently misspelled.", "operationId": "getAlternativeSpellings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "value" ], "additionalProperties": false }, "example": { "value": "Joe Tannorella" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/alerts/alert-config": { "post": { "tags": [ "alerts" ], "summary": "Create Alert Config", "description": "Create a new alert configuration to monitor podcasts for mentions of a person, company, or custom keyword.", "operationId": "createAlertConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 }, "example": { "alertName": "Example Alert", "alertType": "person", "value": "Jason Calacanis" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "createdAlertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/alerts/alert-configs": { "get": { "tags": [ "alerts" ], "summary": "List Alert Configs", "description": "Get all of the team's alert configurations.", "operationId": "getAlertConfigs", "parameters": [ { "name": "enabled", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "alertConfigId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lastRunDate", "alertName" ] } }, { "name": "sortDirection", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } } }, "required": [ "options", "alertConfigs" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/alerts/alert-config/{alertConfigId}": { "get": { "tags": [ "alerts" ], "summary": "Get Alert Config", "description": "Get a single alert configuration by ID.", "operationId": "getAlertConfig", "parameters": [ { "name": "alertConfigId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "alertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "alerts" ], "summary": "Update Alert Config", "description": "Update an existing alert configuration (name, settings, email frequency, or enabled state).", "operationId": "updateAlertConfig", "parameters": [ { "name": "alertConfigId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "createdByUserId", "teamId", "createdAt", "updatedAt", "alertName", "alertType", "enabled", "alertSettings", "emailSettings", "lastRunDate" ], "additionalProperties": false } }, "required": [ "updatedAlertConfig" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "alerts" ], "summary": "Delete Alert Config", "description": "Soft-delete an alert configuration.", "operationId": "deleteAlertConfig", "parameters": [ { "name": "alertConfigId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "deletedAlertConfigId": { "type": "string" } }, "required": [ "deletedAlertConfigId" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/alerts/history": { "get": { "tags": [ "alerts" ], "summary": "Alert Match History", "description": "Get the paginated history of alert matches for the team, optionally scoped to a single alert config.", "operationId": "getAlertMatchHistory", "parameters": [ { "name": "alertConfigId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "sinceDate", "in": "query", "required": false, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "number", "null" ] }, "contextLLMHistoryId": { "type": [ "number", "null" ] }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "type": [ "string", "null" ] }, "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": { "type": [ "number", "null" ] }, "episodeSlug": { "type": "string" }, "episodeTitle": { "type": "string" }, "filteredOut": { "type": "boolean" }, "imageUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "number", "null" ] }, "contextLLMHistoryId": { "type": [ "number", "null" ] }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "processedDate": {}, "type": { "type": "string", "enum": [ "EPISODE" ] } }, "required": [ "advertisementLLMHistoryId", "contextLLMHistoryId", "episodeDate", "episodeId", "filteredOutReason", "podcastId", "processedDate", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "advertisementLLMHistoryId": { "type": [ "number", "null" ] }, "contextLLMHistoryId": { "type": [ "number", "null" ] }, "episodeDate": {}, "episodeId": { "type": "string" }, "filteredOutReason": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/charts": { "get": { "tags": [ "charts" ], "summary": "Historical Chart", "description": "Get a historical chart", "operationId": "getChart", "parameters": [ { "name": "chartType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } }, { "name": "category", "in": "query", "required": false, "schema": { "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\"" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 } }, { "name": "date", "in": "query", "required": false, "schema": { "description": "The date of the chart in YYYY-MM-DD format. If null will return the latest chart", "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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", "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "additionalProperties": false, "description": "Get a specific podcast chart" }, "chart": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "podcastOnChartId", "title", "imageUrl" ], "additionalProperties": false }, "podenginePodcast": { "type": [ "object", "null" ], "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/charts/latest": { "get": { "tags": [ "charts" ], "summary": "Latest Chart", "description": "Get the latest chart", "operationId": "getLatestChart", "parameters": [ { "name": "chartType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } }, { "name": "category", "in": "query", "required": false, "schema": { "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\"" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "podcastOnChartId", "title", "imageUrl" ], "additionalProperties": false }, "podenginePodcast": { "type": [ "object", "null" ], "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/charts/{chartType}/categories": { "get": { "tags": [ "charts" ], "summary": "Chart Categories", "description": "Get the categories for a chart", "operationId": "getCategoriesByChartType", "parameters": [ { "name": "chartType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/charts/{chartType}/countries": { "get": { "tags": [ "charts" ], "summary": "Chart Countries", "description": "Get the available countries for a chart type", "operationId": "getAvailableCountriesByChartType", "parameters": [ { "name": "chartType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/episodes/latest": { "get": { "tags": [ "episodes" ], "summary": "Latest Episodes", "description": "Get the latest 150 episodes", "operationId": "getLatestEpisodes", "parameters": [ { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "podcastImageRequired", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "hasTranscript", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "language", "in": "query", "required": true, "schema": { "default": "en", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "latestPodcasts": { "type": "array", "items": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "anyOf": [ {}, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "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": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "type": [ "string", "null" ] }, "episodeSponsors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "type": [ "string", "null" ] }, "episodeThumbnailRssUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ], "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": { "anyOf": [ {}, { "type": "null" } ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "type": [ "object", "null" ], "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "type": [ "number", "null" ] }, "youtubeDataFetchedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/episodes/{episodeId}/details": { "get": { "tags": [ "episodes" ], "summary": "Episode Details", "description": "Get the details of an episode", "operationId": "getEpisodeDetailsById", "parameters": [ { "name": "episodeId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "episode": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "anyOf": [ {}, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "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": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "type": [ "string", "null" ] }, "episodeSponsors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "type": [ "string", "null" ] }, "episodeThumbnailRssUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ], "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": { "anyOf": [ {}, { "type": "null" } ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "type": [ "object", "null" ], "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "type": [ "number", "null" ] }, "youtubeDataFetchedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/episodes/{episodeId}/transcript-text": { "get": { "tags": [ "episodes" ], "summary": "Episode Transcript Text", "description": "Get the transcript text of an episode", "operationId": "getEpisodeTranscriptText", "parameters": [ { "name": "episodeId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] } }, "required": [ "podcastId", "episodeId", "transcriptId", "text" ], "additionalProperties": false } }, "required": [ "episodeTranscriptText" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/episodes/{episodeId}/transcription-request": { "get": { "tags": [ "transcriptions" ], "summary": "Request Episode Transcription", "description": "Request an episode to be transcribed. This typically takes 1-2 hours and you can check progress using the Requests History endpoint.", "operationId": "requestEpisodeTranscription", "parameters": [ { "name": "episodeId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/episodes/{episodeId}/download/transcript": { "get": { "tags": [ "episodes" ], "summary": "Episode Transcript Download", "description": "File download the transcript of an episode", "operationId": "downloadEpisodeTranscript", "parameters": [ { "name": "episodeId", "in": "path", "required": true, "schema": { "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)$" } }, { "name": "format", "in": "query", "required": true, "schema": { "default": "txt", "type": "string", "enum": [ "txt", "vtt", "sentence-vtt" ] } } ], "responses": { "200": { "description": "Binary file download", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/episodes/{episodeId}/transcript-timestamps": { "get": { "tags": [ "episodes" ], "summary": "Episode Transcript Timestamps", "description": "Get the transcript of an episode with word-level timestamps in a structured JSON format", "operationId": "getEpisodeTranscriptTimestamps", "parameters": [ { "name": "episodeId", "in": "path", "required": true, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/transcriptions": { "get": { "tags": [ "transcriptions" ], "summary": "Transcription Requests", "description": "Get transcription request history for your team", "operationId": "getTranscriptionRequests", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "type": "number", "maximum": 50 } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "filterCompleted", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "transcription", "deepAnalysis", "diarization" ] }, "episodeId": { "type": "string" }, "episodeTitle": { "type": [ "string", "null" ] }, "episodeImageUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "guestPrep" ] }, "episodeId": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeTitle": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeImageUrl": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeSlug": { "type": [ "string", "null" ], "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "autoOutreach" ] }, "episodeId": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeTitle": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeImageUrl": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeSlug": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles": { "post": { "tags": [ "guest-profiles" ], "summary": "Create Guest Profile", "description": "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.", "operationId": "createGuestProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 }, "example": { "firstName": "Jane", "lastName": "Doe", "shortBio": "Jane Doe is a marketing expert with 10 years of experience in B2B SaaS." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileIdOrProjectId}": { "get": { "tags": [ "guest-profiles" ], "summary": "Get Guest Profile Details", "description": "Get detailed information about a specific guest profile including bio, contact details, social media links, and documents", "operationId": "getGuestProfileDetails", "parameters": [ { "name": "guestProfileIdOrProjectId", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the project associated with the guest profile or the guest profile id." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "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": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "name", "id", "size", "status", "fileType", "dateExtracted" ], "additionalProperties": false } }, "listedPodcastsCount": { "type": "number" }, "bookingUrl": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "onePagerUrl": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "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": { "anyOf": [ {}, { "type": "null" } ] }, "lastScrapeFailedAt": { "anyOf": [ {}, { "type": "null" } ] }, "isScraping": { "type": "boolean" } }, "required": [ "socialMediaType", "url", "lastScrapedAt", "lastScrapeFailedAt", "isScraping" ], "additionalProperties": false } }, "guestBio": { "type": [ "object", "null" ], "properties": { "additionalContext": { "type": [ "string", "null" ] }, "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": { "type": [ "object", "null" ], "properties": { "displayLinkedIn": { "type": "boolean" }, "displaySocials": { "type": "boolean" }, "displayPreviousPodcastAppearances": { "type": "boolean" }, "marketingLetterMarkdownText": { "type": [ "string", "null" ] }, "publicSlug": { "type": [ "string", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/download": { "get": { "tags": [ "guest-profiles" ], "summary": "Download Guest Profile", "description": "Download a guest profile as a document. Supported formats are HTML, DOCX, and PDF.", "operationId": "downloadGuestProfile", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "html", "docx", "pdf" ], "description": "The format to download the guest profile in. Supported formats: html, docx, pdf" } } ], "responses": { "200": { "description": "Binary file download", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/bio": { "put": { "tags": [ "guest-profiles" ], "summary": "Update Guest Profile Bio", "description": "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.", "operationId": "updateGuestProfileBio", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/contact-details": { "put": { "tags": [ "guest-profiles" ], "summary": "Update Guest Profile Contact Details", "description": "Update the contact details of a guest profile including name, email, phone, company, website URL, booking URL, LinkedIn, and one-pager URL.", "operationId": "updateGuestProfileContactDetails", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/social-media-links": { "put": { "tags": [ "guest-profiles" ], "summary": "Update Guest Profile Social Media Links", "description": "Update the social media links associated with a guest profile.", "operationId": "updateGuestProfileSocialMediaLinks", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/regenerate-bio": { "post": { "tags": [ "guest-profiles" ], "summary": "Regenerate Guest Bio", "description": "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.", "operationId": "regenerateBio", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/documents": { "post": { "tags": [ "guest-profiles" ], "summary": "Upload Guest Profile Documents", "description": "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.", "operationId": "uploadDocuments", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/guest-profiles/{guestProfileId}/archive": { "post": { "tags": [ "guest-profiles" ], "summary": "Archive Guest Profile", "description": "Archive a guest profile and its associated project. This sets the status to ARCHIVED.", "operationId": "archiveGuestProfile", "parameters": [ { "name": "guestProfileId", "in": "path", "required": true, "schema": { "type": "string", "description": "The guest profile ID" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/latest": { "get": { "tags": [ "podcasts" ], "summary": "Latest Podcasts", "description": "Get the latest podcasts", "operationId": "getLatestPodcasts", "parameters": [ { "name": "hasTranscripts", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/podcasts/multiple": { "get": { "tags": [ "podcasts" ], "summary": "Multiple Podcasts", "description": "Get multiple podcasts by their IDs in a single request", "operationId": "getMultiplePodcasts", "parameters": [ { "name": "podcastIds", "in": "query", "required": true, "schema": { "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" } }, { "name": "details", "in": "query", "required": true, "schema": { "default": "basic", "description": "Level of detail to return for each podcast", "type": "string", "enum": [ "basic", "full" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "type": [ "boolean", "null" ] }, "hostNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "type": [ "object", "null" ], "properties": { "affiliateOrganizationName": { "description": "The name of the affiliate organization", "type": [ "string", "null" ] }, "affiliationType": { "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", "null" ], "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": { "type": [ "boolean", "null" ] }, "podcastHasSponsors": { "type": [ "boolean", "null" ] }, "podcastLocations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "primaryContactEmail": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "firstEpisodePublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "type": [ "number", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/id/lookup": { "get": { "tags": [ "podcasts" ], "summary": "Podcast ID Lookup", "description": "Lookup a podcast by ID", "operationId": "getPodcastIdLookup", "parameters": [ { "name": "appleId", "in": "query", "required": false, "schema": { "description": "Apple Podcasts ID", "type": "number" } }, { "name": "spotifyId", "in": "query", "required": false, "schema": { "description": "Spotify ID", "type": "string" } }, { "name": "slug", "in": "query", "required": false, "schema": { "description": "The Pod Engine slug of the podcast", "type": "string" } }, { "name": "podEngineId", "in": "query", "required": false, "schema": { "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)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": [ "object", "null" ], "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/apple-id/lookup": { "get": { "tags": [ "podcasts" ], "summary": "Apple ID Comprehensive Lookup", "description": "Comprehensive lookup by Apple ID - checks Podcast, PodcastAppleId, PodcastNewRequest, and scraper database", "operationId": "getAppleIdComprehensiveLookup", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Apple Podcasts ID" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "number" }, "appleTitle": { "type": "string" }, "rssUrl": { "type": "string" }, "creationSource": { "type": "string" }, "createdAt": {}, "importedAt": { "anyOf": [ {}, { "type": "null" } ] }, "podcastId": { "type": [ "string", "null" ], "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": { "anyOf": [ {}, { "type": "null" } ] }, "importError": { "type": [ "string", "null" ] }, "importErrorType": { "type": [ "string", "null" ] } }, "required": [ "id", "appleTitle", "rssUrl", "creationSource", "createdAt", "importedAt", "podcastId", "importErrorAt", "importError", "importErrorType" ], "additionalProperties": false }, "scraperData": { "type": [ "object", "null" ], "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "country": { "type": "string" }, "podcastTitle": { "type": "string" }, "createdAt": {}, "lastScrapedAt": { "anyOf": [ {}, { "type": "null" } ] }, "lastSuccessAt": { "anyOf": [ {}, { "type": "null" } ] }, "lastErrorAt": { "anyOf": [ {}, { "type": "null" } ] }, "rssUrl": { "type": [ "string", "null" ] }, "ratingsCount": { "type": [ "number", "null" ] }, "averageRating": { "type": [ "number", "null" ] }, "episodesCount": { "type": [ "number", "null" ] }, "lastEpisodeDate": { "anyOf": [ {}, { "type": "null" } ] }, "isLikelyNonEnglishTitle": { "type": "boolean" }, "skippedPodcastImportReason": { "type": [ "string", "null" ] }, "skippedPodcastImportAt": { "anyOf": [ {}, { "type": "null" } ] } }, "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": { "anyOf": [ {}, { "type": "null" } ] }, "recentAttempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "createdAt": {}, "type": { "type": "string" }, "url": { "type": "string" }, "appleId": { "type": [ "number", "null" ] }, "spotifyId": { "type": [ "string", "null" ] }, "podcastId": { "type": [ "string", "null" ] }, "errorType": { "type": [ "string", "null" ] }, "errorDetails": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/all-details": { "get": { "tags": [ "podcasts" ], "summary": "Podcast All Details", "description": "This wraps all the other endpoints for a podcast so you can get all the details in a single request.", "operationId": "getPodcastAllDetails", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "type": [ "boolean", "null" ] }, "hostNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "type": [ "object", "null" ], "properties": { "affiliateOrganizationName": { "description": "The name of the affiliate organization", "type": [ "string", "null" ] }, "affiliationType": { "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", "null" ], "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": { "type": [ "boolean", "null" ] }, "podcastHasSponsors": { "type": [ "boolean", "null" ] }, "podcastLocations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "primaryContactEmail": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "firstEpisodePublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "type": [ "number", "null" ] } }, "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": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "deepAnalysisRequestedAt": { "anyOf": [ {}, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "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": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "type": [ "string", "null" ] }, "episodeSponsors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "type": [ "string", "null" ] }, "episodeThumbnailRssUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ], "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": { "anyOf": [ {}, { "type": "null" } ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "type": [ "object", "null" ], "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "type": [ "number", "null" ] }, "youtubeDataFetchedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "type": [ "string", "null" ], "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": { "type": [ "object", "null" ], "properties": { "podcastId": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address associated with the podcast contact" }, "verifiedAt": { "anyOf": [ { "description": "The timestamp when the email was last verified, or null if it has not been verified" }, { "type": "null" } ] }, "syntaxValid": { "description": "Whether the email address has valid syntax (e.g. correctly formatted local and domain parts), or null if not yet checked", "type": [ "boolean", "null" ] }, "mxValid": { "description": "Whether the email's domain has valid MX records indicating it can receive mail, or null if not yet checked", "type": [ "boolean", "null" ] }, "deepVerifiedAt": { "anyOf": [ { "description": "The timestamp when the email was last deep-verified for deliverability, or null if not run" }, { "type": "null" } ] }, "deliverabilityStatus": { "description": "Deep deliverability status: valid, invalid, catch-all, unknown, spamtrap, abuse, or do_not_mail", "type": [ "string", "null" ], "enum": [ "valid", "invalid", "catch-all", "unknown", "spamtrap", "abuse", "do_not_mail" ] }, "deliverabilityReason": { "description": "Sub-classification providing more detail on the deliverability result", "type": [ "string", "null" ] }, "isFreeEmailProvider": { "description": "Whether the address belongs to a known free-email provider (e.g. gmail, yahoo)", "type": [ "boolean", "null" ] }, "suggestedCorrection": { "description": "Suggested correction for likely typos, e.g. gmial.com -> gmail.com", "type": [ "string", "null" ] } }, "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": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "object", "null" ], "properties": { "podcastId": { "type": "string" }, "appleId": { "type": "number" }, "spotifyId": { "type": [ "string", "null" ] }, "applePodcastsReview": { "type": [ "object", "null" ], "properties": { "appleId": { "type": "number" }, "scrapedAt": {}, "country": { "type": "string" }, "reviewsCount": { "type": "number" }, "rating": { "type": [ "number", "null" ] }, "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": { "type": [ "object", "null" ], "properties": { "spotifyId": { "type": "string" }, "scrapedAt": {}, "reviewsCount": { "type": "number" }, "rating": { "type": [ "number", "null" ] } }, "required": [ "spotifyId", "scrapedAt", "reviewsCount", "rating" ], "additionalProperties": false }, "castbox": { "type": [ "object", "null" ], "properties": { "scrapedAt": {}, "plays": { "type": "number" }, "subscribers": { "type": "number" } }, "required": [ "scrapedAt", "plays", "subscribers" ], "additionalProperties": false } }, "required": [ "podcastId", "appleId", "spotifyId", "applePodcastsReview", "spotifyReview", "castbox" ], "additionalProperties": false }, "socialMedia": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "followers": { "type": "number", "minimum": 0 }, "likes": { "type": "number", "minimum": 0 }, "following": { "type": "number", "minimum": 0 }, "talkingAboutCount": { "type": [ "number", "null" ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "followers": { "type": "number" }, "employeesInLinkedin": { "type": "number" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "companySize": { "type": [ "string", "null" ] }, "industries": { "type": [ "string", "null" ] }, "logoImageUrl": { "type": [ "string", "null" ] }, "mostRecentUpdate": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "linkedInProfileId": { "type": "string" }, "linkedInNumericId": { "type": "number" }, "avatarUrl": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "about": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "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": { "type": [ "number", "null" ] }, "biography": { "type": [ "string", "null" ] }, "commentEngagementRate": { "type": [ "number", "null" ] }, "dateJoined": {}, "followers": { "type": "number" }, "following": { "type": "number" }, "isPrivate": { "type": "boolean" }, "isVerified": { "type": "boolean" }, "likeEngagementRate": { "type": [ "number", "null" ] }, "likes": { "type": "number" }, "nickname": { "type": "string" }, "handle": { "type": "string" }, "profilePicUrl": { "type": [ "string", "null" ], "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": { "type": [ "string", "null" ], "format": "uri" }, "biography": { "type": [ "string", "null" ] }, "followingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "followerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "postsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dateJoined": { "anyOf": [ {}, { "type": "null" } ] }, "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": { "type": [ "object", "null" ], "properties": { "episodesCount": { "type": "number" }, "episodesWithSponsorsCount": { "type": "number" }, "mostRecentEpisodeDate": {}, "oldestEpisodeDate": {}, "sponsors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "appearancesCount": { "type": "number", "minimum": 1 }, "mostRecentAppearanceDate": {}, "oldestAppearanceDate": {} }, "required": [ "name", "imageUrl", "appearancesCount", "mostRecentAppearanceDate", "oldestAppearanceDate" ], "additionalProperties": false } } }, "required": [ "episodesCount", "episodesWithSponsorsCount", "mostRecentEpisodeDate", "oldestEpisodeDate", "sponsors" ], "additionalProperties": false }, "relatedPodcasts": { "type": [ "object", "null" ], "properties": { "podcastId": { "type": "string" }, "similarPodcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "array", "null" ], "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": { "type": [ "object", "null" ], "properties": { "podcastId": { "type": "string" }, "youtubeData": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "subscriberCount": { "type": "number" }, "viewCount": { "type": "number" }, "videoCount": { "type": "number" }, "publishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "thumbnails": { "type": "object", "properties": { "default": { "type": [ "string", "null" ] }, "medium": { "type": [ "string", "null" ] }, "high": { "type": [ "string", "null" ] } }, "required": [ "default", "medium", "high" ], "additionalProperties": false }, "country": { "type": [ "string", "null" ] }, "customUrl": { "type": [ "string", "null" ] }, "links": { "type": [ "array", "null" ], "items": { "type": "string" } }, "isPodcastChannel": { "type": [ "boolean", "null" ] }, "discoverInputKeyword": { "type": [ "string", "null" ] }, "bannerImageUrl": { "type": [ "string", "null" ] }, "videos": { "type": [ "array", "null" ], "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": { "type": [ "string", "null" ] }, "dataLastUpdated": {}, "lastVideoUploadDate": { "anyOf": [ {}, { "type": "null" } ] }, "lastVideoUploadDateSource": { "type": [ "string", "null" ] }, "lastVideoUploadDateCheckedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Details", "description": "Get a podcast by ID or slug", "operationId": "getPodcast", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "type": [ "boolean", "null" ] }, "hostNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "type": [ "object", "null" ], "properties": { "affiliateOrganizationName": { "description": "The name of the affiliate organization", "type": [ "string", "null" ] }, "affiliationType": { "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", "null" ], "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": { "type": [ "boolean", "null" ] }, "podcastHasSponsors": { "type": [ "boolean", "null" ] }, "podcastLocations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "primaryContactEmail": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "firstEpisodePublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "type": [ "number", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/episodes": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Episodes", "description": "Get the episodes for a podcast", "operationId": "getPodcastEpisodes", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, { "name": "hasTranscript", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "anyOf": [ {}, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "durationSeconds": { "type": [ "number", "null" ] }, "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": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "guest", "unknown", "mentioned" ] }, "imageUrl": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "imageUrl" ], "additionalProperties": false } }, "episodeSlug": { "type": "string" }, "episodeShortDescription": { "type": [ "string", "null" ] }, "episodeSponsors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "hasTranscript": { "type": "boolean" }, "imageUrl": { "type": [ "string", "null" ] }, "episodeThumbnailRssUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ], "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": { "anyOf": [ {}, { "type": "null" } ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "youtubeEpisodeDetails": { "type": [ "object", "null" ], "properties": { "youtubeLink": { "type": "string", "format": "uri" }, "youtubeMatchConfidence": { "type": "number" }, "youtubeViewCount": { "type": [ "number", "null" ] }, "youtubeDataFetchedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "youtubeLink", "youtubeMatchConfidence", "youtubeViewCount", "youtubeDataFetchedAt" ], "additionalProperties": false }, "applePodcastsUrl": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/related-podcasts": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Related Podcasts", "description": "Get the related podcasts for a podcast", "operationId": "getPodcastRelatedPodcasts", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/reviews": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Reviews", "description": "Get the reviews for a podcast", "operationId": "getPodcastReviews", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "applePodcastsReview": { "type": [ "object", "null" ], "properties": { "appleId": { "type": "number" }, "scrapedAt": {}, "country": { "type": "string" }, "reviewsCount": { "type": "number" }, "rating": { "type": [ "number", "null" ] }, "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": { "type": [ "object", "null" ], "properties": { "spotifyId": { "type": "string" }, "scrapedAt": {}, "reviewsCount": { "type": "number" }, "rating": { "type": [ "number", "null" ] } }, "required": [ "spotifyId", "scrapedAt", "reviewsCount", "rating" ], "additionalProperties": false }, "castbox": { "type": [ "object", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/contacts": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Contacts", "description": "Get the contacts for a podcast", "operationId": "getPodcastContacts", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "anyOf": [ { "description": "The timestamp when the email was last verified, or null if it has not been verified" }, { "type": "null" } ] }, "syntaxValid": { "description": "Whether the email address has valid syntax (e.g. correctly formatted local and domain parts), or null if not yet checked", "type": [ "boolean", "null" ] }, "mxValid": { "description": "Whether the email's domain has valid MX records indicating it can receive mail, or null if not yet checked", "type": [ "boolean", "null" ] }, "deepVerifiedAt": { "anyOf": [ { "description": "The timestamp when the email was last deep-verified for deliverability, or null if not run" }, { "type": "null" } ] }, "deliverabilityStatus": { "description": "Deep deliverability status: valid, invalid, catch-all, unknown, spamtrap, abuse, or do_not_mail", "type": [ "string", "null" ], "enum": [ "valid", "invalid", "catch-all", "unknown", "spamtrap", "abuse", "do_not_mail" ] }, "deliverabilityReason": { "description": "Sub-classification providing more detail on the deliverability result", "type": [ "string", "null" ] }, "isFreeEmailProvider": { "description": "Whether the address belongs to a known free-email provider (e.g. gmail, yahoo)", "type": [ "boolean", "null" ] }, "suggestedCorrection": { "description": "Suggested correction for likely typos, e.g. gmial.com -> gmail.com", "type": [ "string", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/charts": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Chart Position", "description": "Get the latest positions of a podcast in a chart", "operationId": "getPodcastCharts", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, { "name": "chartType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "apple", "spotify" ], "description": "The type of chart, one of apple, spotify" } }, { "name": "category", "in": "query", "required": false, "schema": { "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\"" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "The country of the chart in ISO 3166-1 alpha-2 format, for example \"us\". Defaults to us." } }, { "name": "positionsLimit", "in": "query", "required": false, "schema": { "description": "The number of chart positions to return. If not provided, all positions are returned", "type": "number", "minimum": 1, "maximum": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "The number of charts to return", "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/social-media": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Social Media", "description": "Get the social media data for a podcast", "operationId": "getPodcastSocialMediaDetails", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "followers": { "type": "number", "minimum": 0 }, "likes": { "type": "number", "minimum": 0 }, "following": { "type": "number", "minimum": 0 }, "talkingAboutCount": { "type": [ "number", "null" ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "followers": { "type": "number" }, "employeesInLinkedin": { "type": "number" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "companySize": { "type": [ "string", "null" ] }, "industries": { "type": [ "string", "null" ] }, "logoImageUrl": { "type": [ "string", "null" ] }, "mostRecentUpdate": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "linkedInProfileId": { "type": "string" }, "linkedInNumericId": { "type": "number" }, "avatarUrl": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "about": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "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": { "type": [ "number", "null" ] }, "biography": { "type": [ "string", "null" ] }, "commentEngagementRate": { "type": [ "number", "null" ] }, "dateJoined": {}, "followers": { "type": "number" }, "following": { "type": "number" }, "isPrivate": { "type": "boolean" }, "isVerified": { "type": "boolean" }, "likeEngagementRate": { "type": [ "number", "null" ] }, "likes": { "type": "number" }, "nickname": { "type": "string" }, "handle": { "type": "string" }, "profilePicUrl": { "type": [ "string", "null" ], "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": { "type": [ "string", "null" ], "format": "uri" }, "biography": { "type": [ "string", "null" ] }, "followingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "followerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "postsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dateJoined": { "anyOf": [ {}, { "type": "null" } ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/youtube": { "get": { "tags": [ "podcasts" ], "summary": "Podcast Youtube Details", "description": "Get the youtube data for a podcast", "operationId": "getPodcastYoutubeDetails", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "subscriberCount": { "type": "number" }, "viewCount": { "type": "number" }, "videoCount": { "type": "number" }, "publishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "thumbnails": { "type": "object", "properties": { "default": { "type": [ "string", "null" ] }, "medium": { "type": [ "string", "null" ] }, "high": { "type": [ "string", "null" ] } }, "required": [ "default", "medium", "high" ], "additionalProperties": false }, "country": { "type": [ "string", "null" ] }, "customUrl": { "type": [ "string", "null" ] }, "links": { "type": [ "array", "null" ], "items": { "type": "string" } }, "isPodcastChannel": { "type": [ "boolean", "null" ] }, "discoverInputKeyword": { "type": [ "string", "null" ] }, "bannerImageUrl": { "type": [ "string", "null" ] }, "videos": { "type": [ "array", "null" ], "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": { "type": [ "string", "null" ] }, "dataLastUpdated": {}, "lastVideoUploadDate": { "anyOf": [ {}, { "type": "null" } ] }, "lastVideoUploadDateSource": { "type": [ "string", "null" ] }, "lastVideoUploadDateCheckedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastId}/transcription-request": { "get": { "tags": [ "transcriptions" ], "summary": "Request Podcast Transcription", "description": "Request multiple episodes for a Podcast to be transcribed and optionally the future Podcast episodes to be transcribed automatically.", "operationId": "requestPodcastTranscription", "parameters": [ { "name": "podcastId", "in": "path", "required": true, "schema": { "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" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "since", "latest", "recent" ] } }, { "name": "requestFutureEpisodes", "in": "query", "required": true, "schema": { "default": false, "description": "If true, future episodes will be transcribed automatically.", "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/podcasts/{podcastIdOrSlug}/refresh": { "get": { "tags": [ "podcasts" ], "summary": "Refresh Podcast", "description": "Refresh podcast metadata and thumbnail from RSS feed. Rate limited to once per minute per podcast.", "operationId": "refreshPodcast", "parameters": [ { "name": "podcastIdOrSlug", "in": "path", "required": true, "schema": { "type": "string", "description": "Podengine ID, Apple ID, or slug" } }, { "name": "updatePodcastThumbnail", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "type": "string" } }, "explicitRss": { "type": [ "boolean", "null" ] }, "hostNames": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ignore": { "type": "boolean" }, "ignoreReason": { "type": "string" }, "neverTranscribe": { "type": "boolean" }, "neverTranscribeReason": { "type": "string" }, "isClaimed": { "type": "boolean" }, "podcastAffiliation": { "type": [ "object", "null" ], "properties": { "affiliateOrganizationName": { "description": "The name of the affiliate organization", "type": [ "string", "null" ] }, "affiliationType": { "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", "null" ], "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": { "type": [ "boolean", "null" ] }, "podcastHasSponsors": { "type": [ "boolean", "null" ] }, "podcastLocations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "primaryContactEmail": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "stats": { "type": "object", "properties": { "downloadCount": { "type": "number" }, "episodeCount": { "type": "number" }, "latestPublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "firstEpisodePublishedAt": { "anyOf": [ {}, { "type": "null" } ] }, "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": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "audienceEstimate": { "type": "object", "properties": { "audienceDemographics": { "type": [ "object", "null" ], "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": { "type": [ "number", "null" ] }, "estimatedMonthyListenersCalculatedAt": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "audienceDemographics", "estimatedMonthlyListeners", "estimatedMonthyListenersCalculatedAt" ], "additionalProperties": false }, "audioRetentionPolicy": { "type": "string", "enum": [ "RETAIN_INDEFINITELY", "RETAIN_DAYS", "RETAIN_UNTIL_TRANSCRIBED" ] }, "audioRetentionDays": { "type": [ "number", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/polling/updates": { "get": { "tags": [ "polling" ], "summary": "Poll for Updates", "description": "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.", "operationId": "getUpdates", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "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))$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Opaque cursor from a previous response. Takes precedence over since.", "type": "string" } }, { "name": "eventTypes", "in": "query", "required": false, "schema": { "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" ] } } }, { "name": "projectId", "in": "query", "required": false, "schema": { "description": "Filter listed_podcast_added events to a specific project.", "type": "string" } }, { "name": "guestProfileId", "in": "query", "required": false, "schema": { "description": "Filter guest_appearance events to a specific guest profile.", "type": "string" } }, { "name": "alertConfigId", "in": "query", "required": false, "schema": { "description": "Filter alert_match events to a specific alert configuration.", "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "description": "Max events per page (1-100, default 50).", "type": "number", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "options": { "type": "object", "properties": { "since": { "description": "The resolved since timestamp used for this query.", "type": [ "string", "null" ], "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": "The cursor provided in this request, if any.", "type": [ "string", "null" ] }, "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": { "description": "Project filter applied, if any.", "type": [ "string", "null" ] }, "guestProfileId": { "description": "Guest profile filter applied, if any.", "type": [ "string", "null" ] }, "alertConfigId": { "description": "Alert config filter applied, if any.", "type": [ "string", "null" ] } }, "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": { "type": [ "string", "null" ] }, "guestProfileId": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] } }, "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": { "type": [ "boolean", "null" ] }, "humanVerified": { "type": [ "boolean", "null" ] }, "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": { "description": "Pass this value as the cursor query parameter on your next poll. Null if no results.", "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects": { "get": { "tags": [ "projects" ], "summary": "Get Projects", "description": "Get a list of projects for the authenticated user", "operationId": "getProjects", "parameters": [ { "name": "states", "in": "query", "required": false, "schema": {} }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent-activity", "name", "created" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "podcastSlug": { "type": [ "string", "null" ] }, "podcastImageUrl": { "type": [ "string", "null" ] }, "toValue": { "type": [ "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects/{projectSlug}/details": { "get": { "tags": [ "projects" ], "summary": "Get Project Details", "description": "Get detailed information about a specific project including metadata and statistics", "operationId": "getProjectDetails", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "podcastSlug": { "type": [ "string", "null" ] }, "podcastImageUrl": { "type": [ "string", "null" ] }, "toValue": { "type": [ "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "required": [ "id", "displayName", "avatarSeed" ], "additionalProperties": false } }, "required": [ "type", "date", "podcastTitle", "podcastSlug", "podcastImageUrl", "toValue", "user" ], "additionalProperties": false } }, "projectTypeOtherReason": { "type": [ "string", "null" ] }, "projectPurpose": { "type": [ "string", "null" ] }, "projectKeywords": { "type": "array", "items": { "type": "string" } }, "publicTitle": { "type": [ "string", "null" ] }, "publicDescription": { "type": [ "string", "null" ] }, "publicSlug": { "type": [ "string", "null" ] }, "isPublicListicle": { "type": "boolean" }, "publicPodcastLimit": { "type": "number" }, "isPublicForTeam": { "type": "boolean" }, "goHighLevelIntegration": { "type": [ "object", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects/{projectSlug}/strategies": { "get": { "tags": [ "projects" ], "summary": "Get Project Strategies", "description": "Get all strategies associated with a project", "operationId": "getProjectStrategies", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ], "enum": [ "straightforward", "unconventional", "longshot" ] }, "strategyFocus": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects/{projectSlug}": { "patch": { "tags": [ "projects" ], "summary": "Update Project", "description": "Update an existing project's details", "operationId": "updateProject", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "DRAFT", "PENDING", "ACTIVE", "ARCHIVED", "ERROR" ] }, "projectPurpose": { "type": [ "string", "null" ] }, "projectKeywords": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "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": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "DRAFT", "PENDING", "ARCHIVED", "ERROR" ] }, "imageUrl": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "podcastSlug": { "type": [ "string", "null" ] }, "podcastImageUrl": { "type": [ "string", "null" ] }, "toValue": { "type": [ "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "avatarSeed": { "type": [ "string", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects/{projectSlug}/podcasts": { "post": { "tags": [ "projects" ], "summary": "Add Podcast to Project", "description": "Add a single podcast to a project's list", "operationId": "addPodcastToProject", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] } }, "required": [ "podcastId", "titleOriginal", "titleLatest", "slug", "imageUrl" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "urgent" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "addedAt": {}, "updatedAt": {}, "addedByUser": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": [ "string", "null" ] } }, "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": { "type": [ "string", "null" ] }, "toValue": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "userDisplayName": { "type": "string" } }, "required": [ "actionType", "activityDate", "fromValue", "toValue", "userId", "userDisplayName" ], "additionalProperties": false } }, "analysis": { "type": "object", "properties": { "relevancyScore": { "type": [ "number", "null" ] }, "deepRelevancyScore": { "type": [ "number", "null" ] }, "hostRelevancyScore": { "type": [ "number", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/projects/{projectSlug}/podcasts/{listedPodcastId}": { "patch": { "tags": [ "projects" ], "summary": "Update Podcast on Project", "description": "Update the details or status of a podcast within a project", "operationId": "updateProjectListedPodcast", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listedPodcastId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "urgent" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ], "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": { "type": [ "string", "null" ] } }, "required": [ "podcastId", "titleOriginal", "titleLatest", "slug", "imageUrl" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "prospect", "qualified", "pitched", "lost", "booked", "ignored" ] }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "urgent" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "addedAt": {}, "updatedAt": {}, "addedByUser": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": [ "string", "null" ] } }, "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": { "type": [ "string", "null" ] }, "toValue": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "userDisplayName": { "type": "string" } }, "required": [ "actionType", "activityDate", "fromValue", "toValue", "userId", "userDisplayName" ], "additionalProperties": false } }, "analysis": { "type": "object", "properties": { "relevancyScore": { "type": [ "number", "null" ] }, "deepRelevancyScore": { "type": [ "number", "null" ] }, "hostRelevancyScore": { "type": [ "number", "null" ] } }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "projects" ], "summary": "Remove Podcast on Project", "description": "Remove a podcast from a project's list", "operationId": "removeListedPodcastFromProject", "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listedPodcastId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/autocomplete/podcasts": { "get": { "tags": [ "autocomplete" ], "summary": "Podcasts", "description": "Get autocomplete suggestions for podcasts", "operationId": "searchAutocompletePodcasts", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "The fuzzy search query to match against the podcast title" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "podcasts": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/search/podcasts": { "post": { "tags": [ "search" ], "summary": "Search Podcasts", "description": "Search for podcasts by title, description, or RSS feed URL", "operationId": "searchPodcasts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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 }, "example": { "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" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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": { "description": "The project podcast relevancy. If null means something went wrong calculating it.", "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] } }, "required": [ "searchMode", "searchId", "searchOptions", "seachResultsStats", "result", "cursor" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/search/episodes": { "post": { "tags": [ "search" ], "summary": "Search Episodes", "description": "Search for episodes by title, description, or transcript text", "operationId": "searchEpisodes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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 }, "example": { "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" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "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", "null" ] }, "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": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "qualityScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "engagementScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "socialScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "min", "max" ], "additionalProperties": false }, "youtubeScore": { "type": "object", "properties": { "min": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "max": { "type": [ "number", "null" ], "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": { "description": "The project podcast relevancy. If null means something went wrong calculating it.", "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] } }, "required": [ "searchMode", "searchId", "searchOptions", "seachResultsStats", "result", "cursor" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/rss/stats/public/podcast2": { "get": { "tags": [ "stats" ], "summary": "Podcast 2 Stats", "description": "We track the number of podcasts that have implemented podcast2 rss fields and the number of episodes that have transcripts", "operationId": "getRssStatsPodcast2", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [] } }, "/api/v1/teams/podcasts": { "get": { "tags": [ "teams" ], "summary": "Get Team Podcasts", "description": "Get all podcasts associated with your team", "operationId": "getTeamPodcasts", "parameters": [ { "name": "blacklist", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "sync", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "hasAirtableError", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 100, "type": "number", "maximum": 100 } }, { "name": "offset", "in": "query", "required": true, "schema": { "default": 0, "type": "number" } }, { "name": "textFilter", "in": "query", "required": false, "schema": { "description": "Can be a partial podcast title, apple id, apple podcast url, or airtable record id", "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "podcastTitle", "addedAt", "lastAirtableSync" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "addedReason": { "type": "string", "enum": [ "add-to-team-podcasts-button", "listed-podcast", "migration", "script", "search-export" ] }, "blacklist": { "type": "boolean" }, "createdAt": {}, "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/podcasts/{podcastId}": { "put": { "tags": [ "teams" ], "summary": "Add Podcast to Team", "description": "Add a podcast to your team", "operationId": "addPodcastToTeam", "parameters": [ { "name": "podcastId", "in": "path", "required": true, "schema": { "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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": [ "boolean", "null" ] }, "blacklist": { "type": [ "boolean", "null" ] } }, "required": [ "sync", "blacklist" ], "additionalProperties": false }, "example": { "sync": false, "blacklist": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "teamPodcast": { "type": "object", "properties": { "addedByUserId": { "type": [ "string", "null" ] }, "addedReason": { "type": "string", "enum": [ "add-to-team-podcasts-button", "listed-podcast", "migration", "script", "search-export" ] }, "blacklist": { "type": "boolean" }, "createdAt": {}, "podcast": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorityScore": { "type": [ "object", "null" ], "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": { "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "teams" ], "summary": "Remove Podcast from Team", "description": "Remove a podcast from your team", "operationId": "removePodcastFromTeam", "parameters": [ { "name": "podcastId", "in": "path", "required": true, "schema": { "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" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/podcasts/multiple": { "delete": { "tags": [ "teams" ], "summary": "Remove Multiple Podcasts from Team", "description": "Remove multiple podcasts from your team by PodEngine IDs or Apple IDs", "operationId": "removeMultiplePodcastsFromTeam", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "podcastIds": { "type": "array", "items": { "type": "string" } }, "appleIds": { "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/request-history": { "get": { "tags": [ "teams" ], "summary": "Request History", "description": "Get team request history", "operationId": "getTeamRequestHistory", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "type": "number", "maximum": 50 } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "filterCompleted", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "requestType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "autoOutreach", "deepAnalysis", "diarization", "guestPrep", "transcription" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "transcription", "deepAnalysis", "diarization" ] }, "episodeId": { "type": "string" }, "episodeTitle": { "type": [ "string", "null" ] }, "episodeImageUrl": { "type": [ "string", "null" ] }, "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": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "guestPrep" ] }, "episodeId": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeTitle": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeImageUrl": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeSlug": { "type": [ "string", "null" ], "enum": [ null ] } }, "required": [ "podcastTitle", "podcastImageUrl", "podcastId", "podcastSlug", "requestedAt", "requestedByUserId", "completedAt", "requestType", "episodeId", "episodeTitle", "episodeImageUrl", "episodeSlug" ], "additionalProperties": false }, { "type": "object", "properties": { "podcastTitle": { "type": "string" }, "podcastImageUrl": { "type": [ "string", "null" ] }, "podcastId": { "type": "string" }, "podcastSlug": { "type": "string" }, "requestedAt": {}, "requestedByUserId": { "type": [ "string", "null" ] }, "completedAt": { "anyOf": [ {}, { "type": "null" } ] }, "requestType": { "type": "string", "enum": [ "autoOutreach" ] }, "episodeId": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeTitle": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeImageUrl": { "type": [ "string", "null" ], "enum": [ null ] }, "episodeSlug": { "type": [ "string", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/usage/current": { "get": { "tags": [ "usage" ], "summary": "Current Month Usage", "description": "Get your team's current month API usage and limits for each usage category, along with enabled feature flags and plan information.", "operationId": "getCurrent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "description": "Monthly limit (null = unlimited, 0 = disabled)", "type": [ "number", "null" ], "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": { "type": [ "number", "null" ] } }, "required": [ "used", "limit" ], "additionalProperties": false }, "guestProfiles": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": [ "number", "null" ] } }, "required": [ "used", "limit" ], "additionalProperties": false } }, "required": [ "projects", "guestProfiles" ], "additionalProperties": false } }, "required": [ "month", "plan", "featureFlags", "aliases", "totalUsed" ], "additionalProperties": false } }, "required": [ "status", "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/usage/daily": { "get": { "tags": [ "usage" ], "summary": "Daily Usage Trend", "description": "Get daily usage breakdown for your team over a time window (7, 30, or 90 days), with limit thresholds for comparison.", "operationId": "getDaily", "parameters": [ { "name": "window", "in": "query", "required": true, "schema": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ], "description": "Time window for usage data" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "number", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/usage/monthly": { "get": { "tags": [ "usage" ], "summary": "Monthly Usage History", "description": "Get monthly usage history for your team over the past N months.", "operationId": "getMonthly", "parameters": [ { "name": "months", "in": "query", "required": true, "schema": { "default": 6, "description": "Number of months of history to return", "type": "number", "minimum": 1, "maximum": 24 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "type": [ "number", "null" ], "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/teams/usage/members": { "get": { "tags": [ "usage" ], "summary": "Team Member Usage", "description": "Get usage breakdown by team member over a time window.", "operationId": "getMembers", "parameters": [ { "name": "window", "in": "query", "required": true, "schema": { "default": "30d", "type": "string", "enum": [ "7d", "30d", "90d" ], "description": "Time window for usage data" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "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": { "description": "User email address (null if user not found)", "type": [ "string", "null" ] }, "displayName": { "description": "User display name", "type": [ "string", "null" ] }, "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 } } } }, "400": { "description": "Bad request" }, "401": { "description": "Authentication required" }, "403": { "description": "Forbidden — plan does not include this endpoint" }, "404": { "description": "Not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearerAuth": [] } ] } } } }