RESTful API for medical diagnosis assistance and clinical documentation. Get AI-powered differential diagnoses and extract structured medical data from doctor–patient conversations.
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer ymed_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCreate API keys at the Developers Portal. Keys work with web apps, Flutter, and any HTTP client.
Generate a differential diagnosis based on patient symptoms and clinical information.
{
"symptoms": string[], // Required: Array of symptom strings
"patientAge": number, // Optional: Patient age in years
"patientSex": "male" | "female" | "other", // Optional: Patient sex
"medicalHistory": string[], // Optional: Array of medical history items
"currentMedications": string[], // Optional: Array of current medications
"vitalSigns": { // Optional: Vital signs object
"temperature": number, // Temperature in Celsius
"bloodPressure": string, // Blood pressure (e.g., "120/80")
"heartRate": number, // Heart rate in bpm
"respiratoryRate": number // Respiratory rate per minute
}
}curl -X POST http://localhost:3002/api/v1/diagnosis \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"symptoms": ["fever", "cough", "headache"],
"patientAge": 35,
"patientSex": "male",
"medicalHistory": ["hypertension"],
"currentMedications": ["lisinopril"],
"vitalSigns": {
"temperature": 38.5,
"bloodPressure": "120/80",
"heartRate": 85,
"respiratoryRate": 18
}
}'{
"success": true,
"data": {
"primaryDiagnosis": {
"diagnosis": "Acute viral upper respiratory infection",
"percentage": 85
},
"alternativeDiagnoses": [
{
"diagnosis": "Community-acquired pneumonia",
"percentage": 60
},
{
"diagnosis": "Acute bronchitis",
"percentage": 60
},
{
"diagnosis": "COVID-19",
"percentage": 60
}
]
},
"metadata": {
"responseTime": "7144ms"
}
}{
"error": "Unauthorized",
"message": "Missing or invalid Authorization header"
}{
"error": "Validation error",
"details": [
{
"path": ["symptoms"],
"message": "At least one symptom is required"
}
]
}{
"error": "Internal server error",
"message": "An error occurred generating the diagnosis"
}Extract structured medical data from a medical conversation (doctor–patient transcript). Returns chief complaints, past history, medications, allergies, vital signs, review of systems, and more.
{
"conversation": string // Required: Medical conversation transcript to analyze
}curl -X POST http://localhost:3002/api/v1/medical-conversation \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"conversation": "Doctor: What brings you in today?\nPatient: I have had a fever and cough for three days. Also a headache.\nDoctor: Any past medical conditions?\nPatient: I have hypertension. I take lisinopril.\nDoctor: Any allergies?\nPatient: Penicillin.\nDoctor: Blood pressure 128/82, temp 38.2, heart rate 88."
}'{
"success": true,
"data": {
"chiefComplaints": ["fever", "cough", "headache"],
"historyOfPresentIllness": "Fever and cough for three days with headache.",
"pastMedicalHistory": ["hypertension"],
"pastSurgicalHistory": [],
"medications": ["lisinopril"],
"allergies": ["penicillin"],
"familyHistory": [],
"socialHistory": "",
"vitalSigns": {
"temperature": 38.2,
"bloodPressure": "128/82",
"heartRate": 88,
"respiratoryRate": null,
"oxygenSaturation": null,
"weight": null,
"height": null
},
"reviewOfSystems": {},
"physicalExamFindings": "",
"assessmentAndPlan": []
},
"metadata": {
"responseTime": "3200ms"
}
}Same as diagnosis: 401 Unauthorized, 400 Validation error (e.g. missing conversation), 429 Rate limit, 500 Internal server error.
Same as /api/v1/medical-conversation, but accepts a doctor–patient audio recording instead of text. The endpoint runs speech-to-text (Whisper) and then the same Deepseek model to extract structured clinical data.
multipart/form-data: - file: audio/webm, audio/wav, or audio/mpeg (required) - language: optional language hint (e.g. "en")
curl -X POST http://localhost:3002/api/v1/medical-conversation/audio \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@conversation.webm"
The response body matches /api/v1/medical-conversation exactly (same data structure), with an additional metadata.transcript and metadata.inputType: "audio".
const response = await fetch('http://localhost:3002/api/v1/diagnosis', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
symptoms: ['fever', 'cough'],
patientAge: 35,
patientSex: 'male',
medicalHistory: ['hypertension'],
currentMedications: ['lisinopril'],
vitalSigns: {
temperature: 38.5,
bloodPressure: '120/80',
heartRate: 85,
respiratoryRate: 18
}
})
});
const data = await response.json();
console.log(data);import requests
url = 'http://localhost:3002/api/v1/diagnosis'
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
}
data = {
'symptoms': ['fever', 'cough'],
'patientAge': 35,
'patientSex': 'male',
'medicalHistory': ['hypertension'],
'currentMedications': ['lisinopril'],
'vitalSigns': {
'temperature': 38.5,
'bloodPressure': '120/80',
'heartRate': 85,
'respiratoryRate': 18
}
}
response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)conversation string (transcript); response includes chief complaints, past history, medications, allergies, vital signs, review of systems, etc.