What is the Diagnostic Engine?
The Diagnostic Engine is an AI-powered service that replicates a doctor's clinical reasoning to conduct intelligent medical interviews. It dynamically generates follow-up questions based on patient responses, ensuring a thorough assessment of symptoms and risk factors.
By building a detailed clinical context, the engine delivers a comprehensive output that includes differential diagnoses, triage advice, and specialist recommendations—enabling applications to provide personalized and accurate medical guidance.
Use cases
Differential diagnoses
Get a list of medical conditions the patient may have
Self-management advice
Provides practical guidance to help patients manage their symptoms safely at home
Triage recommendation
Suggests the appropriate level of medical urgency based on the patient's symptoms
Specialist recommendation
Recommends the appropriate medical specialty to consult with based on the patient's symptoms
API types
Conversations API
Initiate a conversation then send chat messages until our system gives diagnoses and recommendations
Stateless APIs
Run a stateless questioning or diagnosis from a list of findings. No conversation required.
For complete specifications and request/response shapes, see the API reference.
Conversation Workflow
The endpoints below work together for an interactive, multi-turn conversation. Create a conversation with patient details, then send each user message with the conversation ID; the engine returns assistant messages and eventually a diagnosis in the response.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/conversations | Create a conversation (state container). Returns conversation ID. |
| GET | /v1/conversations/{conversation_id} | Retrieve full conversation state — messages, findings, usage. |
| POST | /v1/chats | Send a message in an existing conversation. Returns the next assistant message or diagnosis. |
Workflow
Three main API calls: create a conversation, send messages (repeated), and optionally retrieve full conversation state.
Step 1 — Create a conversation
Send patient details (and optional personality/language) to POST /v1/conversations.
Receive a conversation id. No inference runs yet.
Step 2 — Send messages and get responses
Send the user message and conversation ID to POST /v1/chats.
Receive an assistant message (and updated findings). Repeat with new input until the response includes a diagnosis and is_complete: true.
Step 3 — Retrieve conversation
Call GET /v1/conversations/{conversation_id} to get the full state: messages, findings, and usage.
How it works
Stateless workflow
Send patient demographics and pre-collected findings in a single request to get a medical question or diagnosis. No conversation is created; no state is stored.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/question | Send input (findings array), coding_system, and patient. Returns the next follow-up question. |
| POST | /v1/diagnosis | Send input (findings array), coding_system, and patient. Returns a differential diagnosis. |
GET /v1/conversations/{conversation_id}) to run a stateless diagnosis without affecting that conversation.Requirements
- Authentication: The API uses Bearer token. Send the header:
Authorization: Bearer <your-api-key>.
API reference
How is this guide?