Heidihealth Heidi API Documentation
Official vendor OpenAPI document · agent-readyHealthcareEhr EmrapiKey, bearer29 EndpointsREST
For Agents
Create clinical scribe sessions, transcribe consultations, generate consult notes and clinical codes, and run ask-AI queries across 29 endpoints.
Use for: Create a new Heidi scribe session for a patient consultation, Get a JWT to authorise per-session Heidi API calls, Generate a consult note for a recorded session, Retrieve the transcript of a finished consultation
Not supported: Does not handle billing, prescription writing, lab orders, or patient demographics management - use for AI scribe sessions, transcripts, consult notes, and clinical codes only.
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.
Install Jentic One Beta
Connect the Heidi API Documentation to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Heidi API Documentation, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fheidihealth.com%2Fheidihealth" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fheidihealth.com%2Fheidihealth" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Heidi API Documentation API.
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
Patterns agents use Heidi API Documentation API for, with concrete tasks.
★ 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.
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.
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.
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.
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
29 endpoints — heidi health provides an ai medical scribe that listens to clinician-patient consultations and produces structured notes.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Heidi API Documentation API through Jentic.
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.
GET STARTED