spoken-md

# Podcast Transcript (spoken.md)

Search for podcast episodes and fetch transcripts as clean markdown with speaker names and timestamps.

## Steps

1. Find the episode:
   - If the user provided a numeric episode ID, skip to step 2
   - If the user provided a URL (Spotify, YouTube, etc.) or a text description, search for it:
     - `GET https://spoken.md/search?q={query or URL}`
     - Include header `x-api-key: {SPOKEN_API_KEY}` (use `pt_demo` if no key is set - returns demo episode only)
     - Show the user the results and let them pick, or pick the best match if unambiguous
   - If unclear what episode they want, ask

2. Fetch the transcript using the WebFetch tool:
   - URL: `https://spoken.md/transcripts/{id}`
   - Include header `x-api-key: {SPOKEN_API_KEY}` (use `pt_demo` if no key is set - demo episode only)

3. Handle the response:
   - **200**: Return the markdown transcript to the user
   - **401**: Tell the user they need an API key. They can get one at https://spoken.md (from $15 for 100 transcripts, with volume discounts)
   - **402**: Tell the user their credits are depleted. The response includes a `top_up_url` - they need to POST to it to buy more credits
   - **404**: Tell the user no transcript was found for that episode
   - **502**: Upstream error - suggest retrying in a moment

4. If the response includes `X-Credits-Remaining` header, mention how many credits remain. Note: `X-Credits-Charged: 0` means this episode was already fetched before (repeat fetches are free).

## Transcribing a whole show

To transcribe a podcast's entire back-catalog (e.g. "get me every episode of X"):

1. Get the show's `podcastId`. Every `/search` result includes one.
2. List every episode: `GET https://spoken.md/podcasts/{podcastId}/episodes` with the `x-api-key` header. This is free (metadata only) and returns a JSON `episodes` array, each with an `id`, `title`, and `date`.
3. Fetch each `id` through `https://spoken.md/transcripts/{id}` as in step 2 above. Each new episode costs 1 credit; repeat fetches are free. Make sure the key has enough credits for the whole show before starting.