Get a key
Sign in, open Profile → API and create a key. It is shown once; store it the way you store any other production credential. Everything below assumes it is in H2T_API_KEY.
1. Start a recording
Send a file, or send a url and we will fetch it. The answer comes back immediately with status: "queued" — the work happens after the response.
curl https://heartotext.com/api/public/v1/transcriptions \
-H "Authorization: Bearer $H2T_API_KEY" \
-H "Idempotency-Key: 9f1c2b7a-1f2e-4a0c-9f0b-2c1d3e4f5a6b" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/episode-42.mp3","language":"en"}'{
"id": "0f2f5f6a-2c6c-4f4e-9d1e-5d8f2a1b3c4d",
"status": "queued",
"title": null,
"language": "en",
"duration_seconds": null,
"created_at": "2026-09-19T10:11:12+00:00",
"updated_at": "2026-09-19T10:11:12+00:00",
"source": { "type": "url", "name": null, "url": "https://example.com/episode-42.mp3" },
"workspace": null,
"progress": { "step": null, "percent": null, "indeterminate": false },
"failure_reason": null
}2. Poll it
Ask for the recording until its status is completed or failed. Every five seconds is plenty; see polling for the intervals we recommend.
curl https://heartotext.com/api/public/v1/transcriptions/$ID \
-H "Authorization: Bearer $H2T_API_KEY"3. Read the transcript
Segments come back in reading order, a page at a time. Follow next_cursor while has_more is true — or ask for the whole thing as a file from /export.
curl "https://heartotext.com/api/public/v1/transcriptions/$ID/segments?limit=200" \
-H "Authorization: Bearer $H2T_API_KEY"
# or as a file
curl "https://heartotext.com/api/public/v1/transcriptions/$ID/export?format=srt" \
-H "Authorization: Bearer $H2T_API_KEY" -o episode-42.srt{
"data": [
{ "index": 0, "start": 0.0, "end": 4.2, "speaker": "A", "text": "Welcome back to the show." },
{ "index": 1, "start": 4.2, "end": 9.8, "speaker": "B", "text": "Glad to be here." }
],
"has_more": true,
"next_cursor": "eyJvIjoyMDB9"
}The whole thing
That is the integration. Everything else in these pages is about doing it well: retrying safely with idempotency keys, staying inside the rate limits, and handling the errors you will eventually meet.