Episode Categories REST API
Endpoints for managing per-show episode categories. Episode categories are internal labels defined per show — they are separate from iTunes categories and do not appear in the RSS feed.
Both endpoints require manage_options and a valid X-WP-Nonce header.
GET /benecaster/v1/episode-categories
Returns all episode categories defined for a show.
Auth: manage_options + X-WP-Nonce
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
show_id |
int | Yes | The show to list categories for |
Response:
{
"items": [
{ "id": 1, "name": "Interviews", "slug": "interviews", "episode_count": 42 },
{ "id": 2, "name": "Solo Episodes", "slug": "solo-episodes", "episode_count": 18 },
{ "id": 3, "name": "Bonus Content", "slug": "bonus-content", "episode_count": 7 }
],
"total": 3
}
Item fields:
| Field | Type | Description |
|---|---|---|
id |
int | Category database ID |
name |
string | Display name |
slug |
string | URL-safe slug, auto-derived from name |
episode_count |
int | Number of published episodes in this show currently tagged with this category |
Errors:
| Code | HTTP | Condition |
|---|---|---|
show_not_found |
404 | show_id does not exist |
invalid_param |
400 | show_id missing or not an integer |
POST /benecaster/v1/episode-categories
Creates a new episode category for a show.
Auth: manage_options + X-WP-Nonce
Body:
{
"show_id": 45,
"name": "Listener Q&A"
}
Response: 201 Created
{
"id": 4,
"name": "Listener Q&A",
"slug": "listener-qa",
"episode_count": 0
}
slug is auto-derived server-side from name (slugified, lowercased, spaces to hyphens). Made unique within the show by appending -2, -3, etc. if needed.
Errors:
| Code | HTTP | Condition |
|---|---|---|
show_not_found |
404 | show_id does not exist |
invalid_param |
400 | name missing, empty, or exceeds 255 characters |
Assigning Categories to Episodes
Categories are assigned via the episode object. When creating or updating an episode, include a category_ids array in the body:
{
"category_ids": [1, 4]
}
category_ids is an array of category database IDs. Pass an empty array to remove all category assignments from an episode. Category IDs that do not belong to the episode’s show are silently ignored.
The category_ids field is also returned in episode objects from GET /shows/{id}/episodes and GET /episodes/{id}.