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 Deploy

Real 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 Deploy

Real 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 Deploy

Real, 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 Deploy

Real 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 Deploy

Publication-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 /predict60 / minute
POST /predict/multi30 / minute
POST /predict/batch10 / minute (max 1000 SMILES per request)
POST /predict/integratedNot rate-limited (as of the code reviewed)
POST /predict/interpretNot rate-limited (as of the code reviewed)
POST /validate, GET /health, /version, /statusNot rate-limited
POST /dock, POST /dock/enhanced, POST /predict/ensemble10 / minute (real Vina docking is compute-heavy)
POST /dock/batch2 / minute (max 200 SMILES per request)
POST /metabolism/predict20 / 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" }
  }
}
200Success
400Bad request — invalid SMILES or invalid endpoint name
422Validation error — missing/malformed request fields
429Rate limit exceeded (see Rate Limits above)
503Service 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