BitePods

Searches the public podcast directory by show name. Use it when you have a name rather than a link. Each hit carries the show's RSS feed as `sourceUrl` — hand that to `list_episodes`. It searches shows, never episodes: there is no index of episode titles to search, so finding one episode means listing a show's episodes and matching the title yourself. Shows Apple rates explicit are left out. Returns `{ shows }` — id, name, author, artwork, feed, and the `sourceUrl` to list episodes from. Usually followed by: list_episodes with a show's sourceUrl.

The most-subscribed shows in a country, ranked. Useful as a starting point when nothing specific was named, and as a way to check that a show is the well-known one rather than a similarly named feed. Country defaults to the one the request came from. Returns `{ country, shows }`, each show carrying its 1-based `rank`. Usually followed by: list_episodes with a show's sourceUrl.

Episodes of a show, newest first, from its RSS feed or its Apple Podcasts page. Feeds are read up to 60 items — that is the cap, not a page you can walk past. Each episode carries a `clipUrl`: pass it back as `url` to `create_clip` or `get_transcript` and the right episode is clipped, whatever the show's pages look like. Errors with `not_a_show` if the URL is one episode rather than a show. An episode from a feed may also carry `chapters` — the publisher's own timestamp index, read out of the show notes, as `{ startSeconds, title }` in the order they happen. That is a human being naming the parts of their own episode, so it is the cheapest way to find a moment worth clipping: pick a chapter, pass its `startSeconds` to `create_clip` as `start`, and the next chapter's `startSeconds` as `end`. Roughly two shows in five publish one, and a show that doesn't simply has no `chapters` field. Returns `{ show, episodes, total, offset, limit, hasMore }`. An episode may carry `chapters`. Usually followed by: An episode's own `chapters` are the quickest way to a moment; get_transcript reads the words where a show publishes one. Then create_clip.

Turns any pasted link into something clippable, and says which of three things it is: `episode` (one playable thing, ready for create_clip), `show` (a feed or channel — a preview of its episodes, with list_episodes for the rest), or `unresolved` (nothing playable was found, and why). Answering `unresolved` is a real answer, not a failure: clipping the wrong audio confidently is worse. Spotify links resolve to the same episode in the show's own feed, because nothing else can play Spotify. Returns `{ type: 'episode' | 'show' | 'unresolved', … }` — always 200; read `type`. Usually followed by: create_clip for an episode, list_episodes for a show.

The episode's own transcript with absolute timestamps in seconds, so a line's `start` is a number you can pass straight to create_clip. This is how you find the moment worth clipping: read the transcript, choose the span, clip it. These are the publisher's transcripts (Podcasting 2.0 `<podcast:transcript>`), and only about one show in six ships one. There is no speech-to-text here — deliberately, and it is not coming — so an episode without one answers `available: false` with a reason rather than an approximation. Cue-timed, not word-timed: a long cue is split into readable lines and `estimated: true` says the split points are interpolated between two known times. Returns `{ available, lines, lineCount, truncated, estimated, episode, … }`; `available: false` carries `reason`. Usually followed by: create_clip with a line's start and end.

Marks a span of an episode and hands back the links that play it. Nothing is downloaded, transcoded or re-hosted: a clip is a pointer — the publisher's own URL plus an in and an out point — so the whole clip fits in its link and this call cannot fail for reasons of storage. The episode's name and cover are resolved and returned, so you can check you clipped what you meant to before sharing the link. Times are seconds from the start of the episode, decimals allowed. Returns `{ clip, links: { page, short, sourceAtMoment, mp3 }, shareText }`. Usually followed by: share links.short (or links.page); links.mp3 downloads the audio.

What a short id stands for: the episode, the two times, the links, and how many times the clip has been played. The id is the `/x/<id>` part of a short link. Play counts are approximate by design — a per-clip counter with no atomic increment behind it, not an audit trail. Returns `{ clip, links, plays, shareText }`.