Episodes REST API

Endpoints for creating, reading, updating, and deleting episodes, including each episode’s tier availability, and for managing per-show episode type definitions. All endpoints require manage_options and a valid X-WP-Nonce header unless noted.

---

Episodes

GET /benecaster/v1/shows/{id}/episodes

List episodes for a show. Supports filtering, sorting, and pagination.

Parameters:

Response:

{
  "items": [
    {
      "id": 201,
      "show_id": 45,
      "title": "Ep 84: Interview with Sarah Chen",
      "episode_number": 84,
      "season_number": null,
      "episode_type": "full",
      "status": "publish",
      "post_date": "2026-11-03 09:00:00",
      "duration": "47:23",
      "file_size": 44368896,
      "audio_url": "https://buzzsprout.com/ep84.mp3",
      "artwork_url": "https://...",
      "category_ids": [1, 3],
      "availability": {
        "premium": "2026-11-03 09:00:00",
        "basic": "2026-11-10 09:00:00",
        "free": "2026-11-17 09:00:00"
      },
      "uses_show_defaults": false,
      "download_count": 342,
      "is_imported": false,
      "created_at": "2026-11-01 14:00:00",
      "updated_at": "2026-11-03 09:00:00"
    }
  ],
  "total": 83,
  "pages": 5,
  "per_page": 20,
  "page": 1
}

post_date, created_at and updated_at are the WordPress post’s own dates, so they are in the site’s time zone, as WordPress stores them.

---

POST /benecaster/v1/episodes

Create a new episode.

Body:

{
  "show_id": 45,
  "title": "Ep 84: Interview with Sarah Chen",
  "description_rss": "This week I chat with Sarah Chen about...",
  "content": "<p>Full show notes here...</p>",
  "episode_number": 84,
  "season_number": null,
  "episode_type": "full",
  "explicit": "inherit",
  "author": null,
  "audio_url": "https://buzzsprout.com/ep84.mp3",
  "video_url": null,
  "preview_url": null,
  "embed_audio": null,
  "embed_video": null,
  "media_type": "audio",
  "duration": "47:23",
  "file_size": 44368896,
  "mime_type": "audio/mpeg",
  "artwork_url": null,
  "web_visible_datetime": "2026-11-03T09:00:00",
  "availability": {
    "premium": "2026-11-03 09:00:00",
    "basic": "2026-11-10 09:00:00",
    "free": "2026-11-17 09:00:00"
  },
  "use_show_defaults": false,
  "visibility_mode": "inherit",
  "tier_visibility": null,
  "category_ids": [1, 3],
  "references": [],
  "guests": [],
  "external_links": [],
  "post_status": "draft"
}

Response: 201 Created with the full episode object.

Every check (episode type, recorded date, audio variants) runs before anything is written, so a 400 means no episode was created.

Custom field values are not part of the episode API. Read and write them through their field groups with benecaster_get_episode_custom_fields(), benecaster_get_field() and benecaster_update_field(). A request that includes a custom_fields key is accepted and the key is ignored, like any other unknown key.

Field notes:

The explicit field

explicit is a three-value string enum — "inherit", "yes", or "no" — on both the request and the response.

• "inherit" (the default) uses the show’s Explicit setting.
• "yes" marks this episode explicit regardless of the show.
• "no" marks this episode clean regardless of the show.

Unrecognised values coerce silently to "inherit" rather than erroring, so an unfamiliar future value falls back to the show default instead of leaking into the feed.

The show-level value uses a different enum — clean / yes / explicit — because Apple’s wording distinguishes the last two. The episode side does not mirror it, since Apple reads both as explicit and an episode override only ever needs to say explicit or clean.

---

GET /benecaster/v1/episodes/{id}

Get a single episode with all metadata.

Response: Full episode object — same shape as items in the list response plus computed fields: feed_urls, source_guid (for imported episodes), source_link (read-only string; the imported item’s RSS <link>, its page on the old host, '' when there is none — not in the list response and not accepted on create/update), is_imported.

references holds each reference exactly as stored — {id, reference_id, label, library_label, url, description, display_label, group_id, display_order}. label is the resolved display label (this episode’s override when set); library_label is the library item’s own label. The array is not passed through the benecaster_episode_references filter, so an add-on that rewrites URLs on the episode page does not change what this returns.

unrecognised_availability lists the episode’s access under a name that is none of the show’s tiers, public, the follower slug or a buy-up’s: usually an episode sold on its own, or a tier or add-on since removed. Each entry is {slug, available_datetime}, in the site’s time zone. These are the entries the editor’s Access tab shows under Other Access, and they are not in the availability map. [] when there are none.

The explicit field is the episode’s own override, not the resolved value. To know what the feed will actually emit, resolve it against the show’s setting — server-side that is EpisodeMeta::get_effective_explicit(); over REST, read the show’s Explicit value and apply inherit yourself.

---

PUT /benecaster/v1/episodes/{id}

Update an episode. All fields are optional:

• A field sent as "" is cleared.
• A field sent as null, or left out, is left unchanged.
• Every check (episode type, recorded date, a move’s conflicting fields, audio variants such as an unknown tier in invalid_tier_slug / invalid_audio_variants) runs before anything is written, so a 400 leaves the episode exactly as it was: no title, content, post_status or post_date change is applied.

Field notes:

Response: Updated episode object.

Moving an episode

Send another show’s show_id to move the episode there. The move runs before anything else in the request, so the rest of the request applies to the episode on its new show.

• Its availability is cleared. The episode is in no feed of either show until you give it dates on the new show.
• Audio versions are kept only for tiers the new show has.
• An episode type the new show lacks becomes full.
• Episode and season numbers are unchanged.
• References are added to the new show’s reference library.
• Download history stays with the old show.

On success, the response gains a move object describing what happened:

"move": {
  "from_show_id": 45,
  "to_show_id": 52,
  "availability_cleared": true,
  "dropped_audio_variants": ["premium"],
  "episode_type_reset_from": "interview",
  "credit_source_cleared": false,
  "references_moved": 3
}

dropped_audio_variants lists the tier slugs whose audio versions were removed. episode_type_reset_from is the old type when it was reset to full, otherwise null. credit_source_cleared is true when the episode’s stamped credit came from a template the new show doesn’t have; the stamped text itself stays. references_moved is how many references moved into the new show’s library.

Errors:

Remove each blocker first: a required buy-up or buy-up access on the episode’s Access tab, and a standalone sale through its own product or, if nothing sells it any more, with DELETE /episodes/{id}/unrecognised-availability/{slug} (below).

The move fires benecaster_episode_move_before and benecaster_episode_move_after, and add-ons can add their own blockers with benecaster_episode_move_blockers.

---

DELETE /benecaster/v1/episodes/{id}/unrecognised-availability/{slug}

Remove one entry from the episode’s unrecognised_availability: the Remove access action under Other Access on the Access tab. It takes effect immediately and clears the show’s feed cache. Listeners who held access under that name lose the episode, so remove one only when nothing sells it any more. It is a route of its own, never a PUT field, so a removal can’t ride along with a save.

Response: 200 with { "removed": true, "unrecognised_availability": [ ... ] }, the entries that remain.

---

DELETE /benecaster/v1/episodes/{id}

Delete an episode and all associated availability records.

Response: 200 OK with { "deleted": true }

---

POST /benecaster/v1/episodes/{id}/detect-metadata

Detect the duration, file size and format of a media file. Makes a HEAD request for the size and type, then reads the start of the file for the duration. Requires manage_options. It returns what it found and stores nothing; the episode editor’s Detect button puts the values into the form, and they are saved with the episode.

Body:

Response:

{
  "url": "https://media.example.com/episode-42.mp3",
  "file_size": 44368896,
  "mime_type": "audio/mpeg",
  "duration": "47:23",
  "duration_seconds": 2843
}

file_size, mime_type, duration and duration_seconds are each null when the file’s response did not give that value.

Errors:

---

Availability

Availability has no endpoint of its own. It is the availability field on the episode, read from any episode response and written with POST /episodes or PUT /episodes/{id}.

"availability": {
  "premium": "2026-11-03 09:00:00",
  "basic": "2026-11-10 09:00:00"
}

The times are in the site’s time zone, not UTC. That holds in both directions, because they are the values a podcaster sees and types in the episode editor. Benecaster converts them to UTC when it saves them. Send site-local times: a time already converted to UTC is converted again, and the episode unlocks early or late by the site’s offset. See Dates, Times and Time Zones.

Reading. The map holds one key per tier that has a date. A tier with no date is left out of the map, not returned as null. Buy-ups are left out too. They are set separately, with the required_buyups field, an array of buy-up IDs.

Writing. The map you send is the episode’s whole set of tier dates. Each tier with a date is created or updated. A tier of the show — from its tier mapping, or its built-in membership tiers — that you leave out, or send as null or "", loses its date and leaves that tier’s feed; {} clears every tier. A row that is not one of the show’s tiers, such as the one a required buy-up keeps, is never removed this way. Leave availability out of the request altogether and the dates are not changed. Writing fires the benecaster_availability_datetimes filter before the rows are saved and benecaster_availability_set after.

Following the show’s defaults

Every episode response carries uses_show_defaults — true while the episode’s tier dates follow the show’s default availability.

POST /episodes and PUT /episodes/{id} accept use_show_defaults:

• true works the tier dates out from the show’s default availability against the episode’s current publish date, and the episode follows the defaults from then on: its dates are worked out again on every save. Any availability map in the same request is ignored. On a show with no default availability, true applies nothing, and the episode does not follow.
• false stops following. So does sending explicit dates, and on PUT, so does sending any availability map.
• Absent: on POST, a request with neither use_show_defaults nor any dates follows the defaults. On PUT, a request with neither changes nothing.

The defaults themselves are the show’s default_availability and default_release_time fields, on GET and PUT /benecaster/v1/shows/{id}:

"default_availability": {
  "tiers": {
    "premium": { "offset_days": 0 },
    "basic": { "offset_days": 7 }
  }
},
"default_release_time": "09:00"

offset_days is how many days after release the tier gets a new episode, from 0 to 365; a tier left out never gets one. GET always returns tiers as an object, {} when the show has no defaults. default_release_time is the time of day the unlocks use, as HH:MM; "" clears it, so unlocks use each episode’s own publish time, and any other value is ignored.

---

Member Thanks

GET /benecaster/v1/episodes/{id}/member-thanks

Returns a list of members to thank for the episode, using the configured query strategy.

Parameters:

Response:

{
  "episode_id": 201,
  "show_id": 45,
  "query_type": "random_cycling",
  "is_accepted_list": false,
  "members": [
    {
      "user_id": 1042,
      "display_name": "Sarah Chen",
      "tier_slug": "premium",
      "joined_at": "2026-09-14T11:32:00"
    }
  ]
}

is_accepted_list is true when the Podcast Workflow add-on is active and a list has been accepted for this episode via the Episode Workbench — in that case the accepted list is returned regardless of query_type and count.

Errors:

---

Episode Types

Episode types are per-show labels that map to iTunes episode types (full, trailer, bonus). The default types (Full Episode, Trailer, Bonus, Sponsored) are created automatically for every new show.

GET /benecaster/v1/shows/{id}/episode-types

Returns all episode type definitions for a show.

Response:

[
  { "slug": "full", "label": "Full Episode", "itunes_type": "full", "sort_order": 0, "is_default": true, "episode_count": 82 },
  { "slug": "trailer", "label": "Trailer", "itunes_type": "trailer", "sort_order": 1, "is_default": true, "episode_count": 1 },
  { "slug": "bonus", "label": "Bonus", "itunes_type": "bonus", "sort_order": 2, "is_default": true, "episode_count": 0 },
  { "slug": "sponsored", "label": "Sponsored", "itunes_type": "full", "sort_order": 3, "is_default": true, "episode_count": 0 }
]

episode_count is used by the episode editor delete/reassign modal to warn when deleting a type that has episodes.

---

POST /benecaster/v1/shows/{id}/episode-types

Creates a new episode type for a show.

Body:

{
  "label": "Sponsored Bonus",
  "itunes_type": "full"
}

slug is auto-derived server-side from label. Made unique within the show by appending -2, -3, etc. if needed.

Response: 201 Created with the type object.

Errors:

---

PUT /benecaster/v1/shows/{id}/episode-types/{slug}

Updates the label and/or iTunes mapping of an existing type. Slug is immutable — episodes store the slug in _benecaster_episode_type and renaming it would orphan existing episodes.

Body: label and/or itunes_type — all fields optional.

Response: Updated type object.

---

DELETE /benecaster/v1/shows/{id}/episode-types/{slug}

Deletes an episode type. All episodes using this type are bulk-reassigned to another type in the same transaction.

Required query param: reassign_to — slug of the type to reassign to.

Response:

{
  "deleted": "sponsored",
  "reassigned_count": 14
}

Errors:

Example:

DELETE /wp-json/benecaster/v1/shows/45/episode-types/sponsored?reassign_to=full

---

Feed Sync (Recurring)

POST /benecaster/v1/shows/{id}/sync

Trigger a manual feed sync — imports only new episodes not yet in WordPress (episodes whose GUID is not already stored). Premium only.

Body:

{
  "source_feed_url": "https://feeds.buzzsprout.com/12345.rss"
}

Response:

{
  "episodes_found": 86,
  "episodes_new": 3,
  "drafts_created": 3,
  "draft_ids": [201, 202, 203],
  "log_id": 47
}

For one-time bulk import of all episodes during setup, use POST /shows/{id}/import (see Setup Wizard REST API) instead.

---

Filters