# Podcast Episodes

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Podcasts
> Source: https://www.podengine.ai/api-docs/get-podcast-episodes.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/get-podcast-episodes
> Full API reference (all endpoints): https://www.podengine.ai/api-docs/llms.txt

**Base URL:** `http://localhost:4000`
**Auth:** Requires a Bearer token: `Authorization: Bearer YOUR_API_KEY`

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/episodes
**Podcast Episodes**

Get the episodes for a podcast

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/episodes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Path parameters schema:**
```json
{
  "type": "object",
  "properties": {
    "podcastIdOrSlug": {
      "type": "string",
      "description": "Podengine ID, Apple ID, or slug"
    }
  },
  "required": [
    "podcastIdOrSlug"
  ],
  "additionalProperties": false
}
```

**Query schema:**
```json
{
  "type": "object",
  "properties": {
    "hasTranscript": {
      "type": "boolean"
    },
    "skip": {
      "type": "number"
    },
    "limit": {
      "type": "number",
      "maximum": 100
    }
  },
  "additionalProperties": false
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "type": "object",
      "properties": {
        "options": {
          "type": "object",
          "properties": {
            "hasTranscript": {
              "type": "boolean"
            },
            "skip": {
              "type": "number"
            },
            "limit": {
              "type": "number",
              "maximum": 100
            }
          },
          "additionalProperties": false
        },
        "totalEpisodes": {
          "type": "number"
        },
        "totalTranscripts": {
          "type": "number"
        },
        "podcastWithEpisodes": {
          "type": "object",
          "properties": {
            "podcast": {
              "type": "object",
              "properties": {
                "author": {
                  "nullable": true,
                  "type": "string"
                },
                "authorityScore": {
                  "nullable": true,
                  "type": "object",
                  "properties": {
                    "calculatedAt": {},
                    "authorityScore": {
                      "type": "number",
                      "description": "This is the weighted total authority score of the podcast, out of 100"
                    },
                    "qualityScore": {
                      "type": "number",
                      "description": "This is the quality score of the podcast, out of 100"
                    },
                    "youtubeScore": {
                      "type": "number",
                      "description": "This is the YouTube score of the podcast, out of 100"
                    },
                    "socialScore": {
                      "type": "number",
                      "description": "This is the social score of the podcast, out of 100"
                    },
                    "engagementScore": {
                      "type": "number",
                      "description": "This is the engagement score of the podcast, out of 100"
                    }
                  },
                  "required": [
                    "calculatedAt",
                    "authorityScore",
                    "qualityScore",
                    "youtubeScore",
                    "socialScore",
                    "engagementScore"
                  ],
                  "additionalProperties": false
                },
                "genres": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "id": {
                  "type": "string"
                },
                "imageUrl": {
                  "nullable": true,
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "lastEpisodePublishedAt": {},
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "titleLatest": {
                  "type": "string"
                }
              },
              "required": [
                "author",
                "authorityScore",
                "genres",
                "id",
                "imageUrl",
                "language",
                "lastEpisodePublishedAt",
                "slug",
                "title",
                "titleLatest"
              ],
              "additionalProperties": false
            },
            "episodes": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "deepAnalysisRequestedAt": {
                    "nullable": true
                  },
                  "description": {
                    "nullable": true,
                    "type": "string"
                  },
                  "durationSeconds": {
                    "nullable": true,
                    "type": "number"
                  },
                  "enclosureUrl": {
                    "type": "string"
                  },
                  "episodeId": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "episodeGuestsAndHosts": {
                    "nullable": true,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "host",
                            "guest",
                            "unknown",
                            "mentioned"
                          ]
                        },
                        "imageUrl": {
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "type",
                        "imageUrl"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "episodeSlug": {
                    "type": "string"
                  },
                  "episodeShortDescription": {
                    "nullable": true,
                    "type": "string"
                  },
                  "episodeSponsors": {
                    "nullable": true,
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "hasTranscript": {
                    "type": "boolean"
                  },
                  "imageUrl": {
                    "nullable": true,
                    "type": "string"
                  },
                  "episodeThumbnailRssUrl": {
                    "nullable": true,
                    "type": "string"
                  },
                  "podcastId": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "podcastSlug": {
                    "type": "string"
                  },
                  "publishedAt": {},
                  "title": {
                    "type": "string"
                  },
                  "transcriptId": {
                    "nullable": true,
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "transcriptionRequestedAt": {
                    "nullable": true
                  },
                  "audienceEstimate": {
                    "type": "object",
                    "properties": {
                      "audienceDemographics": {
                        "nullable": true,
                        "type": "object",
                        "properties": {
                          "ageRange": {
                            "type": "string",
                            "enum": [
                              "Under 18",
                              "18-24",
                              "25-34",
                              "35-44",
                              "45-54",
                              "55+"
                            ],
                            "description": "The age range of the audience as a string."
                          },
                          "genderSkew": {
                            "type": "string",
                            "enum": [
                              "Male 0% Female 100%",
                              "Male 20% Female 80%",
                              "Male 40% Female 60%",
                              "Male 50% Female 50%",
                              "Male 60% Female 40%",
                              "Male 80% Female 20%",
                              "Male 100% Female 0%"
                            ],
                            "description": "How the audience is skewed in terms of gender."
                          },
                          "educationLevel": {
                            "type": "string",
                            "enum": [
                              "No High School",
                              "High School",
                              "Some College",
                              "Bachelors Degree",
                              "Masters Degree",
                              "Doctorate"
                            ],
                            "description": "The probable education levels of the audience."
                          },
                          "incomeLevel": {
                            "type": "string",
                            "enum": [
                              "Under $25K",
                              "$25K-$50K",
                              "$50K-$75K",
                              "$75K-$100K",
                              "$100K-$150K",
                              "$150K-$200K",
                              "$200K+"
                            ],
                            "description": "The probable income levels of the audience."
                          },
                          "exampleListenerProfile": {
                            "type": "string",
                            "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser."
                          }
                        },
                        "required": [
                          "ageRange",
                          "genderSkew",
                          "educationLevel",
                          "incomeLevel",
                          "exampleListenerProfile"
                        ],
                        "additionalProperties": false
                      },
                      "estimatedMonthlyListeners": {
                        "nullable": true,
                        "type": "number"
                      },
                      "estimatedMonthyListenersCalculatedAt": {
                        "nullable": true
                      }
                    },
                    "required": [
                      "audienceDemographics",
                      "estimatedMonthlyListeners",
                      "estimatedMonthyListenersCalculatedAt"
                    ],
                    "additionalProperties": false
                  },
                  "youtubeEpisodeDetails": {
                    "nullable": true,
                    "type": "object",
                    "properties": {
                      "youtubeLink": {
                        "type": "string",
                        "format": "uri"
                      },
                      "youtubeMatchConfidence": {
                        "type": "number"
                      },
                      "youtubeViewCount": {
                        "nullable": true,
                        "type": "number"
                      },
                      "youtubeDataFetchedAt": {
                        "nullable": true
                      }
                    },
                    "required": [
                      "youtubeLink",
                      "youtubeMatchConfidence",
                      "youtubeViewCount",
                      "youtubeDataFetchedAt"
                    ],
                    "additionalProperties": false
                  },
                  "applePodcastsUrl": {
                    "nullable": true,
                    "type": "string",
                    "format": "uri"
                  }
                },
                "required": [
                  "deepAnalysisRequestedAt",
                  "description",
                  "durationSeconds",
                  "enclosureUrl",
                  "episodeId",
                  "episodeGuestsAndHosts",
                  "episodeSlug",
                  "episodeShortDescription",
                  "episodeSponsors",
                  "hasTranscript",
                  "imageUrl",
                  "episodeThumbnailRssUrl",
                  "podcastId",
                  "podcastSlug",
                  "publishedAt",
                  "title",
                  "transcriptId",
                  "transcriptionRequestedAt",
                  "youtubeEpisodeDetails",
                  "applePodcastsUrl"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "podcast",
            "episodes"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "options",
        "totalEpisodes",
        "totalTranscripts",
        "podcastWithEpisodes"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status",
    "data"
  ],
  "additionalProperties": false
}
```

---

## See also

- All endpoints in one file: https://www.podengine.ai/api-docs/llms.txt
- Full reference with every schema inlined: https://www.podengine.ai/api-docs/llms-full.txt
- OpenAPI 3.1 spec: https://www.podengine.ai/api-docs/openapi.json
- Get an API key: https://www.podengine.ai/get-started
- Support: support@podengine.ai