Results

Segments

GET /transcriptions/{id}/segments returns the transcript in reading order: one object per spoken stretch, with offsets in seconds from the start of the recording.

{
  "data": [
    { "index": 0, "start": 0.0,  "end": 4.24, "speaker": "A", "text": "Right, shall we start?" },
    { "index": 1, "start": 4.24, "end": 9.81, "speaker": "B", "text": "Yes -- I have the numbers here." }
  ],
  "has_more": false,
  "next_cursor": null
}

• index is the segment’s position in the recording, zero-based and continuous across pages. It is not a database identifier, and no identifier of ours ever crosses this boundary.
• start and end are seconds, to the millisecond.
• text is the transcript of that stretch, in the recording’s language.

Segments only exist once the recording is completed. Asking earlier gives you an empty page rather than an error, which is another reason to branch on status.

Paging through a long transcript

limit defaults to 100 and goes up to 1000. Keep following next_cursor while has_more is true. The cursor is opaque — pass it back exactly as you received it.

curl "https://heartotext.com/api/public/v1/transcriptions/$ID/segments?limit=500" \
  -H "Authorization: Bearer $H2T_API_KEY"

curl "https://heartotext.com/api/public/v1/transcriptions/$ID/segments?limit=500&cursor=eyJvIjo1MDB9" \
  -H "Authorization: Bearer $H2T_API_KEY"

Speakers

speaker is a diarization label: A, B, C in the order voices first appear. Three things follow from that, and all three matter:

• It is not a person. We do not identify anybody. Mapping A to a name is your job, and yours alone.
• It is stable within one recording only. Speaker A of one recording has nothing to do with speaker A of the next, even with the same people in the room.
• It can be null when diarization found nothing to separate — a single-voice recording, usually.

Export formats

text is accepted as a synonym of txt, and word of docx. The formats available depend on the plan of the account that owns the recording, not on the key calling — a paid plan has all five.

Downloading an export

The bytes come straight back with the right content type. There is no signed URL to follow: these files are rendered on demand rather than stored, so there is nothing to sign. A PDF of a long recording takes a few seconds — set your timeout accordingly.

curl "https://heartotext.com/api/public/v1/transcriptions/$ID/export?format=srt" \
  -H "Authorization: Bearer $H2T_API_KEY" \
  -o episode-42.srt

Only a completed recording can be exported; anything else answers 409 transcription_is_not_ready. An unknown format is a 422.