# PlayLetter API
> Machine-readable access to PlayLetter, an audio-first newsletter marketplace. Discover newsletters + episodes free; buy clean transcripts and voiced audio.

## Free (discovery)
- GET /api/v1/catalog?q=&category=&city=&limit= — search the marketplace
- GET /api/v1/newsletter/<domain> — one newsletter + recent episodes
- GET /api/v1/fresh?limit= — newest episodes across the marketplace
- GET /api/v1/episode/<id> — episode metadata

## Paid (Pro key or x402 micropayment)
- GET /api/v1/transcript/<id> — clean full transcript of an episode
- GET /api/v1/audio/<id> — voiced mp3 URL + duration

## Get access
- POST /api/keys {email} → free key (plk_…). Use as Authorization: Bearer <key>.
- POST /api/billing/checkout {key} → Stripe upgrade to Pro ($49/mo).
- x402: paid routes answer HTTP 402 with USDC-on-Base payment requirements for agent-native pay-per-call.

## MCP (for AI agents)
- POST /mcp (JSON-RPC 2.0). Tools: about, get_free_key, upgrade_to_pro, search_newsletters, get_newsletter, list_fresh, get_episode, get_transcript (paid), get_audio (paid).

Contact: support@playletter.com