API

One upload, one id, five formats. Keys for people, x402 for agents, and the same thing from a terminal or an MCP client.

Upload

curl -F file=@interview.m4a -F language=auto \
  -H "Authorization: Bearer $TYPEHEARD_API_KEY" \
  https://typeheard.pwa.pit.world/api/v1/transcripts

Answers 202 with { id, status, status_url, url }. Without a key you get the first 3 minutes free. tier=full refuses with 402 rather than quietly giving you a preview; tier=preview never spends.

Wait, then read

curl https://typeheard.pwa.pit.world/api/v1/transcripts/ID          # status: queued, running, done, failed
curl https://typeheard.pwa.pit.world/api/v1/transcripts/ID/txt      # also md, srt, vtt, json

Command line

curl -fsSL https://typeheard.pwa.pit.world/install.sh | sh                      # installs typeheard (Node 22.6+)

typeheard interview.m4a            # prints the text
typeheard talk.mp4 --format srt > talk.srt
typeheard login                    # saves an API key
typeheard tui                      # your transcripts, in the terminal

No install: npx -y @profullstack/typeheard interview.m4a.

MCP

{ "mcpServers": { "typeheard": { "command": "npx", "args": ["-y", "@profullstack/typeheard-mcp"],
  "env": { "TYPEHEARD_API_KEY": "th_…" } } } }

Tools: transcribe_file, get_transcript, list_transcripts, and list_webhooks, create_webhook, test_webhook, delete_webhook.

Webhooks

curl -H "Authorization: Bearer $TYPEHEARD_API_KEY" -H 'content-type: application/json' \
  -d '{"url":"https://example.com/hooks/typeheard","events":["transcript.*"]}' \
  https://typeheard.pwa.pit.world/api/v1/webhooks                   # answers { endpoint, secret }

typeheard POSTs transcript.completed and transcript.failed to your URL as CloudEvents JSON signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). data has the id, status, status_url and downloads links, never the text. Retried for about three days; dedupe on webhook-id. Manage them at Account → Webhooks, with typeheard webhooks, or under /api/v1/webhooks (/:id/test, /:id/rotate, /deliveries).

Agents without an account

Send the upload with no key. A metered caller over the free allowance gets 402 with an x402 offer; pay it and repeat the request with the payment header. One payment covers a file up to 60 minutes.

Keys

Make one at Account → API keys. It is shown once.