Podcasts

The Podcast resource is the root container for a show. It contains metadata (title, description, cover art) and configuration for the RSS feed.

Creating a Podcast

You can create a new podcast from scratch or import one from an existing RSS feed.

Method 1: Create New

POST /v1/podcasts
x-virtual-user: user_123
Content-Type: application/json
 
{
  "title": "My Tech Talk",
  "description": "<p>A show about technology.</p>",
  "language": "en-us",
  "categories": ["Technology", "Tech News"],
  "ownerName": "John Doe",
  "ownerEmail": "[email protected]"
}

Method 2: Import from RSS

See the Importing a Podcast documentation for details on how to import an existing podcast using its RSS feed URL.

Publishing & RSS

By default, a new podcast is in draft status. It will not have a public RSS feed until it is published.

1. Validate

Before publishing, you can run a validation check to ensure all required fields are present.

POST /v1/podcasts/{id}/validate

2. Publish

Publishing generates the RSS feed URL.

POST /v1/podcasts/{id}/publish

Response:

{
  "rssUrl": "https://feeds.ichos.dev/r/..."
}

Cover Art

Like audio, cover art is handled via a 2-step process (Get Upload URL -> Upload).

1. Get Upload URL: GET /v1/podcasts/{id}/cover/put
2. Upload: PUT the image file to the returned URL.
3. Automatic: The system detects the upload and updates the podcast record automatically (no “finalize” step needed for images).

Alternatively, you can pull from a URL:

POST /v1/podcasts/{id}/cover/pull
{ "url": "https://example.com/image.jpg" }