API Reference

Complete documentation for all 14 PearMedica v1 endpoints. All requests use JSON and require Authorization: Bearer <api_key> unless noted otherwise.

Base URL: https://api.pearmedica.com

Format: JSON

Rate Limit: 100 req/min

POST

/v1/assessAPI Key (Bearer token)

Symptom Assessment

Core assessment endpoint. Accepts patient demographics and symptom evidence, returns differential diagnosis, triage level, and optional follow-up questions. Powers the conversational assessment loop.

Request Body

{
  "patient": {
    "age": 28,
    "sex": "female",
    "location": "lagos_nigeria"
  },
  "evidence": [
    { "id": "s_fever", "choice_id": "present", "duration_days": 3 },
    { "id": "s_headache", "choice_id": "present", "severity": "severe" }
  ],
  "risk_factors": [
    { "id": "rf_mosquito_exposure", "choice_id": "present" }
  ],
  "interview_id": "int_abc123"
}

Response

{
  "interview_id": "int_abc123",
  "conditions": [{ "name": "Malaria", "probability": "high", "icd_10": "B50" }],
  "triage": { "level": "urgent", "description": "Seek medical attention within 24 hours.", "timeframe": "within_24_hours" },
  "should_stop": false,
  "next_question": { "id": "q_1", "text": "Have you travelled to a rural area recently?", "options": ["yes", "no", "unknown"] },
  "red_flags": [],
  "nearest_facilities": [{ "name": "Lagos General Hospital", "distance_km": 2.3 }],
  "metadata": { "confidence": 0.87, "total_latency_ms": 1850 },
  "disclaimer": "This assessment is generated by PearMDx AI and does not constitute a medical diagnosis."
}

POST

/v1/parseAPI Key (Bearer token)

NLP Symptom Extraction

Extract structured symptoms and risk factors from free-text patient descriptions using NLP. Useful for chatbot and voice interfaces.

Request Body

{
  "text": "I have had fever and headaches for 3 days, with chills at night",
  "context": { "age": 28, "sex": "female", "location": "lagos_nigeria" }
}

Response

{
  "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": []
}

GET

/v1/symptomsAPI Key (Bearer token)

List Symptoms

Returns the full catalogue of symptoms recognised by PearMedica, including IDs, common names, and categories.

Response

{
  "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
}

GET

/v1/risk-factorsAPI Key (Bearer token)

List Risk Factors

Returns available risk factors (lifestyle, environmental, genetic) that can be submitted alongside symptoms for more accurate assessments.

Response

{
  "risk_factors": [
    { "id": "rf_mosquito_exposure", "name": "Mosquito exposure", "category": "environmental" },
    { "id": "rf_sickle_cell", "name": "Sickle cell trait", "category": "genetic" }
  ],
  "total": 40
}

GET

/v1/lab-testsAPI Key (Bearer token)

List Lab Tests

Returns available lab tests that PearMedica may recommend as part of a triage assessment.

Response

{
  "lab_tests": [
    { "id": "lt_malaria_rdt", "name": "Malaria Rapid Diagnostic Test", "category": "infectious" },
    { "id": "lt_fbc", "name": "Full Blood Count", "category": "general" }
  ],
  "total": 25
}

GET

/v1/conditions/{id}API Key (Bearer token)

Condition Detail

Returns detailed information about a specific condition, including description, prevalence data, symptoms, risk factors, treatment overview, and prevention tips.

Response

{
  "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": "..." }]
}

GET

/v1/conditions/{id}/educationAPI Key (Bearer token)

Patient Education

Returns plain-language patient education content for a specific condition. Localised for health literacy appropriate to the African context.

Response

{
  "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"]
}

GET

/v1/usageAPI Key (Bearer token)

Usage Statistics

Returns aggregated usage statistics for your tenant, including assessment counts, cost breakdown, and urgency distribution over a date range.

Response

{
  "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 }
}

GET

/v1/healthNone (public)

Health Check

Returns the operational status of all PearMedica services (database, cache, AI provider, knowledge base). Useful for monitoring integrations.

Response

{
  "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
}

POST

/v1/feedbackAPI Key (Bearer token)

Assessment Feedback

Submit feedback on an assessment's accuracy and usefulness. This data feeds into PearMedica's continuous improvement loop to refine future assessments.

Request Body

{
  "interview_id": "int_abc123",
  "accuracy_rating": 4,
  "was_helpful": true,
  "clinician_diagnosis": "Confirmed malaria via RDT",
  "notes": "Triage level was appropriate"
}

Response

{
  "id": "fb_xyz789",
  "status": "received",
  "message": "Thank you for your feedback."
}

GET

/v1/rationaleAPI Key (Bearer token)

Assessment Rationale

Retrieve the clinical reasoning behind a specific assessment, including evidence weighting, knowledge sources consulted, and validation results.

Query Parameters

interview_idstringrequiredThe interview ID from an assessmentExample: int_abc123

Response

{
  "interview_id": "int_abc123",
  "reasoning": "Based on fever (3 days), headache, and Lagos location...",
  "evidence_weights": [{ "symptom": "fever", "weight": 0.35 }],
  "sources_consulted": 5,
  "validation_summary": { "passed": true, "triage_overridden": false }
}

GET

/v1/searchAPI Key (Bearer token)

Knowledge Search

Search the PearMedica knowledge base for conditions, symptoms, and medical concepts. Supports partial matching.

Query Parameters

qstringrequiredSearch query stringExample: malaria

Response

{
  "results": [
    { "type": "condition", "id": "c_malaria", "name": "Malaria", "relevance": 0.95 },
    { "type": "symptom", "id": "s_fever", "name": "Fever", "relevance": 0.82 }
  ],
  "total": 12
}

POST

/v1/keys/rotateAPI Key (Bearer token)

Rotate API Key

Generate a new API key and invalidate the current one. Returns the new key — store it securely as it won't be shown again.

Request Body

{
  "label": "Production Server - Rotated Feb 2026"
}

Response

{
  "id": "key_new123",
  "key": "sk_live_new_generated_key",
  "prefix": "sk_live_new",
  "label": "Production Server - Rotated Feb 2026",
  "created_at": "2026-02-27T12:00:00Z"
}

POST

/v1/ingestAdmin API Key

Document Ingestion

Ingest medical documents into the PearMedica knowledge base. Admin-only endpoint for adding new clinical guidelines, protocols, and research data.

Request Body

{
  "title": "WHO Malaria Treatment Guidelines 2025",
  "source_type": "pdf",
  "source": "who_guideline",
  "country": "NG",
  "tags": ["malaria", "treatment", "who"]
}

Response

{
  "document_id": "doc_abc123",
  "status": "processing",
  "chunks_created": 0,
  "message": "Document queued for ingestion."
}

Error Codes

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.

Authentication Error Handling