Start Conversation
Creates a new healthcare consultation and begins AI triage.
The contextMessage should be a first-person narrative describing symptoms, duration, severity, and relevant medical history.
Authorizations
OAuth 2.1 with PKCE
Body
Input for starting a conversation.
Important: Format contextMessage as a first-person narrative, not a clinical summary. Include symptom, duration, severity, associated symptoms, and history.
First-person narrative of health concern
"I've had a sore throat for 3 days. It started with a scratchy\nfeeling and now it hurts to swallow. I don't have a fever but\nI've been feeling tired. I had strep throat last year with\nsimilar symptoms.\n"
ISO 3166-2 code for where the patient is physically located right now (care is licensed by current location, not home address). An unsupported region is refused with REGION_NOT_SUPPORTED.
"US-CA"
Response
Consultation started
Response after starting a new conversation. The request returns as soon as the conversation is created (fast-ack) — it does NOT block for the first triage reply. Poll GET /api/consultations/{id} (or configure a webhook) to receive the AI's response.
The conversation ID
A conversation is a continuous thread — it never "closes." There is no terminal CLOSED/CANCELED status: a finished or canceled request simply leaves the conversation IDLE with its visit history intact.
- IDLE: AI-only, nothing in progress. Re-engageable — sending a message re-runs triage
- TRIAGING: AI is gathering symptom information on a live request
- PAYMENT_REQUIRED: Triage complete, awaiting payment confirmation (or dismissal)
- MATCHING: Being matched with a healthcare provider
- WITH_PROVIDER: A provider is connected (messaging is asynchronous)
- EMERGENCY: Urgent care advised — user should call 911 (not re-engageable)
IDLE, TRIAGING, PAYMENT_REQUIRED, MATCHING, WITH_PROVIDER, EMERGENCY