# spoken.md

> Podcast transcripts as clean markdown. Built for AI agents.

## API

Base URL: https://spoken.md
Authentication: `x-api-key` header
Free demo key: `pt_demo` (returns only the demo episode)

### Search episodes

GET /search?q={query}

Search by text or paste a URL (Spotify, YouTube, etc.). Returns JSON array of matching episodes with `id`, `title`, `podcast`, and `date`. Requires API key, no credits charged.

### Get transcript

GET /transcripts/{id}

Returns markdown with speaker names and timestamps. Use an `id` from search results.
Costs 1 credit on first fetch. Repeat fetches of the same episode are free. Errors are never charged.

Response headers include `X-Credits-Remaining` and `X-Credits-Charged`.

### Top up credits

POST /top-up?key={your_api_key}

Redirects to Stripe Checkout to purchase more credits for an existing key. The `top_up_url` in 402 responses points here — use POST, not GET.

### Error codes

- 401: Missing or invalid API key
- 402: No credits remaining (response includes `top_up_url` — POST to it)
- 404: Episode not found
- 502: Upstream error

## Pricing

New customers (POST /buy):
- 100 for $15 ($0.15/ea)
- 500 for $50 ($0.10/ea) — pass ?pack=500
- 2,000 for $160 ($0.08/ea) — pass ?pack=2000

Returning customers (POST /top-up?key={key}):
- 100 for $10 ($0.10/ea)
- 500 for $40 ($0.08/ea) — pass &pack=500
- 2,000 for $120 ($0.06/ea) — pass &pack=2000

## Integration

- OpenAPI spec: https://spoken.md/.well-known/openapi.json
- Agent skill: https://spoken.md/.well-known/skills/spoken-md/SKILL.md