{
  "markdown": "# Spoken — podcast transcripts as clean Markdown, built for AI agents\n\n[Spoken](https://spoken.md) is a transcript API that turns any published podcast into clean Markdown with **real speaker names** — not \"Speaker 1.\" One API call returns named, timestamped text, ready for LLMs, RAG pipelines, summarizers, and search.\n\nIt's a transcript *retrieval* API, not a speech-to-text service: it works on already-published podcasts, so you skip uploading audio, running diarization, and mapping anonymous speaker labels by hand. For published shows that's typically **5–10× cheaper** than running the audio through a transcription service.\n\n- 🎙️ **Real speaker names**, resolved automatically\n- 📄 **Clean Markdown** with timestamps, tuned for LLM context windows and RAG chunking\n- 🔎 **Search** by text query or paste a Spotify/YouTube URL\n- 💳 **Pay-per-use credits** — no subscription, failed calls never charged, repeat fetches free\n- 🤖 **Agent-native** — ships with an [Agent Skill](./SKILL.md), [`agents.md`](https://spoken.md/agents.md), [`llms.txt`](https://spoken.md/llms.txt), and an [OpenAPI spec](https://spoken.md/.well-known/openapi.json)\n\nGet a key at **[spoken.md](https://spoken.md)** — or try it free with the demo key `pt_demo` (search works fully; transcripts limited to the demo episode).\n\n## Quickstart\n\n```sh\n# 1. Find an episode (by text, or paste a Spotify/YouTube URL)\ncurl -s 'https://spoken.md/search?q=huberman+sleep' \\\n  -H 'x-api-key: pt_demo'\n\n# 2. Fetch the transcript as Markdown\ncurl -s 'https://spoken.md/transcripts/1000651996090' \\\n  -H 'x-api-key: pt_demo'\n```\n\nThe transcript comes back as Markdown with named speakers and timestamps:\n\n```md\n**John Smith** (0:00)\nWelcome to the show. Today we're talking about...\n\n**Jane Doe** (0:15)\nThanks for having me.\n```\n\n## Endpoints\n\n| Method & path | What it does | Credits |\n| --- | --- | --- |\n| `GET /search?q={query or URL}` | Find episodes; returns `id`, `title`, `podcast`, `podcastId`, `date` | 0 |\n| `GET /podcasts/{podcastId}/episodes` | List a show's full back catalog; returns every episode's `id`, `title`, `date` | 0 |\n| `GET /transcripts/{id}` | Return the Markdown transcript | 1 on first fetch, 0 on repeat |\n| `GET /balance` | Current credit balance + usage history | 0 |\n| `POST /buy` | New-key checkout (Stripe) | — |\n| `POST /top-up?key={key}` | Returning-customer top-up (Stripe) | — |\n\nAuth is the `x-api-key` header. Responses include `X-Credits-Remaining` and `X-Credits-Charged`. See [`agents.md`](https://spoken.md/agents.md) for the full error table and response shapes.\n\n## Examples\n\n- [`examples/podcast_summarizer.py`](./examples/podcast_summarizer.py) — fetch a transcript and summarize it\n- [`examples/rag_pipeline.py`](./examples/rag_pipeline.py) — chunk a transcript for a vector store / RAG\n- [`examples/quickstart.sh`](./examples/quickstart.sh) — search → transcript in two curl calls\n- [`examples/archive-show.sh`](./examples/archive-show.sh) — archive a show's entire back catalogue, one file per episode\n\n## Use as an MCP server\n\nThis repo includes **`spoken-mcp`**, a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Spoken to MCP-compatible agents (Claude Desktop, Cursor, Cline, …). It provides four tools:\n\n| Tool | Description |\n| --- | --- |\n| `search_podcasts` | Find episodes by text or a pasted Spotify/YouTube URL |\n| `list_episodes` | List a show's entire back-catalog from a `podcast_id` |\n| `get_transcript` | Fetch an episode's transcript as Markdown with real speaker names |\n| `get_balance` | Check remaining credits |\n\nAdd it to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"spoken\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"spoken-mcp\"],\n      \"env\": { \"SPOKEN_API_KEY\": \"pt_your_key\" }\n    }\n  }\n}\n```\n\n`SPOKEN_API_KEY` defaults to `pt_demo` (search works fully; transcripts limited to the demo episode). Get a real key at [spoken.md](https://spoken.md).\n\nRun from source instead:\n\n```sh\nnpm install && npm run build\nSPOKEN_API_KEY=pt_your_key node dist/index.js\n```\n\n## Use with AI agents\n\nSpoken is designed to be called by agents. Point your agent at the [Agent Skill](./SKILL.md) (also served at `https://spoken.md/.well-known/skills/spoken-md/SKILL.md`), or hand it [`agents.md`](https://spoken.md/agents.md). The [OpenAPI spec](https://spoken.md/.well-known/openapi.json) makes it easy to wrap as a tool for any function-calling or MCP-compatible client (Claude, GPT, Cursor).\n\n## Pricing\n\nPay-per-use credits, no subscription. New keys: 100 for $15, 500 for $50, 2,000 for $160. Machine-readable at [spoken.md/pricing.md](https://spoken.md/pricing.md).\n\n## Links\n\n- Website & docs: **https://spoken.md**\n- Agent instructions: https://spoken.md/agents.md\n- OpenAPI spec: https://spoken.md/.well-known/openapi.json\n- LLM-friendly overview: https://spoken.md/llms.txt\n\n---\n\nSpoken is built and maintained at [spoken.md](https://spoken.md).\n",
  "bytes": 4983,
  "sha": "d51de788b41a539867519df08a88788d0e3fab87baa3d4fce2dc510d3c331a76",
  "repo_slug": "spokenmd/spoken",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_spokenmd_spoken_47799184/readme"
}