Authentication #
Organization API key required
Every endpoint on this page takes your organization API key in the X-Api-Key header (or as Authorization: Bearer). The key acts for the whole organization: endpoints that create something for one clinician, such as Create Visit, take that clinician's email in the request.
How to get an API key (organization admins, or members an admin gave Developer access on the Team page):
- Log in to your account.
- Go to Settings > API Keys.
- Create and copy your API key. It is shown once; keep it on your server and never in a browser or an app.
Getting Your API Key #
To use the Passwordless OAuth Authentication, you'll need to obtain an API key from your ScribeMD dashboard.
Step-by-Step Guide
Log in to ScribeMD
Access your ScribeMD account at www.scribemd.ai
Navigate to Settings
Click on the Settings menu in your dashboard
Go to API Keys
Select API Keys from the settings menu
Create New Key
Click Create New Key and give it a descriptive name (e.g., "My App Integration")
Copy Your API Key
Copy the generated API key and store it securely in your environment variables
Important Security Notes
Never expose your API key in client-side code or public repositories
Store API keys securely using environment variables or secure key management systems
Rotate keys regularly and revoke unused keys for better security
Environment Variable Setup
Once you have your API key, set it up as an environment variable:
For Development (.env file)
SCRIBEMD_API_KEY=your_actual_api_key_hereFor Production (Environment Variables)
# Heroku
heroku config:set SCRIBEMD_API_KEY=your_actual_api_key_here
# AWS
export SCRIBEMD_API_KEY=your_actual_api_key_here
# Docker
docker run -e SCRIBEMD_API_KEY=your_actual_api_key_here your-app
POST
/api/v1/visits
진료 생성
#
Create a visit from your own systems by uploading a recording: the note is written with the template you name and delivered to your webhook when it is ready.
Who owns the visit
Your organization API key authenticates the request, and user_email names the clinician the visit belongs to: a member of your organization, matched by their ScribeMD login email, case-insensitively. The visit appears in that clinician's account, is transcribed and written with their language and note settings, and counts towards their activity in your dashboard. Leave user_email out and the visit goes to the clinician who created the API key.
Tell us what you know about the meeting
The recording is enough for a note, but the note is better when the request carries what your system already knows. context (the referral reason, the chief complaint, a summary of the record) is given to the AI alongside the transcript. language tells the transcriber which language to expect. patient_id, medical_record and timestamp are the same reference the ScribeMD widget receives from an EHR: they are stored on the visit, shown in the dashboard export, and sent back to you in the webhook and in the organization encounters export, so you can file the note without keeping our UUID.
Request Parameters
Send a JSON or form-encoded payload with the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_email | string | Recommended | The login email of the clinician this visit belongs to. Must be a member of your organization; any other email returns 422 and nothing is created. Without it, the visit belongs to the clinician who created the API key. |
| template_id | int | Yes | The ID of the note template to write the note with: one of your organization's templates or one of the clinician's own. Admins see template IDs under Manage > Templates; clinicians under their Templates page. |
| audio_file | string | Yes | The audio file, base64-encoded, prefixed with the MIME type (e.g., data:audio/mp3;base64,...). |
| webhook_url | string | No | (Optional) A URL to receive a POST callback when processing is complete. |
| context | string | No | Free text the AI reads alongside the transcript: the referral reason, the chief complaint, a summary of the medical record, the previous note. The same field as "Consultation context" when a clinician starts a visit in the app. At most 1,000,000 characters: a longer context is refused with 422 and nothing is created. |
| language | string | No | The language spoken in the recording as a BCP 47 tag (he-IL, en-US, ar). Without it the clinician's default transcription language is used. The note itself is written in the clinician's note language. |
| patient_id | string | No | The patient's identifier in your EHR. When it is a national ID number (digits only, dashes allowed) it also fills the patient ID field templates can print and the dashboard export lists. Returned in the webhook as patient_id. |
| medical_record | string | No | The medical record or encounter reference in your EHR that the note should be filed under. Returned unchanged in the webhook and in the organization encounters export. |
| timestamp | string | No | When the meeting took place, ISO 8601 with an offset (2026-10-28T09:30:00+02:00). Becomes the visit's start time, so a recording uploaded at night is still dated to the consultation. Anything else returns 422. |
| patient_first_name | string | No | With patient_last_name: creates a patient record with that name in the clinician's patient list and attaches the visit to it. |
How to get a NoteTemplate ID: You can create or view NoteTemplates in the web frontend. Use the ID of the template you want to use for the visit.
Example Request
POST https://api.scribemd.ai/api/v1/visits
Headers:
X-Api-Key: YOUR_ORGANIZATION_API_KEY
Content-Type: application/json
Body (JSON):
{
"user_email": "dr.levi@your-hospital.org",
"template_id": 123,
"audio_file": "data:audio/mp3;base64,AAAAGGZ0eXBtc...",
"webhook_url": "https://example.com/webhook",
"context": "Referred by GP for exertional chest pain. Known hypertension on amlodipine 5 mg.",
"language": "he-IL",
"patient_id": "012345678",
"medical_record": "MR-2026-0042",
"timestamp": "2026-10-28T09:30:00+02:00"
}Webhook URL
If you provide a webhook_url, the system will send a POST request to that URL when the visit processing is complete.
Webhook Request
- Method: POST
- Content-Type: application/json
Example Webhook Payload
{
"notes": "The generated note text as a string.",
"encounter_uuid": "abc123-uuid",
"reviewed_at": null,
"patient_id": "012345678",
"medical_record": "MR-2026-0042",
"timestamp": "2026-10-28T09:30:00+02:00"
}notes: The generated notes for the visit, formatted as a string.encounter_uuid: The unique identifier for the created encounter/visit.reviewed_at: When the clinician approved the note;nullwhile it is an unreviewed draft.patient_id,medical_record,timestamp: Exactly what you sent when creating the visit, so the note can be filed without a lookup;nullwhen not sent.
Response
201 Created
On success, returns a JSON object with the encounter_uuid of the created visit.
Example Success Response
{
"encounter_uuid": "abc123-uuid"
}Errors
Errors come back as { "error": "..." }. Nothing is created when a request fails.
| Status | When |
|---|---|
| 400 | audio_file is missing or not a base64 data URL. |
| 401 | No key, an unknown key, or a key that was deactivated. Only organization keys from Settings > API Keys work here. |
| 403 | The organization's account is locked. |
| 422 | user_email is not a member of your organization, or it was omitted and the key's creator is no longer a member; timestamp is not ISO 8601 or language is not a BCP 47 tag; context is longer than 1,000,000 characters; or the visit could not be saved (the message says why, for example an unknown template_id). |
Notes
- The
template_idmust correspond to a valid note template: one of your organization's or one of the clinician's own. - The
audio_filewill expire in 24 hours after the request is made.
GET
/api/v1/organization_encounters
List Encounters by API Key
#
Retrieve encounters created by users in your organization. Results are always scoped to the organization that owns the API key.
Also available in API v2 as GET https://app.scribemd.ai/api/v2/organization_encounters, with the same API key, filters and fields. It returns data and meta: { page, per_page, total, total_pages, next_page } instead of encounters and pagination, errors as { "error": { "code", "message" } }, takes end_date (not enddate), and is described in the v2 OpenAPI contract (listOrganizationEncounters).
Authentication
Include your organization API key in the X-Api-Key header.
Example Request
curl -X GET "https://api.scribemd.ai/api/v1/organization_encounters?start_date=2024-01-01&enddate=2024-01-31&department_ids=12&page=1" \
-H "X-Api-Key: YOUR_API_KEY"Replace YOUR_API_KEY with your organization's API key. Only encounters owned by users in that organization are returned.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| start_date | string | No | Limit encounters to those created on or after this date (YYYY-MM-DD). |
| enddate | string | No | Limit encounters to those created on or before this date (YYYY-MM-DD). |
| end_date | string | No | Alias of enddate. |
| department_ids | string | No | Only encounters by clinicians who are members of these departments (the same filter as the admin dashboard): one id, several comma-separated (12,13) or repeated (department_ids[]=12&department_ids[]=13). Department ids are listed on each encounter under user.departments. An id outside your organization returns 400. |
| department_ids | string or array | No | Several departments at once: department_ids=12,13 or department_ids[]=12&department_ids[]=13. |
| page | integer | No | Pagination page number (default: 1). |
| per_page | integer | No | Encounters per page, from 1 to 100 (default: 20; limit is accepted too). Take smaller pages when your encounters carry long transcripts or large contexts. A value outside 1–100 returns 400. |
Example Response
{
"encounters": [
{
"id": 123,
"uuid": "6f1c2b9e-3d4a-4c8e-9b1f-2a7d5e8c0f13",
"date": "2024-05-12T14:22:18Z",
"updated_at": "2024-05-12T15:02:41Z",
"user": {
"id": 42,
"name": "Dr. Taylor",
"email": "dr.taylor@example.com",
"departments": [{ "id": 12, "name": "Cardiology" }]
},
"title": "Follow-up Visit",
"language": "en-US",
"platform_source": "web",
"app_version": null,
"note_template": { "id": 7, "name": "SOAP", "updated_at": "2024-05-01T10:00:00Z" },
"json_notes_history": [
{ "event": "generated", "timestamp": "2024-05-12T14:23:05Z", "notes": {} }
],
"json_notes": {},
"note_format": "json",
"markdown_content": null,
"structured_note": null,
"transcript": "Conversation transcript...",
"audio_file_url": "https://example.com/audio.mp3",
"audio_file_proxy_url": "https://api.scribemd.ai/rails/active_storage/blobs/proxy/.../upload.mp3",
"context": {
"text": "History of hypertension, on lisinopril 10 mg.",
"past_medical_history": [{ "description": "Type 2 diabetes", "date": "2019" }],
"physician_notes": null,
"files": [{ "name": "labs.pdf", "content_type": "application/pdf", "byte_size": 48213, "url": "https://example.com/labs.pdf", "proxy_url": "https://api.scribemd.ai/rails/active_storage/blobs/proxy/.../labs.pdf" }]
},
"documents": [
{ "id": 311, "kind": "pdf", "template_id": 18, "template_name": "Referral form", "created_at": "2024-05-12T14:31:00Z", "updated_at": "2024-05-12T14:35:12Z", "content_type": "application/pdf", "download_url": "https://api.scribemd.ai/api/v1/organization_encounter_documents/pdf/eyJfcmFpbHMi..." },
{ "id": 95, "kind": "document", "template_id": 4, "template_name": "Discharge letter", "created_at": "2024-05-12T14:33:40Z", "updated_at": "2024-05-12T14:33:40Z", "content_type": "application/pdf", "download_url": "https://api.scribemd.ai/api/v1/organization_encounter_documents/document/eyJfcmFpbHMi..." }
],
"generation": {
"schema_version": 1,
"generated_at": "2024-05-12T14:23:05Z",
"trigger": "initial",
"custom_instructions": null,
"summarization": { "engine": "7c1e0f9a2b4d6e83", "fallback": false, "provider": "anthropic", "model": "anthropic/claude-sonnet-5-5", "requested_model": "anthropic/claude-sonnet-5-5", "fallback_from": null, "thinking": { "enabled": false }, "schema_enforced": true, "transcript_format": null, "temperature": 0, "note_format": "json", "notes_language": "en" },
"transcription": { "source": "server", "engine": "d41a8c2e9f03b765", "provider": "scribemd", "model": "scribemd-batch-v5", "language": "en-US", "transcribed_at": "2024-05-12T14:22:58Z" },
"template": {
"id": 7,
"parent_id": null,
"updated_at": "2024-05-01T10:00:00Z",
"content_sha256": "9b2f...",
"content": { "name": "SOAP", "custom_instruction": "...", "note_format": "json", "sections": [{ "id": 31, "name": "Subjective", "order": 1, "active": true, "content": "..." }] }
},
"system_prompt_sha256": "4e1a..."
},
"transcription": { "source": "server", "engine": "d41a8c2e9f03b765", "provider": "scribemd", "model": "scribemd-batch-v5", "language": "en-US", "transcribed_at": "2024-05-12T14:22:58Z" },
"note_versions": [
{ "id": 901, "event": "generated", "created_at": "2024-05-12T14:23:05Z", "updated_at": "2024-05-12T14:23:05Z", "author": { "id": 42, "name": "Dr. Taylor", "email": "dr.taylor@example.com" }, "note_template_id": 7, "label": null, "restored_from_id": null, "note_format": "json", "json_notes": {}, "markdown_content": null, "generation": { "...": "as above" }, "is_current": false },
{ "id": 902, "event": "edited", "created_at": "2024-05-12T14:40:12Z", "updated_at": "2024-05-12T14:47:30Z", "author": { "id": 42, "name": "Dr. Taylor", "email": "dr.taylor@example.com" }, "note_template_id": 7, "label": null, "restored_from_id": null, "note_format": "json", "json_notes": {}, "markdown_content": null, "generation": null, "is_current": true }
],
"status": "succeeded",
"summary_status": "finished",
"reviewed_at": "2024-05-12T15:02:41Z",
"reviewed_by": { "id": 42, "name": "Dr. Taylor", "email": "dr.taylor@example.com" },
"feedback_value": true,
"feedback_text": "Helpful",
"feedback_date": "2024-05-13T09:10:00Z",
"patient_id_number": "123456",
"medical_record": "MR-2026-0042",
"started_at": "2024-05-12T14:00:00Z"
}
],
"pagination": {
"count": 25,
"page": 1,
"items": 20,
"pages": 2,
"last": 2,
"next": 2,
"prev": null
}
}Note history and provenance
note_versionsis the note's full history, oldest first: every state the note has been in.eventsays what produced it:generated(the AI wrote or rewrote the whole note),edited(a clinician edited it; edits by the same person within 15 minutes fold into one version, whoseupdated_atis the last save),revised(an AI rewrite of a selected passage),dictated(dictation inserted into the note),guidelines_applied,restored(an earlier version restored;restored_from_idpoints to it),adopted(the alternative note chosen in a side-by-side comparison),carried_over(the note a resumed visit started from) andsnapshot(the note as found when history began, for encounters older than the version store).authoris the user who made the change (null for system events), andis_currentmarks the version equal tojson_notes.- Approval is not a note version: when the clinician marks the note reviewed,
reviewed_atandreviewed_byare set on the encounter. generationdescribes the latest AI generation, and eachgeneratedversion carries its own copy: the summarizationproviderandmodelthat wrote the note (withrequested_model,fallback_fromand the thinking and schema settings;fallbackis true when an outage handed the note to a backup model) and anengineid of that whole configuration, identical for every note the same configuration produced and different once anything in it changed,trigger(initial,regenerationorresume), the clinician's regeneration instructions, the transcription engine, and a snapshot of the template's content as it was at that moment with itscontent_sha256.system_prompt_sha256changes whenever anything in the full prompt changed (ScribeMD's instructions, organization or department settings, glossary, or the encounter's own inputs). Notes generated before this field existed havegeneration: null.transcription.sourceisserverwhen ScribeMD transcribed uploaded audio andclientwhen the recording app transcribed live, withplatform_sourceandapp_version.providerandmodelname the speech-to-text that made the transcript (for a live client transcription the app picks the model, so it is null), andengineidentifies that configuration the same way as for summarization. ScribeMD's own speech-to-text is served as providerscribemd. To compare two notes, group byengine,template.content_sha256andsystem_prompt_sha256.json_notes_historyis the conversation with the model, kept so a regeneration can build on it:generatedentries are the model's outputs,regenerate_requestentries the clinician's instructions, andguidelines_applied,admin_retryandadmin_regeneratesystem steps. Clinician edits are never written to it, and it is cleared when the template changes, so it can lag behindjson_notes. Usenote_versionsfor history.contextis what the clinician entered when setting up the visit (text: the free-text context;past_medical_history; attachedfiles, with links that expire after 24 hours) and the notes typed during it (physician_notes). All of it is given to the model with the transcript.documentslists the documents generated from the encounter, oldest first: filled PDF templates (kind:pdf,application/pdf) and document template outputs (kind:document, printed with the organization, title, visit date and page numbers, alsoapplication/pdf). Each has itsid(unique within its kind),template_idandtemplate_name,created_at,updated_at(the last edit) and adownload_url. The file is the document as last edited. Documents still generating or that failed are left out.- File links come in pairs that both expire after 24 hours:
audio_file_urlandfiles[].urlare signed links to our storage (Amazon S3);audio_file_proxy_urlandfiles[].proxy_urlserve the same file throughapi.scribemd.ai. Use the proxy links when your network blocks*.s3.amazonaws.com(connections reset before any data arrives).documents[].download_urlis served throughapi.scribemd.aionly and also expires after 24 hours. Download with a plain GET; no API key is needed, the link itself is signed.
Pagination
- Pagination metadata follows the
paginationobject shown above. - Each page returns up to 20 encounters, or
per_page(1–100); use thepageparameter to navigate. - Send
Accept-Encoding: gzipto receive the response compressed (most HTTP clients do it for you). Range requests are not supported: take smaller pages instead. - To refetch a single encounter, call
GET /api/v1/organization_encounters/{uuid}with the same API key: it returns{ "encounter": { ... } }, the same record as in the list, or 404 for a deleted encounter or one outside your organization (v2:GET /api/v2/organization_encounters/{uuid},{ "data": { ... } }). - The
lastvalue tells you the final page available for the current filters. - The
nextandprevvalues help you continue fetching subsequent pages.
Audio, file and document links (both the S3 url and the proxy_url forms) are pre-signed and expire after 24 hours. Request fresh links by calling this endpoint again, or GET /api/v1/organization_encounters/{uuid} for a single encounter.
GET
/api/v1/organization_encounters/{uuid}
One Encounter by API Key
#
One encounter of your organization, exactly as List Encounters by API Key serves it: the same fields, with fresh file links. Use it to refetch a single record (for example one whose links expired) without paging through a whole date range. Authenticate with the organization API key in the X-Api-Key header.
Also available in API v2 as GET https://app.scribemd.ai/api/v2/organization_encounters/{uuid}, returning { "data": { ... } } (getOrganizationEncounter in the v2 OpenAPI contract).
Example Request
curl -X GET "https://api.scribemd.ai/api/v1/organization_encounters/6f1c2b9e-3d4a-4c8e-9b1f-2a7d5e8c0f13" \
-H "X-Api-Key: YOUR_API_KEY" \
--compressedExample Response
{
"encounter": {
"id": 123,
"uuid": "6f1c2b9e-3d4a-4c8e-9b1f-2a7d5e8c0f13",
"...": "the same fields as each item of encounters in the list"
}
}Errors
401: the API key is missing or not valid.404: no such encounter in your organization, or it was deleted.
PATCH
/api/v1/encounters/:id/update_markdown
Update Markdown Content
#
Update the markdown content of a markdown-format encounter. The server automatically syncs json_notes from the updated markdown on save.
Markdown Format Only
This endpoint only works for encounters with note_format: "markdown". For JSON-format encounters, use the existing POST /api/v1/encounters/:id/update_notes endpoint.
Request
PATCH /api/v1/encounters/:id/update_markdown
Content-Type: application/json
Authorization: Bearer <access_token>
{
"prompt": {
"markdown_content": "#### Chief Complaint\nPatient presents with..."
}
}Response
Returns the encounter with both markdown_content and auto-synced json_notes:
{
"data": {
"id": 123,
"name": "Visit 2026-03-11",
"note_format": "markdown",
"markdown_content": "#### Chief Complaint\nPatient presents with...",
"json_notes": { "1_ChiefComplaint": ["Patient presents with..."] },
"summary_status": "finished",
...
}
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| prompt[markdown_content] | string | Yes | The full markdown content for the note. |
Error Responses
422— Encounter is not in markdown format422—markdown_contentparameter is missing403— Unauthorized (encounter belongs to another user)
POST
/api/v1/encounters/:id/resume_visit
Continue Recording
#
Creates a "(Continued)" copy of a finished encounter so more audio can be recorded without touching the original note. The copy carries over the audio segments, template, patient, language, mode, duration and consultation context; recording appends new segments after the copied ones and, on finish, the full conversation is re-transcribed and the note regenerated. The original encounter and its note are left unchanged.
Example Request
curl -X POST "https://api.scribemd.ai/api/v1/encounters/12345/resume_visit" \
-H "Authorization: Bearer <access_token>"Example Response
{
"id": 12346,
"name": "Patient - August 09, 2026 (Continued)",
"summary_status": "waiting",
"duration": 145,
"encounter_mode": "visit",
"visit_mode": "in_person",
"note_template_id": 1234,
"audio_segments_count": 8
}audio_segments_count is the number of segments carried over — recorders must continue segment numbering from this value so the merge keeps old and new audio in order. Requires ownership of the encounter (403 otherwise).
POST
/api/v1/encounters/:id/delete_audio_segment
Delete Audio Segment
#
Removes a single recorded audio segment (e.g. one with background noise) without discarding the rest of the encounter. The segment is identified by the signed_id returned when it was uploaded.
Request Body
{ "signed_id": "<active-storage-signed-id>" }Responses
200—{ "success": true }404— segment not found on this encounter422—signed_idmissing403— encounter belongs to another user
POST
/api/v1/encounters/:id/source_feedback
Note Feedback
#
Records like/dislike feedback on a selected piece of a generated note, or on the whole note when selected_text is omitted. A note keeps every feedback it receives. Negative feedback that includes a comment is fed into the prompt-learning pipeline, which distils it into a durable preference on the user's personal prompt and applies it to future notes.
Request Body
{
"value": false, // true = like, false = dislike
"comment": "Too verbose; list meds as bullets", // optional; drives learning
"selected_text": "The patient was prescribed..." // optional; omit to rate the whole note
}Responses
200—{ "success": true, "id": 987 }422—valuemissing403— encounter belongs to another user
Prompt learning runs automatically on negative feedback that includes a comment.
GET
/api/v1/encounters/retrieve
Retrieve Note & Transcript
#
A poll-based, callback-independent way to fetch an encounter's note and transcript. The onNoteGenerated callback is a push and is lost if the clinician switches patients mid-visit; this endpoint lets the host store the encounter uuid at visit start (see onEncounterCreated below) and poll until the note is ready.
Query Parameters (provide one)
uuid— the ScribeMD encounter uuid (fromonEncounterCreatedor the create response).ehr_encounter_id— your EHR encounter id, if set on the encounter.ehr_appointment_id— your EHR appointment id, if set on the encounter.
Example Request
curl -X GET "https://api.scribemd.ai/api/v1/encounters/retrieve?uuid=1bc91eb0-ca16-40a5-87c5-ccc7b6cb4f14" \
-H "Authorization: Bearer <access_token>"Response — while generating
{
"success": true,
"uuid": "1bc91eb0-ca16-40a5-87c5-ccc7b6cb4f14",
"summary_status": "running", // waiting | running | finished | failed
"transcript_status": "succeeded",
"ready": false,
"duration": 145
}Response — when ready
{
"success": true,
"uuid": "1bc91eb0-ca16-40a5-87c5-ccc7b6cb4f14",
"summary_status": "finished",
"ready": true,
"duration": 145,
"note_format": "json", // "json" | "markdown"
"note": [ { "name": "History", "order": "1", "content": ["..."] }, ... ],
"json_notes": { "1_History": "...", ... },
"markdown_content": "...", // markdown templates only
"structured_note": { // structured templates only, else null;
"version": 1, // json_notes stays the flat copy
"sections": [
{ "key": "assessment_plan", "title": "Assessment & Plan", "type": "group", "numbered": true,
"sections": [
{ "key": "assessment_plan_1", "title": "Hypertension", "type": "group", "numbered": false,
"sections": [
{ "key": "assessment", "title": "Assessment", "type": "text", "content": "..." },
{ "key": "plan", "title": "Plan", "type": "list", "content": ["..."] }
] }
] }
]
},
"transcript": [ { "speaker": 0, "text": "...", "start_time": 0.4 }, ... ]
}Poll every few seconds until ready is true. Owner-scoped (the token's own encounters); 404 if no matching encounter.
JavaScript SDK #
Integrate ScribeMD directly into your web application with our lightweight JavaScript widget SDK.
Try the Live Demo
Experience the ScribeMD widget in action with our interactive demo:
What you'll see:
- Real widget integration
- Audio recording functionality
- Live transcription processing
Quick Start
Step 1: Include the SDK
<script src="https://static.scribemd.ai/scribeMDwidget.min.js"></script>Step 2: Initialize the Widget
<button onclick="scribeMDWidget.init()">Initialize ScribeMD Widget</button>Widget Configuration
The ScribeMD widget supports various configuration options for customization:
// Basic initialization
scribeMDWidget.init();
// Advanced configuration
scribeMDWidget.init({
// Pre-fill consultation context, sent with the encounter (optional)
consultationContext: "Patient presents with chest pain for 2 days...",
// Pre-fill Past Medical History — an array of { description, date }.
// Shown when the org has past_medical_history / unified_past_medical_history
// enabled. A filled entry (has a description) requires a date (optional).
pastMedicalHistory: [
{ description: "Appendectomy", date: "2015-06-01" },
{ description: "Hypertension diagnosis", date: "2019-03-15" },
],
// Pre-attach context documents — images, PDF, Word (.doc/.docx), or text.
// Each file is a URL or a base64 data URL, plus a filename. Files are
// fetched/decoded and uploaded with the encounter on the first visit (optional).
contextFiles: [
{ url: "https://your-ehr.example.com/labs/123.pdf", name: "labs.pdf" },
{ dataUrl: "data:image/jpeg;base64,...", name: "scan.jpg" },
],
// Limit the widget to a single note template (optional)
noteTemplateId: 1234,
// Appearance (optional)
position: "right", // "left" | "right" (default "right")
theme: "light", // "light" | "dark" (default "light")
// Manual note approval (optional, default false)
// When true, the note opens in the editor as soon as generation
// finishes and onNoteGenerated fires ONLY after the clinician clicks
// the approval button (never automatically). The clinician can edit
// the note first; the callback receives the final, saved content.
manualNoteApproval: true,
approvalButtonLabel: "Push to Photon", // default "Approve & Send"
// Show the physician's visit-history list in the widget menu.
// Default false: the widget sits on a single patient's page while the
// history spans all of the physician's patients (optional).
showVisitHistory: false,
// Fired the moment the encounter is created ("Start Consultation"),
// delivering its encounter_id immediately — before recording. Store it so
// you can retrieve the note later via GET /encounters/retrieve even if the
// clinician switches patients and the onNoteGenerated callback is lost.
onEncounterCreated: function ({ uuid }) {
rememberEncounterUuid(uuid);
},
// Fired when the note is ready (or approved, if manualNoteApproval).
// Accepts a second `meta` argument; older handlers reading only the
// first argument keep working unchanged.
onNoteGenerated: function (note, meta) {
// note — array of sections: [{ name, order, content: [..] }, ...]
// (or a plain string for non-JSON note formats)
console.log('Note:', note);
// meta — extra context about the encounter:
// meta.encounter_id -> number
// meta.duration -> seconds (number | null)
// meta.transcript_text -> full transcript as plain text
// meta.transcript_json -> [{ speaker, text, start_time? }, ...]
console.log('Encounter:', meta.encounter_id);
console.log('Transcript text:', meta.transcript_text);
console.log('Transcript JSON:', meta.transcript_json);
}
// onGenerateNote is accepted as an alias for onNoteGenerated.
});
// Pre-authenticated (EHR) initialization — bypasses the login/OTP screens.
scribeMDWidget.initWithTokens(
{ tokens: { access_token, refresh_token }, user: { id, email, full_name } },
{ manualNoteApproval: true, approvalButtonLabel: "Push to Photon", /* ...options */ }
);| Option | Type | Default | Description |
|---|---|---|---|
| consultationContext | string | — | Pre-fills the consultation context; sent with the encounter for note generation. |
| pastMedicalHistory | {description, date}[] | — | Pre-fills Past Medical History entries. A filled entry requires a date. Shown when the org has the feature enabled. |
| contextFiles | {url|dataUrl, name}[] | — | Pre-attach documents (images, PDF, Word, text) by URL or base64 data URL. Uploaded with the encounter. |
| noteTemplateId | number | string | — | Restricts the widget to a single note template. |
| position | "left" | "right" | "right" | Side of the screen the widget anchors to. |
| theme | "light" | "dark" | "light" | Color theme. |
| manualNoteApproval | boolean | false | Hold the callback until the clinician reviews/edits and clicks the approval button. The note opens in the editor automatically when generation finishes. |
| approvalButtonLabel | string | "Approve & Send" | Label for the approval button (only with manualNoteApproval). |
| showVisitHistory | boolean | false | Show the cross-patient visit-history list in the widget menu. |
| onEncounterCreated(info) | function | — | Fired at visit start with { uuid }. Store it to retrieve the note later via GET /encounters/retrieve?uuid=… — survives switching patients. |
| onNoteGenerated(note, meta) | function | — | Called when the note is ready (or approved). meta carries encounter_id, duration, transcript_text, and transcript_json. |
React Integration Example
Load the SDK once, mount the widget when the component appears, and detach it on unmount:
import { useEffect, useState } from 'react';
const WIDGET_SRC = 'https://static.scribemd.ai/scribeMDwidget.min.js';
export default function ScribeMDPanel({ consultationContext }) {
const [encounterUuid, setEncounterUuid] = useState(null);
const [note, setNote] = useState(null);
useEffect(() => {
const script = document.createElement('script');
script.src = WIDGET_SRC;
script.async = true;
script.onload = () => {
window.scribeMDWidget.init({
position: 'right',
theme: 'light',
consultationContext,
// Fired at visit start. Persist the uuid so the note can still be
// fetched via GET /api/v1/encounters/retrieve?uuid=... later.
onEncounterCreated: ({ uuid }) => setEncounterUuid(uuid),
// Fired when the note is ready (or approved, with manualNoteApproval).
onNoteGenerated: (sections, meta) => {
setNote(sections);
console.log('Encounter', meta?.encounter_id, 'transcript:', meta?.transcript_text);
},
});
};
document.body.appendChild(script);
// Remove the widget and its DOM when the component unmounts
return () => {
window.scribeMDWidget?.detach();
document.body.removeChild(script);
};
}, [consultationContext]);
if (!note) {
return <p>{encounterUuid ? 'Consultation in progress…' : 'Start a consultation from the ScribeMD panel.'}</p>;
}
return (
<section>
{note.map((section) => (
<article key={section.order}>
<h3>{section.name}</h3>
{section.content.map((line, i) => <p key={i}>{line}</p>)}
</article>
))}
</section>
);
}Complete HTML Example
A dependency-free page that opens the widget, remembers the encounter and renders the note when it arrives:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ScribeMD Integration</title>
</head>
<body>
<h1>Medical Documentation</h1>
<button id="openBtn">Open ScribeMD</button>
<p id="status"></p>
<div id="note"></div>
<script src="https://static.scribemd.ai/scribeMDwidget.min.js"></script>
<script>
var statusEl = document.getElementById('status');
var noteEl = document.getElementById('note');
scribeMDWidget.init({
position: 'right',
theme: 'light',
consultationContext: 'Patient presents with...',
onEncounterCreated: function (info) {
// Persist the uuid: GET /api/v1/encounters/retrieve?uuid=... still
// works if this page is closed before the note is ready.
localStorage.setItem('scribemd_encounter', info.uuid);
statusEl.textContent = 'Consultation started: ' + info.uuid;
},
onNoteGenerated: function (sections, meta) {
statusEl.textContent = 'Note ready';
if (!Array.isArray(sections)) { // markdown / plain-text templates
noteEl.textContent = sections;
return;
}
noteEl.innerHTML = sections.map(function (s) {
return '<h3>' + s.name + '</h3>' +
s.content.map(function (line) { return '<p>' + line + '</p>'; }).join('');
}).join('');
}
});
// toggle() opens or closes the panel; detach() removes the widget entirely.
document.getElementById('openBtn').addEventListener('click', function () {
scribeMDWidget.toggle();
});
</script>
</body>
</html>SDK Features
Lightweight
Only 15KB minified and gzipped
No Dependencies
Works standalone without jQuery or other libraries
HIPAA Compliant
Secure data transmission and storage
Real-time Transcription
Live transcription during recording
Responsive Design
Works on desktop, tablet, and mobile
Customizable UI
Theme and behavior configuration
Browser Support
Chrome
90+
Safari
14+
Firefox
88+
Edge
90+
Passwordless OAuth Authentication #
Authenticate users seamlessly using your organization's API key and integrate with the JavaScript SDK for a complete authentication flow.
Overview
The Passwordless OAuth endpoint allows you to authenticate users using their email address and your organization's API key. This is perfect for:
- Seamless user authentication in your application
- Integration with the ScribeMD JavaScript SDK
- Minimal data transfer for security and performance
- No password management required
API Endpoint
POST /api/users/tokens/passwordless_oauthHeaders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Body
{
"email": "user@example.com"
}Response Format
{
"user": {
"id": 1,
"email": "user@example.com",
"full_name": "John Doe",
"role": "doctor",
"organization_id": 194992
},
"token": {
"access_token": "eyJhbGciOiJIUzI1NiJ9...",
"refresh_token": "b1c2d3e4f5...",
"expires_in": 604800,
"created_at": "2025-09-17T20:28:05.391Z"
}
}Server-Side Implementation
⚠️ Security Notice
Always use your API key server-side. Never expose it in client-side code.
Python Flask Server
from flask import Flask, request, jsonify
import requests
import os
app = Flask(__name__)
@app.route('/api/authenticate', methods=['POST'])
def authenticate_user():
email = request.json.get('email')
if not email:
return jsonify({'success': False, 'error': 'Email required'}), 400
# Call ScribeMD API server-side
response = requests.post(
'https://api.scribemd.ai/api/users/tokens/passwordless_oauth',
headers={
'Authorization': f"Bearer {os.getenv('SCRIBEMD_API_KEY')}",
'Content-Type': 'application/json'
},
json={'email': email}
)
if response.status_code == 200:
data = response.json()
return jsonify({
'success': True,
'user': data['user'],
'token': data['token']
})
else:
return jsonify({
'success': False,
'error': response.json()
}), response.status_code
if __name__ == '__main__':
app.run(debug=True)Node.js Express Server
const express = require('express');
const axios = require('axios');
require('dotenv').config();
const app = express();
app.use(express.json());
app.post('/api/authenticate', async (req, res) => {
const { email } = req.body;
if (!email) {
return res.status(400).json({ success: false, error: 'Email required' });
}
try {
// Call ScribeMD API server-side
const response = await axios.post(
'https://api.scribemd.ai/api/users/tokens/passwordless_oauth',
{ email },
{
headers: {
'Authorization': `Bearer ${process.env.SCRIBEMD_API_KEY}`,
'Content-Type': 'application/json'
}
}
);
res.json({
success: true,
user: response.data.user,
token: response.data.token
});
} catch (error) {
res.status(error.response?.status || 500).json({
success: false,
error: error.response?.data || error.message
});
}
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});Test with cURL
# Test your server endpoint
curl -X POST http://localhost:3000/api/authenticate \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
# Expected response:
# {
# "success": true,
# "user": { "id": 1, "email": "user@example.com", ... },
# "token": { "access_token": "...", ... }
# }Client-Side Integration
Now call your server endpoint from the client-side to get tokens and initialize ScribeMD:
<script src="https://static.scribemd.ai/scribeMDwidget.min.js"></script>
<script>
async function authenticateAndInitialize(userEmail) {
try {
// Step 1: Call your server endpoint (secure - no API key exposed)
const response = await fetch('/api/authenticate', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: userEmail
})
});
const data = await response.json();
if (!data.success) {
throw new Error(data.error);
}
// Step 2: Initialize ScribeMD widget with tokens from your server
const result = await scribeMDWidget.initWithTokens({
tokens: data.token,
user: data.user
});
if (result.success) {
console.log('ScribeMD initialized successfully!');
// Widget is now ready for use
} else {
console.error('Failed to initialize:', result.error);
}
} catch (error) {
console.error('Authentication error:', error);
}
}
// Usage
authenticateAndInitialize('user@example.com');
</script>Complete Working Example
Step 1: Set up your server
Create a .env file:
SCRIBEMD_API_KEY=your_actual_api_key_here
# server.py (Python Flask)
from flask import Flask, request, jsonify
import requests
import os
app = Flask(__name__)
@app.route('/api/authenticate', methods=['POST'])
def authenticate_user():
email = request.json.get('email')
if not email:
return jsonify({'success': False, 'error': 'Email required'}), 400
# Call ScribeMD API server-side
response = requests.post(
'https://api.scribemd.ai/api/users/tokens/passwordless_oauth',
headers={
'Authorization': f"Bearer {os.getenv('SCRIBEMD_API_KEY')}",
'Content-Type': 'application/json'
},
json={'email': email}
)
if response.status_code == 200:
data = response.json()
return jsonify({
'success': True,
'user': data['user'],
'token': data['token']
})
else:
return jsonify({
'success': False,
'error': response.json()
}), response.status_code
if __name__ == '__main__':
app.run(debug=True)Step 2: Test your server
# Start your server
python server.py
# Test in another terminal
curl -X POST http://localhost:5000/api/authenticate \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
# Should return:
# {
# "success": true,
# "user": { "id": 1, "email": "user@example.com", ... },
# "token": { "access_token": "...", ... }
# }Step 3: Create client HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>ScribeMD Integration</title>
</head>
<body>
<div id="app">
<h1>Healthcare Platform</h1>
<input type="email" id="emailInput" placeholder="Enter your email">
<button onclick="authenticateUser()">Sign In</button>
<div id="status"></div>
</div>
<script src="https://static.scribemd.ai/scribeMDwidget.min.js"></script>
<script>
async function authenticateUser() {
const email = document.getElementById('emailInput').value;
const statusDiv = document.getElementById('status');
if (!email) {
statusDiv.innerHTML = '<span style="color: red;">Please enter an email</span>';
return;
}
statusDiv.innerHTML = '<span style="color: blue;">Authenticating...</span>';
try {
// Call your server endpoint
const response = await fetch('/api/authenticate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: email })
});
const data = await response.json();
if (!data.success) {
throw new Error(data.error);
}
// Initialize ScribeMD widget
const result = await scribeMDWidget.initWithTokens({
tokens: data.token,
user: data.user
});
if (result.success) {
statusDiv.innerHTML = '<span style="color: green;">✓ Success! ScribeMD ready.</span>';
} else {
statusDiv.innerHTML = '<span style="color: red;">Failed to initialize</span>';
}
} catch (error) {
statusDiv.innerHTML = `<span style="color: red;">Error: ${error.message}</span>`;
}
}
</script>
</body>
</html>Error Handling
401 Unauthorized - Missing API Key
{
"error": "Missing API key"
}
401 Unauthorized - Invalid API Key
{
"error": "Invalid API key"
}
400 Bad Request - User Not Found
{
"msg": "Something went wrong."
}
Security Best Practices
- Always use server-side authentication - Never expose API keys in client-side code
- Store API keys in environment variables (ENV['SCRIBEMD_API_KEY'])
- Validate email format server-side before making API calls
- Handle authentication errors gracefully with proper HTTP status codes
- Use HTTPS for all API communications
- Implement rate limiting on your authentication endpoints
- Log authentication attempts for security monitoring
- Consider implementing session management for token refresh
Architecture Flow
- User enters email in your application
- Client sends email to your server-side endpoint
- Server validates email and calls ScribeMD API with your API key
- Server receives tokens and user data from ScribeMD
- Server returns tokens and user data to client
- Client initializes ScribeMD widget with received data