canonical: https://jentic.com/apis/heidihealth.com/heidihealth

# Heidihealth Heidi API Documentation

Heidi Health provides an AI medical scribe that listens to clinician-patient consultations and produces structured notes. The Heidi API exposes the underlying ml-scribe pipeline so applications can create sessions, stream audio segments for transcription, generate consult notes and clinical codes, retrieve transcripts, and run agentic ask-AI queries against the captured session. Authentication uses an API key to mint a JWT, then bearer tokens on per-session calls.

## For AI agents

Create clinical scribe sessions, transcribe consultations, generate consult notes and clinical codes, and run ask-AI queries across 29 endpoints.

## Scope

Does not handle billing, prescription writing, lab orders, or patient demographics management - use for AI scribe sessions, transcripts, consult notes, and clinical codes only.

## Capabilities

- Mint a session JWT from your Heidi API key via GET `/api/v2/ml-scribe/open-api/jwt`
- Create a new clinician scribe session via POST `/api/v2/ml-scribe/open-api/sessions`
- Submit audio segments and trigger transcription via the restful-segment-transcription endpoints
- Generate a structured consult note from a recorded session via POST `/sessions/{session_id}/consult-note`
- Retrieve the session transcript and extracted clinical codes via the transcript and clinical-codes endpoints
- Ask a session-aware question of the AI scribe via POST `/sessions/{session_id}/ask-ai`
- List and use document templates to drive consult-note formatting

## Use cases

### AI Medical Scribe for Telehealth

A telehealth platform uses Heidi to auto-generate consult notes from each video visit. The platform creates a Heidi session per visit, streams the audio segments, then calls `/sessions/{session_id}/consult-note` once the visit ends. Clinicians review the generated note inside the platform rather than typing it from scratch.

Example prompt: Create a session via POST `/api/v2/ml-scribe/open-api/sessions`, submit audio segments, then call POST `/sessions/{session_id}/consult-note` to receive the structured note

### Clinical Coding Assistance

An EHR add-on extracts ICD/SNOMED-style codes from each consultation to assist billing. After a session is finished, the EHR calls GET `/sessions/{session_id}/clinical-codes` to retrieve the codes Heidi inferred and presents them to the coder for review and submission.

Example prompt: After finishing a session, call GET `/api/v2/ml-scribe/open-api/sessions/{session_id}/clinical-codes` and surface the suggested codes to the clinician

### Customised Note Templates by Specialty

A multi-speciality clinic uses different templates for cardiology, paediatrics, and mental-health visits. The clinic lists available templates via `/templates/document-templates` and chooses the right one when calling the consult-note generator, so each note matches the specialty's preferred structure.

Example prompt: Call GET `/api/v2/ml-scribe/open-api/templates/document-templates` and select the cardiology template for the next consult-note generation

### AI Agent Clinical Q&A

A clinician asks an AI agent 'what symptoms did the patient mention in this morning's visit?'. Through Jentic, the agent calls `/sessions/{session_id}/ask-ai` with the session id and returns Heidi's grounded answer drawn from the session transcript, without exposing the API key.

Example prompt: Search Jentic for 'ask ai a question about a heidi session', load POST `/sessions/{session_id}/ask-ai`, and submit the clinician's question

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v2/ml-scribe/open-api/sessions` | Create a new scribe session |
| GET | `/api/v2/ml-scribe/open-api/sessions/{session_id}` | Get session details |
| POST | `/api/v2/ml-scribe/open-api/sessions/{session_id}/consult-note` | Generate a consult note from the session |
| GET | `/api/v2/ml-scribe/open-api/sessions/{session_id}/transcript` | Get the session transcript |
| GET | `/api/v2/ml-scribe/open-api/sessions/{session_id}/clinical-codes` | Get extracted clinical codes |
| POST | `/api/v2/ml-scribe/open-api/sessions/{session_id}/ask-ai` | Ask an AI question grounded in the session |
| GET | `/api/v2/ml-scribe/open-api/jwt` | Mint a session JWT from the API key |
| GET | `/api/v2/ml-scribe/open-api/templates/document-templates` | List document templates |

## Key resources

- **Sessions** — Create, retrieve, and update clinician-patient scribe sessions
- **Transcription** — Submit audio segments and finalise transcription
- **Consult Notes** — Generate structured consult notes from a finished session
- **Clinical Codes** — Retrieve extracted clinical codes from a session
- **Documents and Templates** — List and use document templates and store generated documents
- **Ask AI** — Run grounded Q&A against a session's transcript

## Why Jentic

- **Setup:** Wiring Heidi by hand means sending your Heidi-API-key header to /jwt to mint a short-lived bearer token, then attaching that token on every scribe call. Through Jentic you install once, import the Heidi API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Heidi puts the session id in the URL path (`/api/v2/ml-scribe/open-api/sessions/{session_id}/...`), so a rule can pin your agent to one session: it can read that session's transcript and clinical codes and nothing else. You choose the operations it may call, so ones that generate a consult note or ask the AI are not included unless you add them.
- **Credential handling:** Your Heidi API key is stored once, encrypted, by your own Jentic One instance, which performs the JWT exchange at execution time so the agent only ever works with a short-lived session-scoped token. The key never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a scribe session' or 'generate a consult note', and Jentic returns the matching Heidi operation with its input schema and required path parameters so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DrChrono API** — DrChrono provides the EHR system to which Heidi-generated notes are typically written
- **Athenahealth API** — Athenahealth is another EHR target for Heidi-generated notes and codes
- **Deepgram API** — Deepgram offers raw speech-to-text but lacks the consult-note and clinical-code layers Heidi provides
- **AssemblyAI API** — AssemblyAI is a generic transcription and audio intelligence API, broader but less clinical than Heidi

## FAQ

### What authentication does the Heidi API use?

Heidi uses an API key to call GET `/api/v2/ml-scribe/open-api/jwt`, which returns a JWT that is then used as a Bearer token on per-session endpoints. Through Jentic, the API key is held in the encrypted vault and the JWT exchange happens at execution time.

### Can I generate a consult note from a recorded session?

Yes. POST `/api/v2/ml-scribe/open-api/sessions/{session_id}/consult-note` generates a structured note from the session's transcript, optionally using a chosen document template id.

### What are the rate limits for the Heidi API?

The OpenAPI spec does not publish hard rate limits; Heidi applies plan-level fair use. Because audio transcription is the heavy operation, batch segment uploads rather than firing many small segments per second.

### How do I create a session and ask the AI a question through Jentic?

Run pip install jentic, have the agent search for 'create a heidi scribe session', load the session-creation operation, then chain to POST `/sessions/{session_id}/ask-ai` with the clinician's question.

### Does Heidi return clinical codes for a session?

Yes. GET `/api/v2/ml-scribe/open-api/sessions/{session_id}/clinical-codes` returns the clinical codes inferred from the consultation, which a coder or billing system can review before submission.

### Can I customise the consult-note template?

Yes. List document templates with GET `/api/v2/ml-scribe/open-api/templates/document-templates` and pass the selected template id when generating the consult note, or use the client-customised-template endpoint for tailored output.

### Can I limit what my agent is allowed to do with the Heidi API?

Yes. Jentic One is self-hosted, so your own rules decide which of Heidi's operations the agent may call: because the session id lives in the URL path (`/api/v2/ml-scribe/open-api/sessions/{session_id}/...`), a rule can pin the agent to a single session and let it read only that session's transcript and clinical codes. You choose the operations it may use, so ones that generate a consult note or ask the AI are excluded unless you add them. Credentials and operation access stay under your control.