VoxChart — API Documentation

Quick Start

Three steps to get your first transcription:

1. Get an API Key

Go to the Test Console to see your API key, or generate one via the management endpoint.

2. Send Audio

// cURL example
curl -X POST https://voxchart.polsia.app/api/transcribe \
  -H "X-API-Key: vx_your_key_here" \
  -F "audio=@dictation.wav" \
  -F "note_type=note"
            

3. Get Structured Note

{
  "success": true,
  "data": {
    "formatted_note": "<b>Subjective</b><br>Chief Complaint:...",
    "plain_text": "SUBJECTIVE\nChief Complaint:...",
    "raw_transcript": "Patient is a 45-year-old male presenting with...",
    "summary": "45-year-old male presenting with acute lower back pain.",
    "metadata": {
      "note_type": "note",
      "date": "02/27/2026",
      "processing_time_seconds": 8.3
    }
  }
}
            

Authentication

All API calls require an API key passed via header:

Header	Value	Notes
X-API-Key	Your API key (e.g., `vx_abc123...`)	Required
Authorization	Bearer <your-api-key>	Alternative

Both header formats work. Choose whichever fits your .NET HttpClient setup.

Endpoints

POST /api/transcribe Auth Required

Upload an audio file and receive a structured SOAP note. This is the primary endpoint for integration.

Request (multipart/form-data)

Field	Type	Description
audio	File	Required — WAV, MP3, WebM, or M4A. Max 25MB.
note_type	String	Optional — `"note"` (default) for clinical notes with MM/DD/YYYY dates, or `"letter"` for correspondence with spelled-out dates.

Response

Field	Type	Description
data.formatted_note	String (HTML)	SOAP note with `<b>` headings. Ready to insert into rich text editors.
data.plain_text	String	Plain text version with ALL CAPS headings. For text fields or emails.
data.raw_transcript	String	Unprocessed Whisper transcription of the audio.
data.summary	String	One-sentence clinical summary of the encounter.
data.metadata	Object	note_type, date, audio_filename, audio_size_bytes, processing_time_seconds

.NET Core Integration Example

// C# — .NET Core HttpClient
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "vx_your_key");

using var content = new MultipartFormDataContent();
content.Add(new ByteArrayContent(audioBytes), "audio", "dictation.wav");
content.Add(new StringContent("note"), "note_type");

var response = await client.PostAsync(
    "https://voxchart.polsia.app/api/transcribe", content);
var json = await response.Content.ReadAsStringAsync();

// Parse JSON response — formatted_note contains HTML with bold headings
var result = JsonSerializer.Deserialize<TranscribeResponse>(json);
string formattedHtml = result.Data.FormattedNote;
                

GET /api/transcriptions Auth Required

List recent transcriptions for your API key. Useful for building history views.

Param	Type	Description
limit	Number	Optional — Max results (1-100, default 20)

GET /api/transcriptions/:id Auth Required

Get full details of a specific transcription including all text versions.

POST /api/keys Admin

Generate a new API key. Requires admin secret via X-Admin-Secret header or admin_secret in body.

Field	Type	Description
name	String	Optional — Label for the key (e.g., "Production")
admin_secret	String	Required — Admin authentication

GET /api/keys Admin

List all API keys with usage statistics. Requires X-Admin-Secret header.

DELETE /api/keys/:id Admin

Deactivate an API key. The key stops working immediately. Requires X-Admin-Secret header.

SOAP Note Format

All notes follow the standard SOAP format with physician-required formatting:

<b>Subjective</b>
<b>Chief Complaint:</b> Lower back pain x 3 days
<b>HPI:</b> Patient is a 45-year-old male presenting with...
<b>ROS:</b> Negative for fever, chills, weight loss...

<b>Objective</b>
<b>Vitals:</b> BP 128/82, HR 76, Temp 98.6°F
<b>Physical Exam:</b> Tenderness over L4-L5...

<b>Assessment</b>
Acute lumbar strain, likely muscular in origin.

<b>Plan</b>
1. Ibuprofen 600mg TID x 7 days
2. Physical therapy referral
3. Follow up in 2 weeks
            

Key formatting rules:

• All section headings wrapped in <b> tags
• Text starts on the line after the heading
• Blank line between each major section
• Clinical note dates: MM/DD/YYYY — Letter dates: spelled out (e.g., 27 February, 2026)

Error Codes

Status	Error	Meaning
400	Audio file required	No file attached to the request
400	Unsupported audio format	File is not WAV, MP3, WebM, or M4A
400	File too large	File exceeds 25MB Whisper limit
401	API key required	No X-API-Key or Authorization header
403	Invalid or inactive API key	Key doesn't exist or was deactivated
422	No speech detected	Audio file contains no recognizable speech
500	Transcription processing failed	Server error during Whisper or GPT processing

Limits & Notes

File size: 25MB max per request (Whisper API limit)

Audio formats: WAV, MP3, WebM, M4A, OGG

Processing time: Typically 5-15 seconds depending on audio length

CORS: Enabled for all origins (Access-Control-Allow-Origin: *)

Base URL: https://voxchart.polsia.app