---
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 |
| GET | `/podcasts/{show_id}` | Single show with episode counts |
| GET | `/podcasts/{show_id}/episodes` | Episodes for a show (filters, pagination) |
| GET | `/podcast-episodes/{episode_id}` | Single episode with parent show summary |

## 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. Premium episodes do not expose media URLs, full transcripts, or RSS enclosures publicly.

Episode `rss_status` values: `included`, `excluded`, `missing_enclosure` — useful when debugging empty RSS feeds.

Users with `edit_posts` receive authenticated context (drafts/private/premium metadata), still without exposing premium media URLs on anonymous requests.

## 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.
