API Reference

EHR Copilot API

v1.0.0 · OpenAPI 3.0.3 · Base URL: http://localhost:3000

POST/api/session/process

Process a therapy session transcript

Runs the full EHR Copilot agent pipeline — transcript quality check → SOAP note generation → risk analysis → DSM-5 diagnostic suggestions → treatment plan — and returns a ReviewPackage for clinician review.

Request Body

Field	Type	Description
`session.transcript`*	string	Full session transcript text
`session.sessionNumber`*	integer	Session number (≥1)
`session.sessionType`*	enum	intake \| follow_up \| crisis
`session.modality`	enum	in_person \| telehealth
`patient.id`*	string	Anonymized patient ID — no real PII
`patient.age`*	integer	1–120
`patient.knownDiagnoses`	string[]	ICD-10/DSM-5 codes
`clinicianPreferences.noteVerbosity`	enum	concise \| standard \| detailed

Response Fields

Field	Type	Description
`sessionId`	string	Unique session ID
`overallRiskLevel`	enum	none \| low \| moderate \| high \| critical
`riskFlags[]`	RiskFlag[]	Detected clinical risk signals
`soapNote`	SOAPNote	Subjective, Objective, Assessment, Plan sections
`diagnosisSuggestions[]`	DiagnosisSuggestion[]	DSM-5 matches with confidence
`treatmentPlan`	TreatmentPlan	Goals and interventions
`auditLog[]`	AuditEntry[]	Agent action trail

200Success — ReviewPackage returned

400Validation error

422Transcript quality too low — includes qualityScore

429Rate limit exceeded (10 req/min per IP)

500Internal error

cURL

curl -X POST http://localhost:3000/api/session/process \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "transcript": "Clinician: How have you been?...",
      "sessionNumber": 7,
      "sessionType": "follow_up",
      "modality": "telehealth"
    },
    "patient": { "id": "anon_abc", "age": 34 }
  }'

JavaScript (fetch)

const res = await fetch('/api/session/process', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ session, patient }),
});
const reviewPackage = await res.json();
const sessionId = res.headers.get('X-Session-Id');

POST/api/session/revise

Revise a SOAP section with AI feedback (SSE streaming)

Accepts clinician feedback and streams a revised version of the specified section using Server-Sent Events. Each event is a JSON token fragment. The final event contains the complete revised text with confidence and provenance.

Request Body

Field	Type	Description
`section`*	enum	subjective \| objective \| assessment \| plan
`currentDraft`*	string	Current section text
`feedback`*	string	Clinician revision instruction (max 500 chars)
`approvedSections`*	object	Map of already-approved section content for context
`transcript`*	string	Original session transcript

Response Fields

Field	Type	Description
`token`	string	Streaming token (each SSE event)
`done`	boolean	True on final event
`content`	string	Complete revised text (final event only)
`confidence`	number	AI confidence 0–1 (final event only)
`provenanceTag`	string	"ai_revised" (final event only)

200Returns text/event-stream — consume with ReadableStream

400Validation error

500Stream failed

cURL

curl -X POST http://localhost:3000/api/session/revise \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "section": "subjective",
    "currentDraft": "Patient presents with...",
    "feedback": "Add more detail about sleep patterns",
    "approvedSections": {},
    "transcript": "Clinician: ..."
  }'

JavaScript (fetch)

const res = await fetch('/api/session/revise', {
  method: 'POST',
  body: JSON.stringify({ section, currentDraft, feedback, approvedSections, transcript }),
});
const reader = res.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = new TextDecoder().decode(value);
  // Parse SSE lines: 'data: {...}'
}

POST/api/session/finalize

Finalize session and export as FHIR R4 Bundle

Validates that all SOAP sections are clinician-approved, then constructs a FHIR R4 Bundle containing a DocumentReference, section Observations, DSM-5 Conditions, and risk flag Observations. Returns application/fhir+json.

Request Body

Field	Type	Description
`reviewPackage`*	ReviewPackage	The complete reviewed package from Zustand
`approvedSections`*	Record<string, boolean>	Map of section → approved status
`patientId`	string	Anonymized patient ID (defaults to "anonymous")
`sessionId`	string	Session identifier

Response Fields

Field	Type	Description
`resourceType`	string	"Bundle"
`type`	string	"document"
`entry[]`	object[]	DocumentReference + Observations + Conditions
`meta.tag[]`	Coding[]	ai-assisted + clinician-reviewed tags

200FHIR R4 Bundle returned (Content-Type: application/fhir+json)

400Validation error

422Not all sections approved — missing[] returned

500Build failed

cURL

curl -X POST http://localhost:3000/api/session/finalize \
  -H "Content-Type: application/json" \
  -d '{
    "reviewPackage": { ... },
    "approvedSections": {
      "subjective": true, "objective": true,
      "assessment": true, "plan": true
    },
    "patientId": "anon_abc"
  }'

JavaScript (fetch)

const res = await fetch('/api/session/finalize', {
  method: 'POST',
  body: JSON.stringify({ reviewPackage, approvedSections, patientId }),
});
const fhirBundle = await res.json();
// Save as .json file with Content-Type: application/fhir+json

EHR Copilot API v1.0.0 · MIT License · AI-assisted clinical documentation