Castro Podcasts

Get Podcast

Look up a Castro podcast by exactly one identifier. Provide exactly one of: - public_id: the podcast's Castro public id (a UUID). - feed_url: the podcast's RSS feed URL. - itunes_id: the podcast's iTunes id. Returns the podcast's metadata: title, author_name, feed_url, site_url, artwork_url, description, itunes_id, itunes_category, public_id, short_id. If the feed has ended and was replaced, the current (successor) podcast is returned. If you look up

Get Episode

Look up a Castro episode by exactly one identifier. Provide exactly one of: - public_id: the episode's Castro public id. - short_id: the episode's Castro short id (the code in a share link). - enclosure_url: the episode's audio (media) URL, e.g. the `enclosureUrl` from an Overcast OPML export or an RSS `<enclosure url="...">`. Castro normalizes it the same way it does on feed ingest, so tracking prefixes and HTML-entity encoding don't have to match

Get Episode By Guid

Look up a Castro episode by its RSS `guid` within a specific podcast. A guid is only unique within a podcast, so along with `guid` you must provide exactly one podcast scope: - podcast_public_id: the podcast's Castro public id, or - itunes_id: the podcast's iTunes id, or - feed_url: the podcast's RSS feed URL. Returns the same episode metadata as `get_episode`.

Get Episode By Title

Look up a Castro episode by its title and publish date within a podcast. Use this when you don't have a Castro id, an RSS `guid`, or a media URL — e.g. matching an episode from another app's export by what it shows. Prefer `get_episode` with `enclosure_url` when you have the audio URL; this is the fallback. Both `title` and `pub_date` are required: - title: the episode title as it appears in the RSS `<title>`. - pub_date: the RSS `<pubDate>` (an ISO-8601 / RFC-2

Get Episodes By Enclosure Urls

Resolve many episodes at once by their audio (media) URLs. Use this to map a batch of `enclosureUrl`s (e.g. every episode in an Overcast OPML export) to Castro ids in a single call, instead of calling `get_episode` once per URL. Be deliberate about how you call it — it is an unauthenticated bulk endpoint: - Pass at most 50 URLs per call. Split a larger set into successive batches of <=50. - Issue the batches sequentially, not many in parallel: Castro throttl

Get Episodes By Public Ids

Resolve many episodes at once by their Castro public ids. Use this to fetch metadata for a batch of episode public ids (e.g. every episode referenced by a `.castrobackup` file) in a single call, instead of calling `get_episode` once per id. Be deliberate about how you call it — it is an unauthenticated bulk endpoint: - Pass at most 200 public_ids per call. Split a larger set into successive batches of <=200. - Issue the batches sequentially, not many in para

Get Podcasts By Public Ids

Resolve many podcasts at once by their Castro public ids. Use this to map a batch of podcast public ids (e.g. every podcast referenced by a `.castrobackup` file) to their current RSS feed URLs in a single call, instead of calling `get_podcast` once per id. Be deliberate about how you call it — it is an unauthenticated bulk endpoint: - Pass at most 200 public_ids per call. Split a larger set into successive batches of <=200. - Issue the batches sequentially,

Get Backup Format

Return the spec for Castro's `.castrobackup` library-export files. Call this before reading, interpreting, or generating a `.castrobackup` file. A backup is a single JSON object (Castro's `UserData` export) holding the user's podcasts, episodes, queue, inbox, history, listening sessions, folders, and app preferences as a graph of Castro public ids. Returns Markdown documenting the top-level shape, the two different date encodings used in the file, every section and its

Get Overcast Import Guide

Return the guide for translating an Overcast OPML export to a backup. Call this when converting an Overcast `.opml` subscriptions export into a Castro `.castrobackup` file. Pair it with `get_backup_format` (the destination schema). Returns Markdown documenting the Overcast OPML structure (feeds, episodes, and the Queue playlist), the recipe for resolving Overcast episodes to Castro public ids directly from their `enclosureUrl` (in bulk, with title + pubDate as the p

Get Pocket Casts Import Guide

Return the guide for translating a Pocket Casts export to a backup. Call this when converting a Pocket Casts library into a Castro `.castrobackup` file. Pair it with `get_backup_format` (the destination schema). Returns Markdown documenting which Pocket Casts export to use (the ZIP'd SQLite *database export*, not the subscriptions-only OPML), the SQLite tables and columns to read (`podcasts`, `podcast_episodes`, `up_next_episodes`), the recipe for resolving episodes