Scribe Sessions

A scribe session is created when a clinician conducts a consultation through the Telepatia interface. Once the session is finished, you can check its lifecycle and consultation metadata here, then fetch the filled record from the Medical Record Documents endpoint.

Session lifecycle

A session moves through several states. The values below are returned verbatim in the status field.

Status	Phase	Description
`created`	in-flight	Session opened, recording hasn’t started yet
`recording`	in-flight	Clinician is actively recording the consultation
`stopped`	in-flight	Recording ended; audio is being uploaded and queued for processing
`processing`	in-flight	AI pipeline (transcription + record generation) running
`completed`	ready	Pipeline finished — documents are available
`completedWithErrors`	ready	Pipeline finished with non-fatal AI errors — documents are still available
`reviewed`	ready	Clinician has reviewed and finalized the record
`error`	terminal	Fatal error during processing — no documents will be produced
`cancelled`	terminal	User cancelled the session
`unknown`	—	Fallback when the upstream state is unrecognized

Retrieving a session

Look a session up by its id. The id is either the consultationInternalId you set, or the session id (ss_...) the API returns — in this response and as scribeSessionId in every webhook event. Both resolve to the same session:

# By your consultationInternalId
curl https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

# By the session id the API returned
curl https://scribe-api.telepatia.ai/v1/scribe-sessions/ss_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "ss_a1b2c3d4e5f6g7h8",
  "status": "completed",
  "createdAt": "2026-02-20T10:00:00Z",
  "completedAt": "2026-02-20T10:30:00Z",
  "patientName": "John Doe",
  "scribeSessionModality": "IN_PERSON",
  "consultationInternalId": "CONSULT-12345",
  "specialty": "Cardiology"
}

This endpoint returns lifecycle and consultation metadata only. The filled record — and its diagnosis ICD codes — is fetched from the Medical Record Documents endpoint.

A session created without a consultationInternalId — for example one a clinician recorded directly — returns consultationInternalId: null. Use the session id (ss_...) to look it up. Every session-scoped endpoint accepts either id.

While status is still in-flight (created, recording, stopped, processing), poll this endpoint until it reaches a ready state (completed, completedWithErrors, reviewed) before fetching the filled record. error and cancelled are terminal failure states — no documents will be produced.

Listing a patient’s sessions

GET /v1/patients/{patient_id}/scribe-sessions returns the scribe sessions for one patient, most recent first. The {patient_id} can be the public id (sp_...) or the internalCode you set for your institution. Paginate with page (1-based) and limit (1–50, default 20).

curl "https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8/scribe-sessions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "items": [
    {
      "id": "ss_a1b2c3d4e5f6g7h8",
      "status": "completed",
      "createdAt": "2026-02-20T10:00:00Z",
      "completedAt": "2026-02-20T10:30:00Z",
      "patientName": "John Doe",
      "scribeSessionModality": "IN_PERSON",
      "consultationInternalId": "CONSULT-12345",
      "specialty": "Cardiology"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3,
  "hasMore": true
}

Each item carries the same fields as a single session above. total and totalPages count every session for the patient and are present on every page. Use id (ss_...) or consultationInternalId to fetch a session’s filled record from the Medical Record Documents endpoint. Returns 404 if no patient with that id is visible to your key.

Retrieving the filled record

This endpoint returns only the session’s lifecycle and consultation metadata. The actual filled record — the output of the session templates, with all sections — is fetched separately from the medical record documents endpoint, using the same consultationInternalId:

curl https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345/medical-record-documents \
  -H "Authorization: Bearer YOUR_API_KEY"

A session can produce more than one document (one per purpose — e.g. primary for the clinician-facing record, rpa for EMR injection). Filter with ?purpose=primary to fetch only the main one. See Medical Record Documents for the full response shape and field reference.

Getting Started

Core Concepts

Accounts & Patients

Reference

Session lifecycle

Retrieving a session

Listing a patient’s sessions

Retrieving the filled record

​Session lifecycle

​Retrieving a session

​Listing a patient’s sessions

​Retrieving the filled record

Session lifecycle

Retrieving a session

Listing a patient’s sessions

Retrieving the filled record