Loading documentation…
Loading documentation…
Complete documentation for all 13 PearMedica v1 endpoints. All requests use JSON and require Authorization: Bearer <api_key> unless noted otherwise.
List endpoints (GET /v1/symptoms, GET /v1/risk-factors, GET /v1/lab-tests) support offset-based pagination via two query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 20 | Maximum results per page (1–50) |
| offset | integer | 0 | Number of results to skip |
GET /v1/symptoms?limit=10&offset=20Responses include a total field so you can calculate total pages: Math.ceil(total / limit).
/v1/assessBillableAPI Key (Bearer token)Core assessment endpoint. Accepts patient demographics and symptom evidence, returns differential diagnosis, triage level, and optional follow-up questions. Powers the conversational assessment loop.
{
"patient": {
"age": 28,
"sex": "female",
"location": "lagos_nigeria"
},
"evidence": [
{ "id": "s_fever", "choice_id": "present", "source": "initial", "duration_days": 3 },
{ "id": "s_headache", "choice_id": "present", "source": "initial", "severity": "severe" }
],
"risk_factors": [
{ "id": "rf_mosquito_exposure", "choice_id": "present" }
],
"interview_id": "int_abc123"
}{
"interview_id": "int_abc123",
"conditions": [{ "name": "Malaria", "probability": 0.82, "icd10": "B50", "snomed_ct": "61462000", "rationale_one_line": "High fever with headache and mosquito exposure in Lagos is strongly suggestive of P. falciparum malaria." }],
"triage": { "level": "urgent", "description": "Seek medical attention within 24 hours.", "timeframe": "within_24_hours", "recommended_specialist": { "id": "sp_internal_medicine", "name": "Internal Medicine" }, "recommended_channel": "personal_visit" },
"should_stop": false,
"next_question": { "id": "q_1", "text": "Have you travelled to a rural area recently?", "options": [{ "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" }, { "id": "unknown", "label": "Not sure" }] },
"red_flags_present": ["High fever (≥39°C) with severe headache"],
"red_flags_watch_for": ["Confusion or altered consciousness", "Difficulty breathing"],
"clinical_warnings": [],
"recommended_investigations": [{ "priority": 1, "test_name": "Malaria RDT", "purpose": "Confirm P. falciparum infection", "urgency": "immediate" }],
"nearest_facilities": [{ "name": "Lagos General Hospital", "distance_km": 2.3 }],
"metadata": { "confidence": 0.87, "total_latency_ms": 1850, "escalation_tier": 3, "phi_tokenized": true },
"disclaimer": "This assessment is generated by PearMDx AI and does not constitute a medical diagnosis."
}/v1/parseFreeAPI Key (Bearer token)Extract structured symptoms and risk factors from free-text patient descriptions using NLP. Useful for chatbot and voice interfaces.
{
"text": "I have had fever and headaches for 3 days, with chills at night",
"context": { "age": 28, "sex": "female", "location": "lagos_nigeria" }
}{
"symptoms": [
{ "id": "s_fever", "name": "Fever", "confidence": 0.95, "duration_days": 3 },
{ "id": "s_headache", "name": "Headache", "confidence": 0.92, "duration_days": 3 },
{ "id": "s_chills", "name": "Chills", "confidence": 0.88 }
],
"risk_factors": []
}/v1/symptomsFreeAPI Key (Bearer token)Returns the full catalogue of symptoms recognised by PearMedica, including IDs, common names, and categories.
{
"symptoms": [
{ "id": "s_fever", "name": "Fever", "common_name": "High temperature", "category": "general" },
{ "id": "s_headache", "name": "Headache", "common_name": "Head pain", "category": "neurological" }
],
"total": 150
}/v1/risk-factorsFreeAPI Key (Bearer token)Returns available risk factors (lifestyle, environmental, genetic) that can be submitted alongside symptoms for more accurate assessments.
{
"risk_factors": [
{ "id": "rf_mosquito_exposure", "name": "Mosquito exposure", "category": "environmental" },
{ "id": "rf_sickle_cell", "name": "Sickle cell trait", "category": "genetic" }
],
"total": 40
}/v1/lab-testsFreeAPI Key (Bearer token)Returns available lab tests that PearMedica may recommend as part of a triage assessment.
{
"lab_tests": [
{ "id": "lt_malaria_rdt", "name": "Malaria Rapid Diagnostic Test", "category": "infectious" },
{ "id": "lt_fbc", "name": "Full Blood Count", "category": "general" }
],
"total": 25
}/v1/conditions/{id}FreeAPI Key (Bearer token)Returns detailed information about a specific condition, including description, prevalence data, symptoms, risk factors, treatment overview, and prevention tips.
{
"id": "c_malaria",
"name": "Malaria (Plasmodium falciparum)",
"description": "Parasitic infection transmitted by Anopheles mosquitoes...",
"prevalence": { "global": "high", "africa": "very_high" },
"symptoms": ["fever", "chills", "headache", "sweating"],
"risk_factors": ["mosquito_exposure", "no_antimalarial_prophylaxis"],
"treatment_overview": "Artemisinin-based combination therapy (ACT)",
"resources": [{ "title": "WHO Malaria Guidelines", "url": "..." }]
}/v1/conditions/{id}/educationFreeAPI Key (Bearer token)Returns plain-language patient education content for a specific condition. Localised for health literacy appropriate to the African context.
{
"condition_id": "c_malaria",
"title": "Understanding Malaria",
"summary": "Malaria is a serious disease spread by mosquito bites...",
"key_facts": ["Preventable with bed nets", "Treatable when caught early"],
"when_to_seek_care": "If you have fever with chills lasting more than 2 days",
"prevention_tips": ["Use insecticide-treated bed nets", "Take antimalarial medication"]
}/v1/usageFreeAPI Key (Bearer token)Returns aggregated usage statistics for your tenant, including assessment counts, cost breakdown, and urgency distribution over a date range.
{
"period": { "start": "2026-02-01", "end": "2026-02-28" },
"total_assessments": 1247,
"breakdown": {
"by_urgency": { "emergency": 45, "urgent": 312, "routine": 678, "self-care": 212 },
"top_conditions": [{ "name": "Malaria", "count": 189 }]
},
"cost": { "total_naira": 24940, "current_tier": "professional", "usage_percentage": 62.35 }
}/v1/healthFreeNone (public)Returns the operational status of all PearMedica services (database, cache, AI provider, knowledge base). Useful for monitoring integrations.
{
"status": "healthy",
"timestamp": "2026-02-16T12:00:00Z",
"version": "1.0.0",
"checks": {
"database": "healthy",
"redis": "healthy",
"ai_provider": "healthy",
"knowledge_base": "healthy"
},
"uptime_seconds": 2592000
}/v1/rationaleFreeAPI Key (Bearer token)Retrieve the clinical reasoning behind a specific assessment, including evidence weighting, knowledge sources consulted, and validation results.
{
"assessment_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"assessment_id": "550e8400-e29b-41d4-a716-446655440000",
"interview_id": "int_abc123",
"reasoning": "Assessment analysed 3 potential condition(s) with 87.0% confidence. Model: gpt-4o. Triage level matches LLM output.",
"conditions": [{ "id": "c_malaria", "name": "Malaria", "probability": 0.82, "evidence_supporting": ["fever", "headache", "mosquito_exposure"], "evidence_against": [], "explanation": "Malaria is ranked #1 with 82.0% probability. Supporting evidence: fever, headache, mosquito_exposure." }],
"triage": { "level": "urgent", "rationale": "Triage level 'urgent' was determined by the assessment model. Seek medical attention within 24 hours.", "overridden": false, "override_reason": null },
"metadata": { "model_used": "gpt-4o", "confidence": 0.87, "generated_at": "2026-02-16T12:00:00Z", "processing_time_ms": 1850 }
}/v1/searchFreeAPI Key (Bearer token)Search the PearMedica knowledge base for conditions, symptoms, and medical concepts using fuzzy trigram matching.
phrasestringrequiredSearch query string (1–200 characters)Example: malariasexstringOptional sex filter (male, female, other)Example: femalemax_resultsintegerMaximum results to return (1–20, default: 8)Example: 8{
"data": [
{ "id": "c_malaria", "name": "Malaria", "type": "condition", "category": "infectious", "similarity": 0.95 },
{ "id": "s_fever", "name": "Fever", "type": "symptom", "category": "general", "similarity": 0.82 }
],
"meta": { "total": 2, "phrase": "malaria", "timestamp": "2026-02-16T12:00:00Z" }
}/v1/fhir/assessBillableAPI Key (Bearer token)FHIR R4-compatible assessment endpoint. Accepts and returns standard FHIR Bundle resources, enabling plug-and-play integration with FHIR-aware EMR/EHR systems including Epic, Cerner, and OpenMRS.
{
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "Patient",
"gender": "female",
"birthDate": "1998-01-01"
}
},
{
"resource": {
"resourceType": "Observation",
"code": { "coding": [{ "system": "http://pearmedica.com/symptoms", "code": "s_fever" }] },
"valueString": "present"
}
}
]
}{
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "RiskAssessment",
"prediction": [{ "outcome": { "text": "Malaria" }, "qualitativeRisk": { "text": "high" } }]
}
}
]
}/v1/fhir/metadataFreeNone (public)Returns PearMedica's FHIR R4 CapabilityStatement, enabling integration engines to auto-discover supported resources, operations, and search parameters.
{
"resourceType": "CapabilityStatement",
"status": "active",
"kind": "instance",
"fhirVersion": "4.0.1",
"format": ["json"],
"rest": [{
"mode": "server",
"resource": [{ "type": "RiskAssessment" }, { "type": "Patient" }]
}]
}| Code | Status | Description |
|---|---|---|
| 400 | Bad Request | Invalid request body or missing required fields. |
| 401 | Unauthorized | Missing or invalid API key. |
| 403 | Forbidden | API key does not have permission for this endpoint. |
| 404 | Not Found | Resource not found (e.g., invalid condition ID). |
| 429 | Rate Limited | Request rate exceeded. Default: 100 req/min per key. |
| 500 | Internal Error | Unexpected server error. Contact support. |
| 503 | Service Unavailable | PearMDx degraded mode — LLM provider unreachable. |
Receive real-time notifications when events occur in your PearMedica account. Configure webhook endpoints, subscribe to event types, and verify payloads with HMAC-SHA256 signatures.
| Event | Description |
|---|---|
| assessment.completed | Fired when a clinical assessment reaches a terminal state. |
| adverse_event.created | Fired when an adverse event is flagged for regulatory review. |
| usage.threshold_reached | Fired when API usage hits 80% or 100% of the tier quota. |
| api_key.expiring | Fired 7 days before an API key's scheduled expiration. |
/v1/webhooksRegister a new webhook endpoint/v1/webhooksList all registered webhooks/v1/webhooks/{id}Remove a webhook endpointWant early access to webhooks?
Request Early Access