Chat agent
The AI chat endpoint — a tool-using agent over patient data.
The chat endpoint runs a tool-using AI agent over the clinic's patient data. It requires
a signed-in user, an active clinic, and patient:read.
| Method | Path | Auth | Returns |
|---|---|---|---|
POST | /api/chat | patient:read | A streamed UI-message response (SSE) |
Request
{
"messages": [ /* AI SDK UI messages */ ],
"model": "claude-sonnet-4-6",
"effort": "medium"
}The model selects the provider too (e.g. a claude-* id routes to Anthropic, gpt-*
to OpenAI, gemini-* to Gemini, the ollama sentinel to your local model). The matching
provider key from your AI config is used. If no key is configured for the
chosen provider, the request fails with a clear message.
What the agent can do
The agent can display and add data — but never edits, deletes, or alters the database structure. Every add is a dry-run proposal that streams an approval card; the record is written only after the clinician approves, through the existing RBAC-gated REST endpoint (so an under-privileged role is rejected at commit).
Display (read):
getPatient— look up a patient by file number and render record cards.getPatientLabs— pull labs + trend and render a lab chart with high/low flags.searchPatients— find patients by name, then look one up.listAppointments/listTasks/listPrescriptions— render the clinic's schedule, task queue, or prescriptions as list cards.
Add (propose → approve, nothing written until approved):
proposeAppointment/proposeTask/proposePrescription— validate a new record and show an approval card. On Add, the client commits via/api/appointments,/api/tasks, or/api/prescriptions.previewImport— a dry run for migration (or a single add): validates records parsed from an uploaded export and shows an approval card. Nothing is written until the clinician approves and the client callsPOST /api/ai/import.
All tools run under the caller's role scoping (a doctor only sees their own panel;
reception sees demographics only) — identical to the patient routes.
Response
The endpoint streams an AI-SDK UI-message stream. Alongside the assistant's text it
emits custom data parts the clinician's UI renders as rich cards:
data-patientCard, data-labCard, data-importPreview, data-appointmentList,
data-taskList, data-prescriptionList, data-actionPreview (an add awaiting approval),
data-step (a live Chain-of-Thought step), and a data-veilNotice flag.
These data parts carry the real record data straight to the clinician. On external providers the model itself only ever receives Veil-redacted results.