docs/api_reference.md

API Reference — DDI Checker

REST API served by app.py on port 7860.

---

Endpoints

Method	Path	Description
GET	/	Landing page
GET	/checker	DDI Checker UI
GET	/chat	Chat interface
GET	/results	Model performance page
GET	/responsible	Responsible ML page (RM1–RM4)
GET	/dashboard	Live dashboard
GET	/about	About page
GET	/health	Liveness / readiness check
GET	/api/stats	Live stats (queries, hit rate, top pairs)
POST	/api/check	Check a single drug pair
POST	/api/check/batch	Check up to 50 pairs
POST	/api/check/compare	Side-by-side dict vs GNN comparison
POST	/api/chat	Chat endpoint (NER → lookup → explanation)
GET	/api/drug/search?q=<query>&limit=<n>	Drug name autocomplete

---

POST /api/check

Request:

{ "drug_a": "Warfarin", "drug_b": "Aspirin" }

Accepts drug names or DrugBank IDs (DB00682). Case-insensitive.

Response:

{
  "drug_a": { "query": "Warfarin", "resolved": "Warfarin", "id": "DB00682" },
  "drug_b": { "query": "Aspirin",  "resolved": "Acetylsalicylic acid", "id": "DB00945" },
  "source":  "documented",
  "found":   true,
  "interaction_description": "Acetylsalicylic acid may increase the anticoagulant activities...",
  "gnn":     null,
  "error":   null
}

source values:

Value	Meaning
"documented"	Pair found in DrugBank (O(1) dict lookup)
"gnn_predicted"	Novel pair — GNN link prediction above threshold
"not_found"	Not in DrugBank; GNN score below threshold
"drug_not_found"	Drug name could not be resolved

---

POST /api/check/batch

Request:

{
  "pairs": [
    { "drug_a": "Warfarin", "drug_b": "Aspirin" },
    { "drug_a": "Metformin", "drug_b": "Lisinopril" }
  ]
}

Max 50 pairs per request.

Response:

{ "results": [ { /* same structure as /api/check */ }, ... ] }

---

GET /api/drug/search

GET /api/drug/search?q=war&limit=5

Returns a list of drug name suggestions for autocomplete:

[
  { "name": "Warfarin", "id": "DB00682" },
  ...
]

---

GET /health

{ "status": "ok", "model_loaded": true, "drugs_loaded": 4795 }

---

GET /api/stats

Live dashboard metrics:

{
  "total_queries": 142,
  "documented_hits": 89,
  "gnn_predictions": 31,
  "not_found": 22,
  "avg_latency_ms": 14.2,
  "top_pairs": [ ... ]
}

---

Authentication

No authentication required. The API is public and read-only. GROQ_API_KEY is required server-side for /api/chat (NER + explanation); all other endpoints work without it.

---

For pipeline details see pipeline.md. For model details see model_architecture.md.