API referenceIndoPGx v1.1

IndoPGx API

Two endpoints, one envelope. /pgx/check for single-prescription safety (sub-200ms target)./pgx/batch_csv for diagnostic-lab batch interpretation. Every response carries the hardened envelope: api_version, request_id, audit_log_id,confidence, data_completeness, source_citations.

Versioning & base URL

BASE URL

bioreason-india.vercel.app/api

API VERSION

1.1.0

AUTH

Bearer <id_token>

P95 LATENCY TARGET

200 ms

POST/pgx/check

Single prescription-time pharmacogenomic safety check. Returns the hardened envelope plus CPIC-graded alerts, safer alternatives, and Indian context. Designed for EHR order-entry embedding.

Request

curl -X POST https://bioreason-india.vercel.app/api/pgx/check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <id_token>" \
  -d '{ "drug": "Clopidogrel", "variants": ["rs4244285"], "state": "Bihar", "ethnicity": "Indo-Aryan", "indication": "ACS" }'

Response (200 OK)

{
  "api_version": "1.1.0",
  "request_id": "pgx-a3f1e9c8b7d24e2f",
  "audit_log_id": "audit-7d2c1b9e3f4a8c1d5b2e",
  "timestamp": "2026-06-16T09:14:22.481Z",
  "latency_ms": 187,
  "confidence": "high",
  "data_completeness": {
    "genotype_provided": true,
    "state_provided": true,
    "ethnicity_provided": true,
    "indication_provided": true,
    "fields_populated": 4,
    "fields_total": 4
  },
  "source_citations": [
    {
      "field": "alerts[CYP2C19]",
      "source": "CPIC guideline · CYP2C19*2",
      "evidence_level": "1A",
      "url": "https://cpicpgx.org/guidelines/"
    },
    {
      "field": "alerts[CYP2C19].af_india",
      "source": "IndiGen 1029-genome (CSIR-IGIB) + published Indian cohort PMIDs",
      "url": "https://clingen.igib.res.in/indigen/"
    }
  ],
  "drug": "Clopidogrel",
  "drug_normalised": "clopidogrel",
  "sensitivity": "high",
  "overall_severity": "HIGH",
  "alerts": [
    {
      "severity": "HIGH",
      "severity_score": 3,
      "variant": "rs4244285",
      "gene": "CYP2C19",
      "star_allele": "*2",
      "af_india": 0.23,
      "af_global": 0.15,
      "category": "genotype-confirmed",
      "message": "CYP2C19*2 (rs4244285) carrier on clopidogrel: HIGH risk — Reduced metabolism",
      "action": "Reduced metabolism — consider Prasugrel/Ticagrelor; dose-adjust SSRIs and PPIs.",
      "alternatives": ["Ticagrelor", "Prasugrel"],
      "test_recommended": false
    }
  ],
  "safer_alternatives": [
    { "name": "Ticagrelor", "rationale": "CYP2C19-independent, direct P2Y12 inhibitor. CPIC Level A." },
    { "name": "Prasugrel",  "rationale": "CYP2C19-independent activation. Standard alternative for *2 carriers." }
  ],
  "indian_context": { "state": "Bihar" },
  "grounding_contract": "no entity outside graph result rows"
}

Response envelope fields

api_version	string	Semver of the response schema.
request_id	string	Unique ID for this call. Include in support tickets.
audit_log_id	string	Immutable audit-log entry ID. Persisted server-side (365-day retention).
timestamp	string	ISO-8601 UTC.
latency_ms	int	Server-side processing latency.
confidence	enum	high \| medium \| low. Derived from completeness + alert category.
data_completeness	object	fields_populated / fields_total. genotype/state/ethnicity/indication flags.
source_citations	array	Per-field provenance with evidence_level (CPIC 1A/1B/2A/2B) and URL/PMID.
sensitivity	enum	high \| moderate \| none. Clinical sensitivity tier.
overall_severity	enum	HIGH \| MODERATE \| INFO \| NONE.
alerts	array	PgxAlert objects with variant, gene, star_allele, af_india, af_global, action.
safer_alternatives	array	Drug name + rationale.
indian_context	object	State-specific endemic risks when state provided.
grounding_contract	string	Always returns 'no entity outside graph result rows'.

POST/pgx/batch_csv

CSV-in, JSON-out batch interpretation for diagnostic labs. Per-row failures do not abort the batch — the response includes successful + failed counts, every row carries an ok flag.

CSV template

drug,variants,state,ethnicity,indication,patient_ref
Clopidogrel,rs4244285,Bihar,Indo-Aryan,ACS,patient-0001
Azathioprine,rs116855232;rs1142345,Maharashtra,,IBD maintenance,patient-0002
Warfarin,,Tamil Nadu,Dravidian,AFib,patient-0003

Required: drug. Optional: variants (semicolon-separated rsIDs), state, ethnicity, indication, patient_ref.

Request

curl -X POST https://bioreason-india.vercel.app/api/pgx/batch_csv \
  -H "Authorization: Bearer <id_token>" \
  -F "file=@panel_2026_06.csv"

Engine metadata endpoints

GET /pgx/version

API version, engine version, CPIC guideline version, SLA targets.

GET /pgx/status

Engine health, audit-log policy, grounding-contract enforcement.

GET /pgx/drugs

All drugs covered by the safety layer.

GET /pgx/variants

All 61 tracked variants with Indian allele frequencies.

POST /pgx/batch

Bulk drug list per single genotype (medication reconciliation).

GET /pgx/india_panel

Full IndoPGx flagship panel — pathway + wedges + Ayurvedic overlay.

Rate limits

Open beta: 60 requests / minute / user. Lab API pilot: negotiated per-sample volume. Hospital embed: SLA-bound throughput in contract. Pilot intake at /pilot.