---
title: REST API — Podcasts
menu_group: REST API
menu_order: 45
tab: REST API
tab_order: 45
requires_podcasts: true
summary: mediablaster/v3 podcast show and episode endpoints with public-safe premium stripping.
---

# REST API — Podcasts

Namespace: `/wp-json/mediablaster/v3`

Available when **Enable Podcasts** is on. Discovery index includes `features.podcasts` and `links.podcasts`.

## Endpoints

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/podcasts` | List podcast shows |
| POST | `/podcasts` | Create show (Application Password / cookie / bearer) |
| GET | `/podcasts/{show_id}` | Single show with episode counts |
| PUT/PATCH | `/podcasts/{show_id}` | Update show |
| POST | `/podcasts/{show_id}/validate` | Validate show for distribution |
| GET | `/podcasts/{show_id}/episodes` | Episodes for a show (SQL pagination) |
| POST | `/podcasts/{show_id}/episodes` | Create episode |
| GET | `/podcast-episodes/{episode_id}` | Single episode with parent show summary |
| PUT/PATCH | `/podcast-episodes/{episode_id}` | Update episode |
| POST | `/podcast-episodes/{episode_id}/validate` | Validate episode |
| GET | `/podcast-episodes/{episode_id}/transcript` | Public transcript (free published only) |
| GET | `/podcast-episodes/{episode_id}/chapters` | Public chapters JSON (free published only) |
| GET | `/podcast-episodes?search=` | Bounded episode search (block picker / automation) |

## Query parameters

**GET /podcasts**

- `include_episodes` (bool, default false)
- `episodes_per_show` (int, default 3)
- `episode_preview` (`latest` \| `featured`, default `latest`)
- `page`, `per_page`
- `search` — WordPress search (`s`) on show title, content, and excerpt

**GET /podcasts/{show_id}/episodes**

- `featured` (bool)
- `access` (`free` \| `premium`)
- `type` (`full` \| `trailer` \| `bonus`)
- `rss` (`included` \| `excluded` \| `missing_enclosure`)
- `page`, `per_page`

## Public vs authenticated

Unauthenticated requests return published public-safe content only. Public show objects never include `owner_email`. Episode counts only include viewer-visible episodes.

Premium/gated episodes do not expose media URLs, full transcripts, chapters, or RSS enclosures unless the viewer is entitled (WordPress session or MediaBlaster bearer token). Responses that depend on entitlements are privately cached (`Cache-Control: private`).

Episode objects include legacy `access` (`free`\|`premium`) plus a richer `entitlement` object.

Episode `rss_status` values: `included`, `excluded`, `missing_enclosure`.

Write routes require Podcast capabilities (`create_podcast_shows`, `edit_podcast_episode`, `publish_podcast_episodes`, etc.). Publishing requires the matching publish capability.

### Application Password example

```bash
curl -X POST "https://example.com/wp-json/mediablaster/v3/podcasts" \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Show","status":"draft","rss_enabled":true}'
```

## Normalized objects

Shows include id, slug, title, url, rss_url, artwork, **images** (Roku-sized variants), subtitle, description, host, credits, owner fields, language, copyright, app_category, explicit, rss settings, distribution_links, categories, tags, and episode_counts.

Episodes include id, slug, title, url, podcast_show summary, artwork, **images**, show_notes, publish_date, type/season/number, duration, explicit, access, featured, rss_status, canonical_audio/video (when allowed), transcript, chapters, guests, and tags.

### `images` (shows and episodes)

Same structure as [Content API `images`](rest-api-content.md#images). Generated from the show or episode featured image; episodes without artwork inherit the parent show attachment.

| Role key | Dimensions | Typical use |
|----------|------------|-------------|
| `portrait.square` | 200×200 | Podcast row tiles |

All landscape and portrait roles from the content API are also emitted when an attachment is available.

**Backward compatibility:** flat `artwork` remains the full-size URL. Prefer `images.portrait.square` (or other role keys) for TV slot-sized artwork.