Introduction

ChatMed API Documentation

The ChatMed API gives your application access to enterprise-grade medical AI capabilities — conversational diagnosis support, medical image analysis, video teleconsultation, voice interaction, health monitoring, prescriptions, and emergency detection — through a single, unified REST interface.

HIPAA Compliant 99.9% Uptime SLA <200ms P95 Latency TLS 1.3 Encrypted

Base URL: https://api.chatmed.site/api/v1
All requests must be made over HTTPS. HTTP requests will be automatically redirected.

New here? Jump to the Quick Start guide and make your first API call in under 5 minutes.

Getting Started

Quick Start

Get up and running with the ChatMed API in minutes.

1

Create your account

Sign up at /register and confirm your email address.

2

Generate an API key

From your developer portal, create a new API key. Keys are prefixed with sk_live_ for production and sk_test_ for sandbox.

3

Make your first request

Pass your key in the X-API-Key header and call any endpoint.

cURL

# Your first ChatMed API call
curl -X POST "https://api.chatmed.site/api/v1/chat/message" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are symptoms of hypertension?"}'

4

Handle the response

All responses are JSON. Successful responses return HTTP 200. Check the Error Codes section for failure scenarios.

Authentication

The ChatMed API uses API keys for authentication. Include your key in every request using the X-API-Key header.

Keep your API key secret. Never expose it in client-side JavaScript, public repositories, or logs. Use environment variables or a secrets manager.

                
                
                
                
              

                  cURL
                
curl -X GET "https://api.chatmed.site/api/v1/users/me" \
  -H "X-API-Key: sk_live_YOUR_KEY_HERE"

                  JavaScript
                
const response = await fetch('https://api.chatmed.site/api/v1/users/me', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_YOUR_KEY_HERE',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
console.log(data);

                  Python
                
import requests

headers = {
    "X-API-Key": "sk_live_YOUR_KEY_HERE",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.chatmed.site/api/v1/users/me",
    headers=headers
)
print(response.json())

                  PHP
                
<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL           => "https://api.chatmed.site/api/v1/users/me",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER    => [
        "X-API-Key: sk_live_YOUR_KEY_HERE",
        "Content-Type: application/json"
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Rate Limiting

Rate Limits

Rate limits are applied per API key. When a limit is exceeded the API returns HTTP 429 Too Many Requests.

Plan	Requests / min	Requests / day	Concurrent
Starter	60	1,000	5
Professional	300	50,000	25
Enterprise	Unlimited	Unlimited	Unlimited

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Core API

Medical Chat

Send a medical question or symptom description and receive a structured AI-powered response with recommendations, disclaimers, and follow-up suggestions.

POST /api/v1/chat/message Send a medical message

Sends a conversational message to the medical AI. Maintains session context via session_id.

Request Body

Parameter	Type	Required	Description
message	string	required	The user's question or symptom description.
session_id	string	optional	Conversation session ID for context continuity.
language	string	optional	Response language code (e.g. `en`, `fr`, `ar`). Defaults to `en`.
profile_id	string	optional	Patient health profile ID for personalised context.

                    
                    
                    
                    
                  

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/chat/message" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I have had a headache for 3 days with sensitivity to light.",
    "session_id": "sess_abc123",
    "language": "en"
  }'

                      JavaScript
                    
const res = await fetch('https://api.chatmed.site/api/v1/chat/message', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'I have had a headache for 3 days with sensitivity to light.',
    session_id: 'sess_abc123',
    language: 'en'
  })
});
const data = await res.json();
console.log(data.response);

                      Python
                    
import requests

payload = {
    "message": "I have had a headache for 3 days with sensitivity to light.",
    "session_id": "sess_abc123",
    "language": "en"
}

res = requests.post(
    "https://api.chatmed.site/api/v1/chat/message",
    json=payload,
    headers={"X-API-Key": "sk_live_YOUR_KEY"}
)
data = res.json()
print(data["response"])

                      PHP
                    
<?php
$payload = json_encode([
    'message'  => 'I have had a headache for 3 days with sensitivity to light.',
    'session_id' => 'sess_abc123',
    'language' => 'en'
]);
$ch = curl_init('https://api.chatmed.site/api/v1/chat/message');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: sk_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['response'];
curl_close($ch);
?>

200 Response

JSON

{
  "response": "The symptoms you describe — persistent headache with photosensitivity — may indicate migraine or tension headache. Recommended: rest in a dark room, hydration, and OTC analgesics. If symptoms worsen or are accompanied by fever or stiff neck, seek immediate medical attention.",
  "session_id": "sess_abc123",
  "disclaimer": "This is AI-generated health information and does not constitute medical advice.",
  "urgency_level": "moderate",
  "follow_up_questions": ["Do you experience nausea?", "Any recent head trauma?"],
  "timestamp": "2025-01-15T10:30:00Z"
}

Core API

Medical Imaging

Upload medical images (X-rays, MRIs, dermatology photos) for AI-powered analysis and structured diagnostic insights.

POST /api/v1/medical-vision/analyze Analyze a medical image

Accepts image files up to 10 MB (JPEG, PNG, DICOM). Returns structured findings and confidence scores.

Request Body (multipart/form-data)

Parameter	Type	Required	Description
image	file	required	Image file. Supported: JPEG, PNG, DICOM.
analysis_type	string	optional	`general` \| `chest_xray` \| `dermatology` \| `mri`. Defaults to `general`.
language	string	optional	Response language. Defaults to `en`.

                    
                    
                    
                    
                  

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/medical-vision/analyze" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -F "image=@chest_xray.jpg" \
  -F "analysis_type=chest_xray"

                      JavaScript
                    
const form = new FormData();
form.append('image', imageFile);
form.append('analysis_type', 'chest_xray');

const res = await fetch('https://api.chatmed.site/api/v1/medical-vision/analyze', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk_live_YOUR_KEY' },
  body: form
});
const result = await res.json();
console.log(result.findings);

                      Python
                    
import requests

with open("chest_xray.jpg", "rb") as f:
    res = requests.post(
        "https://api.chatmed.site/api/v1/medical-vision/analyze",
        headers={"X-API-Key": "sk_live_YOUR_KEY"},
        files={"image": ("chest_xray.jpg", f, "image/jpeg")},
        data={"analysis_type": "chest_xray"}
    )
print(res.json()["findings"])

                      PHP
                    
<?php
$ch = curl_init('https://api.chatmed.site/api/v1/medical-vision/analyze');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => [
        'image'         => new CURLFile('/path/chest_xray.jpg', 'image/jpeg'),
        'analysis_type' => 'chest_xray'
    ],
    CURLOPT_HTTPHEADER => ['X-API-Key: sk_live_YOUR_KEY'],
]);
$result = json_decode(curl_exec($ch), true);
echo $result['findings'];
curl_close($ch);
?>

200 Response

JSON

{
  "analysis_id": "vis_01H9XYZ",
  "analysis_type": "chest_xray",
  "findings": "No acute cardiopulmonary abnormality detected. Lung fields are clear. Heart size normal.",
  "confidence": 0.94,
  "regions_of_interest": [],
  "disclaimer": "AI-assisted analysis. Always verify with a licensed radiologist."
}

Core API

Video Teleconsultation

Create and manage real-time video consultation sessions between patients and healthcare providers. Includes waiting room management, session signalling, and recording.

POST /api/v1/consultations/video/create Create a video session

Creates a new video consultation session. Returns a session token and connection credentials for both patient and doctor.

Parameter	Type	Required	Description
doctor_id	string	required	Unique identifier of the healthcare provider.
patient_id	string	required	Unique identifier of the patient.
scheduled_at	string	optional	ISO 8601 datetime for scheduled sessions. Omit for immediate sessions.
language	string	optional	Session language code (e.g. `en`, `fr`, `ar`). Defaults to `en`.
enable_recording	boolean	optional	Record the session. Requires patient consent. Defaults to `false`.

                    
                    
                    
                    
                  

                      JavaScript
                    
const res = await fetch('https://api.chatmed.site/api/v1/consultations/video/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    doctor_id: 'doc_abc123',
    patient_id: 'pat_xyz789',
    language: 'en',
    enable_recording: false
  })
});
const { session_id, token, room_url } = await res.json();
// Open video call in iframe or redirect
window.open(room_url, '_blank');

                      Python
                    
import requests

res = requests.post(
    "https://api.chatmed.site/api/v1/consultations/video/create",
    json={
        "doctor_id": "doc_abc123",
        "patient_id": "pat_xyz789",
        "language": "en",
        "enable_recording": False
    },
    headers={"X-API-Key": "sk_live_YOUR_KEY"}
)
data = res.json()
print(f"Room URL: {data['room_url']}")

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/consultations/video/create" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"doctor_id":"doc_abc123","patient_id":"pat_xyz789","language":"en"}'

                      PHP
                    
<?php
$ch = curl_init('https://api.chatmed.site/api/v1/consultations/video/create');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'doctor_id'  => 'doc_abc123',
        'patient_id' => 'pat_xyz789',
        'language'   => 'en'
    ]),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['room_url'];
curl_close($ch);
?>

200 Response

JSON

{
  "session_id": "vs_01H9XYZ_abc",
  "room_url": "https://meet.chatmed.site/room/vs_01H9XYZ_abc",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "doctor_join_url": "https://meet.chatmed.site/room/vs_01H9XYZ_abc?role=doctor",
  "patient_join_url": "https://meet.chatmed.site/room/vs_01H9XYZ_abc?role=patient",
  "expires_at": "2025-01-15T12:00:00Z",
  "status": "waiting"
}

GET /api/v1/consultations/video/{session_id}/status Get session status

Returns the current status of a video consultation session: waiting, active, ended, or cancelled.

                    
                    
                    
                  

                      cURL
                    
curl "https://api.chatmed.site/api/v1/consultations/video/vs_01H9XYZ_abc/status" \
  -H "X-API-Key: sk_live_YOUR_KEY"

                      JavaScript
                    
const res = await fetch(
  'https://api.chatmed.site/api/v1/consultations/video/vs_01H9XYZ_abc/status',
  { headers: { 'X-API-Key': 'sk_live_YOUR_KEY' } }
);
const { status } = await res.json();
console.log(status); // 'waiting' | 'active' | 'ended'

                      Python
                    
import requests

res = requests.get(
    "https://api.chatmed.site/api/v1/consultations/video/vs_01H9XYZ_abc/status",
    headers={"X-API-Key": "sk_live_YOUR_KEY"}
)
print(res.json()["status"])

POST /api/v1/consultations/waiting-room/join Add patient to waiting room

Places a patient in the virtual waiting room queue for a consultation. The doctor is notified when the patient is ready.

Parameter	Type	Required	Description
patient_id	string	required	Patient identifier.
doctor_id	string	required	Doctor the patient is waiting for.
reason	string	optional	Reason for consultation / chief complaint.

Core API

Voice Assistant

Convert spoken medical queries to text, process them through the medical AI, and receive a synthesised voice response.

POST /api/v1/speech/transcribe Transcribe audio + get AI response

Accepts audio files (WAV, MP3, WebM, OGG up to 25 MB). Returns transcript and synthesised audio response.

Parameter	Type	Required	Description
audio	file	required	Audio file. WAV, MP3, WebM, OGG.
language	string	optional	Audio language hint. Defaults to auto-detect.
return_audio	boolean	optional	If `true`, returns synthesised audio URL in response.

                    
                    
                    
                  

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/speech/transcribe" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -F "audio=@question.wav" \
  -F "return_audio=true"

                      JavaScript
                    
const form = new FormData();
form.append('audio', audioFile); // File object from input or recorder
form.append('return_audio', 'true');

const res = await fetch('https://api.chatmed.site/api/v1/speech/transcribe', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk_live_YOUR_KEY' },
  body: form
});
const { transcript, response_text, audio_url } = await res.json();
console.log(transcript, response_text);

                      Python
                    
import requests

with open("question.wav", "rb") as f:
    res = requests.post(
        "https://api.chatmed.site/api/v1/speech/transcribe",
        headers={"X-API-Key": "sk_live_YOUR_KEY"},
        files={"audio": ("question.wav", f, "audio/wav")},
        data={"return_audio": "true"}
    )
data = res.json()
print(data["transcript"], data["response_text"])

Core API

Health Monitoring

Submit health metrics and receive AI-powered trend analysis, anomaly alerts, and actionable recommendations.

POST /api/v1/health/heart-rate Record heart rate measurement

Records a manual heart rate measurement for the authenticated user. Returns a category (normal, elevated, high) and a health interpretation. Triggers alerts for palpitations or irregular rhythm.

Parameter	Type	Required	Description
heart_rate_bpm	integer	required	Heart rate in beats per minute.
is_resting	boolean	optional	Whether the measurement was taken at rest. Default: true.
feels_regular	boolean	optional	Whether the heartbeat felt regular. Default: true.
has_palpitations	boolean	optional	Whether palpitations were experienced. Default: false.
has_shortness_of_breath	boolean	optional	Whether shortness of breath was experienced. Default: false.
measurement_duration_seconds	integer	optional	Duration of measurement in seconds. Default: 60.

                    
                    
                    
                    
                  

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/health/heart-rate" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"heart_rate_bpm":72,"is_resting":true,"feels_regular":true,"has_palpitations":false,"has_shortness_of_breath":false,"measurement_duration_seconds":60}'

                      JavaScript
                    
const res = await fetch('https://api.chatmed.site/api/v1/health/heart-rate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    heart_rate_bpm: 72,
    is_resting: true,
    feels_regular: true,
    has_palpitations: false,
    has_shortness_of_breath: false,
    measurement_duration_seconds: 60
  })
});
const data = await res.json();
console.log(data);

                      Python
                    
import requests

res = requests.post(
    "https://api.chatmed.site/api/v1/health/heart-rate",
    json={
        "heart_rate_bpm": 72,
        "is_resting": True,
        "feels_regular": True,
        "has_palpitations": False,
        "has_shortness_of_breath": False,
        "measurement_duration_seconds": 60
    },
    headers={"X-API-Key": "sk_live_YOUR_KEY"}
)
print(res.json())

                      PHP
                    
<?php
$ch = curl_init('https://api.chatmed.site/api/v1/health/heart-rate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'heart_rate_bpm'             => 72,
        'is_resting'                  => true,
        'feels_regular'               => true,
        'has_palpitations'            => false,
        'has_shortness_of_breath'     => false,
        'measurement_duration_seconds' => 60
    ]),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
]);
echo curl_exec($ch);
?>

Core API

Prescriptions

Generate structured prescription documents, check drug interactions, and retrieve prescription history for a patient profile.

POST /api/v1/prescriptions/generate Generate a prescription

Creates a structured prescription based on diagnosis and patient profile. Includes drug interaction checks.

Note: AI-generated prescriptions are advisory only. They must be reviewed and approved by a licensed medical professional before use.

Parameter	Type	Required	Description
profile_id	string	required	Patient profile ID.
diagnosis	string	required	Diagnosed condition or ICD-10 code.
medications	array	optional	List of desired medications to include.

Core API

Emergency Detection

Real-time analysis of symptoms for life-threatening conditions. Returns urgency level, recommended actions, and nearest emergency resources.

POST /api/v1/emergency/detect Analyse for emergency conditions

Screens symptom descriptions for critical conditions (cardiac arrest, stroke, sepsis, etc.) with millisecond response times.

Parameter	Type	Required	Description
symptoms	string	required	Free-text symptom description.
location	object	optional	`{"lat": 48.85, "lng": 2.35}` for nearby resources.
profile_id	string	optional	Patient profile for medical history context.

                    
                    
                    
                    
                  

                      cURL
                    
curl -X POST "https://api.chatmed.site/api/v1/emergency/detect" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symptoms":"Severe chest pain radiating to left arm, profuse sweating","location":{"lat":48.8566,"lng":2.3522}}'

                      JavaScript
                    
const res = await fetch('https://api.chatmed.site/api/v1/emergency/detect', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    symptoms: 'Severe chest pain radiating to left arm, profuse sweating',
    location: { lat: 48.8566, lng: 2.3522 }
  })
});
const { urgency_level, actions } = await res.json();
if (urgency_level === 'critical') triggerEmergencyProtocol(actions);

                      Python
                    
import requests

res = requests.post(
    "https://api.chatmed.site/api/v1/emergency/detect",
    json={
        "symptoms": "Severe chest pain radiating to left arm, profuse sweating",
        "location": {"lat": 48.8566, "lng": 2.3522}
    },
    headers={"X-API-Key": "sk_live_YOUR_KEY"}
)
data = res.json()
print(data["urgency_level"], data["actions"])

                      PHP
                    
<?php
$ch = curl_init('https://api.chatmed.site/api/v1/emergency/detect');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'symptoms' => 'Severe chest pain radiating to left arm, profuse sweating',
        'location' => ['lat' => 48.8566, 'lng' => 2.3522]
    ]),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: sk_live_YOUR_KEY',
        'Content-Type: application/json'
    ],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['urgency_level'];
?>

200 Response

JSON

{
  "urgency_level": "critical",
  "suspected_condition": "Acute Myocardial Infarction",
  "confidence": 0.91,
  "actions": ["Call emergency services immediately (112/911)", "Administer aspirin if not contraindicated", "Keep patient still and calm"],
  "nearby_emergency": { "name": "Hôpital Lariboisière", "distance_km": 1.2, "phone": "+33 1 49 95 65 65" }
}

Reference

Error Codes

All errors return a JSON body with error, message, and code fields.

Error Response Shape

{
  "error": "unauthorized",
  "message": "Invalid or missing API key.",
  "code": 401,
  "request_id": "req_01H9XYZ_abc"
}

HTTP Status	Error	Description
400	bad_request	Missing or invalid request parameters.
401	unauthorized	API key is missing, invalid, or revoked.
403	forbidden	Your plan does not have access to this endpoint.
404	not_found	Requested resource does not exist.
413	payload_too_large	File upload exceeds the maximum allowed size.
422	validation_error	Request body failed schema validation.
429	rate_limit_exceeded	Too many requests. Check `X-RateLimit-Reset` header.
500	internal_error	Unexpected server error. Retry with exponential backoff.
503	service_unavailable	Temporary downtime. Check status page.

Implement exponential backoff for 429 and 503 errors. Start with a 1s delay, double it each retry, cap at 32s. Include the request_id when contacting support.

Interactive

Live API Tester

Test the ChatMed API directly from this page. Enter your API key and choose an endpoint to make a live request.

API Playground

Requests are made directly from your browser to the live API.

No key

API Key

Endpoint

Request Body (JSON)

Sending request…