> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-podcasts-and-episodes.md). # REST API podcasts and episodes Endpoints, parameters, fields, and errors of the podcasts and episodes resources in the REST API v1. Use this reference when you need the exact endpoints and parameters for podcasts and episodes. Paths are relative to `https://app.podigee.com/api/v1`. ## Podcasts | Method | Path | Purpose | Notable parameters | Response notes | | -------- | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `GET` | `/podcasts` | List the podcasts that the credential can see | `fields_filter[]`, `collaborator` (default `true`), `partner` (default `true`), `filter` with the value `analytics` | No pagination. | | `GET` | `/podcasts/{podcast_id}` | Read one podcast | none | Returns `304` when the `ETag` did not change. | | `POST` | `/podcasts` | Create a podcast | Create fields, see below | `422` with the validation message when a field is invalid. Plan limits on podcasts are enforced on create. | | `PUT` | `/podcasts/{podcast_id}` | Update a podcast | Update fields, see below | `422` with the validation message. | | `DELETE` | `/podcasts/{podcast_id}` | Delete a podcast | none | `422` with a message when the podcast cannot be deleted. | ### Podcast fields Create fields: `authors`, `category_id`, `category_ids[]`, `copyright_text`, `cover_image`, `create_stats_reports`, `description`, `domain`, `explicit`, `external`, `external_site_url`, `facebook`, `feed_items`, `flattr_id`, `keywords[]`, `language`, `owner_email`, `publication_type`, `quality`, `subdomain`, `subtitle`, `title`, `transcriptions_enabled`, `twitter`, `website_url`. Update fields: the create fields without `external`, plus `published_at`. The API stores a `category_id` value as `category_ids`. The response of a podcast includes its feeds and the `podcast_namespace_guid`. ### Podcast errors | Status | Message | | ------ | --------------------------------------------------------------- | | `404` | `The podcast with id could not be found.` | | `422` | The validation message of the failed create, update, or delete. | ## Episodes | Method | Path | Purpose | Notable parameters | Response notes | | -------- | ------------------------ | ----------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `GET` | `/episodes` | List or search episodes | See the list parameters below | Newest episodes first. Offset pagination; no total count. | | `GET` | `/episodes/{episode_id}` | Read one episode | none | | | `POST` | `/episodes` | Create an episode | Create fields, see below | `422` with the validation message when a field is invalid. Plan limits on episodes are enforced on create. | | `PUT` | `/episodes/{episode_id}` | Update an episode | Update fields, see below | `422` with the validation message. | | `DELETE` | `/episodes/{episode_id}` | Delete an episode | none | `422` with the organization permission message when the credential may not delete the episode. | ### Episode list parameters | Parameter | Meaning | Values and limits | | ------------------- | ------------------------------------------------- | --------------------------------------------------------------- | | `podcast_id` | One podcast | Podcast id | | `podcast_ids[]` | Several podcasts | Podcast ids | | `limit_per_podcast` | Episodes per podcast when `podcast_ids[]` is used | Maximum `10` | | `limit` | Episodes per page | Default `50`, maximum `50` | | `offset` | Episodes to skip | Number | | `published` | Only published episodes | `true` | | `publication_type` | Only one episode type | `full`, `trailer`, or `bonus`. Omit the parameter for all types | | `sort_by` | Sort field | `number`, `title`, `updated_at`, `created_at` | | `sort_direction` | Sort direction | `asc` (default) or `desc` | | `search` | Title search | Text; matches the title only | | `fields_filter[]` | Returned fields | Field names. `id` and `title` are always included | ### Episode fields Create fields: `podcast_id`, `title`, `subtitle`, `description`, `show_notes`, `show_notes_md`, `authors`, `cover_image`, `facebook_image`, `number`, `season`, `slug`, `explicit`, `guid`, `external_url`, `publication_type`, `intro_outro_include`, `video_content_rating`, `video_thumbnail_source`, `keywords[]`, `labels[]`, `contributor_ids[]`, `transcription[]` with `start`, `end`, `text`, and `speaker_id`, and `chapter_marks[]` with `title`, `start_time`, `url`, and `image`. Update fields: the create fields plus `published_at`. ### Episode errors | Status | Message | | ------ | --------------------------------------------------------------- | | `404` | `The episode with id could not be found.` | | `422` | The validation message of the failed create, update, or delete. | ## Related pages * [REST API media uploads and encoding](/documentation/connect-and-administer/integrations/rest-api/rest-api-media-uploads-and-encoding.md) attaches audio to an episode. * [REST API episode content](/documentation/connect-and-administer/integrations/rest-api/rest-api-episode-content.md) manages chapter marks, contributors, and more. * [REST API authentication and errors](/documentation/connect-and-administer/integrations/rest-api/rest-api-authentication-and-errors.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-podcasts-and-episodes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.