Developer Portal
Build with the MultiEndpointTox API
A plain REST/JSON API — no SDK required, callable from any language. Everything on this page is verified against the live, deployed contract.
Overview
Base URL: https://api.bionexusdiscovery.com. Interactive OpenAPI docs (FastAPI's built-in Swagger UI) are live at /docs , with the raw OpenAPI schema at /openapi.json. That live Swagger UI is the API Explorer — a first-party interactive playground is not separately built on this site (see the roadmap).
Note: the backend repo's own docs/API.md describes an older contract (v0.3.0, 6 endpoints, no auth or rate limiting). Everything below reflects the current deployed v1.2 contract, verified against the live API and the backend source — not that stale doc.
Authentication
Authentication is optional by default (REQUIRE_AUTH is unset/false in the deployed environment as of this writing — every endpoint documented here is publicly callable without a token, exactly like the live demo on this site). The backend does implement full authentication for deployments that enable it: JWT access tokens (30 min) with rotating, reuse-detected refresh tokens (30 day TTL), role-based access control (admin/researcher/reviewer/student), and API keys (POST/GET/DELETE /auth/api-keys, stored as SHA-256 hashes, the raw key shown exactly once at creation). See the backend's own src/api/routes/auth.py for the full contract if you're deploying your own instance with REQUIRE_AUTH=true.
Quick Start
# Health check
curl https://api.bionexusdiscovery.com/health
# Single-endpoint prediction
curl -X POST https://api.bionexusdiscovery.com/predict \
-H "Content-Type: application/json" \
-d '{"smiles": "CC(=O)Nc1ccc(O)cc1", "endpoint": "hepatotox"}'
# Full integrated assessment (all 7 endpoints + SHAP)
curl -X POST https://api.bionexusdiscovery.com/predict/integrated \
-H "Content-Type: application/json" \
-d '{"smiles": "CC(=O)Nc1ccc(O)cc1", "include_interpretation": true, "top_k": 8}'SDKs & Examples
No published Python/JS/R package exists yet (roadmap item) — the API is plain REST/JSON, directly callable from any HTTP client today.
New Capabilities
Not yet on the live API. The three modules below exist on the backend's feature/scientific-platform-expansion branch and are documented here for transparency, but https://api.bionexusdiscovery.com does not serve these routes yet — calling them today will 404. This section will be updated the moment they deploy.
Molecular Docking (AutoDock Vina)
Pending DeployReal physics-based docking against 7 curated protein targets (hERG, CYP3A4, CYP2D6, CYP2C9, PPARγ, androgen receptor, ERα — real RCSB PDB structures). Disabled by default even once deployed (docking.enabled: false) — requires optional vina/meeko dependencies not in the main requirements.txt.
- GET /docking/status
- GET /docking/targets
- POST /dock
- POST /dock/batch
- GET /dock/{target}
- POST /dock/enhanced
- GET /dock/endpoint/{endpoint}/enhanced
- POST /predict/ensemble
- POST /descriptors/3d
- POST /pharmacophore/features
- POST /pharmacophore/compare
Every route returns HTTP 503 with an explanation — never a fabricated affinity or pose — when docking is disabled or Vina isn't installed.
Metabolite Prediction (SyGMa)
Pending DeployReal Phase I/II metabolite prediction via SyGMa (Ridder & Wagener, ChemMedChem 2008, doi:10.1002/cmdc.200700312) — 138 Phase I + 27 Phase II published, literature-derived reaction rules. Returns the full reaction graph, real likelihood scores, 2D structure SVGs, and structural-alert screening of every metabolite.
- GET /metabolism/status
- POST /metabolism/predict
- GET /metabolism/predict/{smiles}
Structural alerts on metabolites are a mechanistic hypothesis, not a validated toxicity prediction — labeled as such in every response.
Scientific Validation Artifacts
Pending DeployReal, on-disk per-endpoint validation data — model version history with SHA256/training timestamp/git commit, real cross-validation fold statistics, and a live applicability-domain (AD) staleness health check. Nothing here is computed or estimated by the API.
- GET /validation
- GET /validation/{endpoint}
- GET /validation/ad-health
The AD health check currently reports 4 of 7 endpoints as STALE (hepatotox, ames, skin_sens, cytotox) — a real, documented, in-progress incident, not hidden. See the Validation page's Applicability Domain Status panel.
Pharmacogenomic Safety Index (PSI)
Pending DeployReal CPIC-sourced gene-drug evidence — 57 level A/A-B pairs across 16 genes, live-fetched from api.cpicpgx.org with real guideline URLs and PMIDs. No patient genotype input exists in this API; every phenotype is an explicit scenario. Anything outside the curated evidence set is reported 'Not currently supported', never guessed.
- POST /pharmacogenomics/predict
- POST /pharmacogenomics/score
- POST /pharmacogenomics/report
- POST /pharmacogenomics/adjust-toxicity
- GET /pharmacogenomics/genes
- GET /pharmacogenomics/version
/adjust-toxicity calls the real, unmodified toxicity model and applies an illustrative PSI adjustment on top — the model itself is never touched.
curl -X POST https://api.bionexusdiscovery.com/pharmacogenomics/predict \
-H "Content-Type: application/json" \
-d '{"smiles": "CN1CCC23C=CC(O)C4Oc5c(O)ccc(c25)C1C34", "genes": ["CYP2D6"]}'
# codeine — real CYP2D6 prodrug-activation evidence (CPIC level A, PMID 22205192):
# Poor Metabolizer -> decreased toxicity risk (less morphine formed)
# Ultrarapid Metabolizer -> increased toxicity risk (excess morphine —
# the real mechanistic basis for the FDA's black-box warning)Batch Screening
Pending DeployPublication-scale batch screening — SMILES paste, CSV, TSV, SDF, or ZIP of SDF files. Chunked, resumable, cancellable async jobs (up to 10,000 compounds/job) with real per-compound provenance and CSV/Excel/JSON/PDF export. No model outputs changed — every compound scored via the same pipeline as POST /predict/multi.
- POST /batch/jobs
- GET /batch/jobs/{id}
- GET /batch/jobs/{id}/items
- GET /batch/jobs/{id}/summary
- POST /batch/jobs/{id}/resume
- POST /batch/jobs/{id}/retry-failed
- POST /batch/jobs/{id}/cancel
- GET /batch/jobs/{id}/export?format=csv|xlsx|json|pdf
Rate-limited to 10 job submissions/minute — physics-real compute triggers, not a cached lookup.
curl -X POST https://api.bionexusdiscovery.com/batch/jobs \
-F "smiles_text=CCO
CC(=O)Nc1ccc(O)cc1,paracetamol" \
-F "endpoints=hepatotox,herg" \
-F "chunk_size=50"
# -> {"id": "...", "status": "pending", "total": 2, ...}
# then poll: curl https://api.bionexusdiscovery.com/batch/jobs/{id}Rate Limits
| POST /predict | 60 / minute |
| POST /predict/multi | 30 / minute |
| POST /predict/batch | 10 / minute (max 1000 SMILES per request) |
| POST /predict/integrated | Not rate-limited (as of the code reviewed) |
| POST /predict/interpret | Not rate-limited (as of the code reviewed) |
| POST /validate, GET /health, /version, /status | Not rate-limited |
| POST /dock, POST /dock/enhanced, POST /predict/ensemble | 10 / minute (real Vina docking is compute-heavy) |
| POST /dock/batch | 2 / minute (max 200 SMILES per request) |
| POST /metabolism/predict | 20 / minute |
| GET /docking/status, /docking/targets, /metabolism/status, /validation* | Not rate-limited |
Error Handling
{
"error": {
"code": "string",
"message": "human-readable description",
"request_id": "uuid, echoes X-Request-ID if you sent one",
"details": { "...": "validation-error-specific, when applicable" }
}
}| 200 | Success |
| 400 | Bad request — invalid SMILES or invalid endpoint name |
| 422 | Validation error — missing/malformed request fields |
| 429 | Rate limit exceeded (see Rate Limits above) |
| 503 | Service unavailable — predictor not yet initialized (cold start) |
Changelog
The full, real changelog lives in the backend repository — rendering it here would risk drifting out of sync with each release. View CHANGELOG.md on GitLab
Status
Live health, version, and response latency, fetched directly from the deployed API.
View live status