API Reference · v0.1

MedSure AI HTTP API

All endpoints live under /api/public/*. Every request must include an X-API-Key header. Keys are issued from the admin console and can be revoked at any time.

GET/api/public/health

Liveness probe. Returns service metadata. No auth required.

curl https://your-domain.lovable.app/api/public/health
# → { "status": "ok", "service": "MedSure AI", "version": "0.1.0" }

POST/api/public/validate

The main endpoint. Given a diagnosis, prescription, and insurer, returns ICD validation, drug-coverage decisions, interaction warnings, dosage alerts, guideline score, and an overall approval probability.

Request body

{
  "patient_age": 65,                 // int, optional (0-130)
  "patient_sex": "F",                // "M" | "F", optional
  "diagnosis":   "Type 2 Diabetes",  // required
  "icd10":       "E11",              // optional
  "insurance":   "Jubilee Health",   // required; matches insurer name
  "prescription": ["Empagliflozin", "Metformin"],
  "clinical_notes": "HbA1c 8.9, no ketosis"   // optional
}

Response 200

{
  "status": "approved_likely",       // approved_likely | review_needed | high_risk | denied_likely
  "approval_probability": 92,        // 0-100
  "icd_validation": {
    "provided_icd10": "E11",
    "matched_icd10":  "E11",
    "matched_icd11":  "5A11",
    "description":    "Type 2 diabetes mellitus",
    "confidence":     100,
    "ai_suggested":   false
  },
  "drug_coverage": [
    { "drug": "Empagliflozin", "covered": true, "requires_preauth": true,
      "required_documents": ["Consultant note","Recent labs"],
      "alternative": null, "notes": "Preauth required" },
    { "drug": "Metformin",     "covered": true, "requires_preauth": false,
      "required_documents": [], "alternative": null, "notes": "Standard cover" }
  ],
  "interactions": [],
  "dosage_alerts": [],
  "guideline_score": 95,
  "recommendations": [
    "Empagliflozin requires pre-authorization. Attach: Consultant note, Recent labs."
  ],
  "ai_reasoning": "Combination is guideline-aligned for T2DM with cardiorenal benefit.",
  "request_id": "b7…",
  "latency_ms": 812
}

POST/api/public/icd/lookup

Free-text diagnosis → ICD-10/ICD-11 code with a confidence score. Falls back to AI suggestion when no direct match exists.

POST /api/public/icd/lookup
{ "diagnosis": "acute bacterial pneumonia" }

# → { "matched_icd10":"J15.9","matched_icd11":"CA40.Z","confidence":85,"ai_suggested":false }

Errors

401 unauthorizedMissing or invalid X-API-Key.

400 invalid_inputZod validation failed. See `details`.

500 server_errorEngine failure. Retry with exponential backoff.

Integration checklist

Store the API key in your HMIS server-side config, never in the client.
Call `/validate` on prescription save; block submission on `denied_likely`.
Show `recommendations[]` inline in the doctor's HMIS panel.
Log the `request_id` alongside your HMIS visit ID for traceability.
Retry 5xx with jitter; 4xx should surface to the clinician verbatim.