docs/API.md

# BioNexus API (automatically generated)

> Generated by `scripts/generate_docs.py` — do not edit by hand.

- `POST` `/api/admet/descriptors` — Compute molecular descriptors from SMILES / chemical name / PubChem CID.
- `POST` `/api/admet/protox` — ProTox 3.0 ML-based toxicity prediction (Charité).
- `GET` `/api/admet/search` — PubChem autocomplete for chemical name search.
- `GET` `/api/admin/cache-stats` — 
- `POST` `/api/admin/cache-stats/reset` — 
- `POST` `/api/ai/interpret` — 
- `POST` `/api/ai/interpret/stream` — 
- `POST` `/api/ai/tool-interpret` — Generate a plain-language AI interpretation of a single tool result on demand.
- `POST` `/api/alignment/pairwise` — 
- `POST` `/api/alignment/run` — 
- `POST` `/api/audit/event` — 
- `GET` `/api/audit/insights` — 
- `GET` `/api/benchmarks` — Benchmark catalog (BBS-1 expansion), optionally filtered by category.
- `POST` `/api/benchmarks/seed` — Upsert the JSON benchmark catalog (app/data/benchmarks) into the DB.
- `GET` `/api/benchmarks/summary` — Per-category pass/fail statistics across recorded benchmark runs.
- `GET` `/api/benchmarks/{benchmark_id}` — 
- `POST` `/api/benchmarks/{benchmark_id}/run` — Execute a benchmark against the stored context of an existing job.
- `POST` `/api/castp/analyze` — 
- `GET` `/api/dashboard/datasets` — 
- `GET` `/api/dashboard/engines` — 
- `GET` `/api/dashboard/runs` — 
- `GET` `/api/dashboard/summary` — 
- `POST` `/api/dashboard/upload_data` — Ingest a scientist's own dataset file into the dashboard library.
- `GET` `/api/datasets` — Summaries of every dataset in the library.
- `GET` `/api/datasets/{name}` — One full dataset (records included).
- `POST` `/api/datasets/{name}/snapshot` — Copy a dataset (records + manifest) into an engine workspace folder.
- `GET` `/api/docking` — 
- `GET` `/api/docking/result/{job_id}/complex.pdb` — Receptor + docked ligand merged into a single PDB (techspec §2).
- `GET` `/api/docking/result/{job_id}/ligand.sdf` — Ligand-only SDF of the docked poses (techspec §2).
- `GET` `/api/docking/result/{job_id}/pdb` — 
- `POST` `/api/docking/run` — 
- `GET` `/api/docking/status/{job_id}` — 
- `POST` `/api/domains/scan` — Scan a raw protein sequence against PROSITE signatures (best-effort).
- `GET` `/api/domains/{accession}` — Fetch InterPro domain architecture (Pfam, SMART, PROSITE, CDD, PANTHER, PRINTS).
- `GET` `/api/domains/{accession}/all` — Combined analysis: domains, sites, PTMs, topology, motifs, variants, GO, pathways.
- `GET` `/api/domains/{accession}/composition` — Compositionally biased regions and low-complexity sequences.
- `GET` `/api/domains/{accession}/disulfide` — Disulfide bond connectivity.
- `GET` `/api/domains/{accession}/features` — Full UniProt feature table categorized by type.
- `GET` `/api/domains/{accession}/go` — Gene Ontology annotations (molecular function, biological process, cellular component).
- `GET` `/api/domains/{accession}/motifs` — Structural motifs: zinc fingers, coiled coils, repeats, domain families.
- `GET` `/api/domains/{accession}/pathways` — Pathway annotations from KEGG, Reactome, and WikiPathways.
- `GET` `/api/domains/{accession}/ptm` — Post-translational modifications (phosphorylation, glycosylation, etc.).
- `GET` `/api/domains/{accession}/sites` — Active sites, binding sites, and catalytic residues.
- `GET` `/api/domains/{accession}/topology` — Signal peptides, transmembrane regions, chains, and propeptides.
- `GET` `/api/domains/{accession}/variants` — Mutagenesis sites and natural variants.
- `GET` `/api/engines` — Every registered engine: name, tool, databases, benchmark coverage.
- `GET` `/api/engines/{name}` — 
- `POST` `/api/engines/{name}/export` — Export an engine result to JSON or CSV.
- `POST` `/api/engines/{name}/figure` — Render a publication-style SVG figure for the result.
- `POST` `/api/engines/{name}/validate` — Validate a canonical engine output; returns PASS/FAIL checks,
- `GET` `/api/experiments` — Recent experiments (provenance metadata for reproducibility).
- `GET` `/api/experiments/debug/fingerprint` — Return the reproducibility fingerprint for an input (used by tests).
- `POST` `/api/experiments/debug/new` — Create an experiment record on demand (used by tests).
- `POST` `/api/experiments/debug/trace` — Record a provenance node on demand (used by tests).
- `GET` `/api/experiments/{job_id}` — The immutable experiment record for a job, including its provenance DAG.
- `GET` `/api/experiments/{job_id}/evidence` — Evidence graph linking every AI claim to its supporting computation.
- `GET` `/api/experiments/{job_id}/evidence/validate` — Validation report over the evidence graph (honesty invariant).
- `POST` `/api/experiments/{job_id}/finalize` — Manually finalize an experiment (used by tests / admin).
- `GET` `/api/experiments/{job_id}/ledger` — 
- `POST` `/api/experiments/{job_id}/ledger` — 
- `GET` `/api/experiments/{job_id}/ledger/validate` — 
- `GET` `/api/experiments/{job_id}/paper` — Manuscript draft generated from the recorded experiment. Zero external calls.
- `GET` `/api/experiments/{job_id}/paper/latest` — 
- `POST` `/api/experiments/{job_id}/paper/regenerate` — 
- `GET` `/api/experiments/{job_id}/paper/versions` — 
- `GET` `/api/experiments/{job_id}/provenance` — Clickable provenance trace: nodes + edges for a job's experiment.
- `GET` `/api/figure/formats` — Publication formats the Figure Engine can emit (SVG only by design:
- `GET` `/api/figures/{job_id}` — One publication figure for a recorded experiment (paneled, captioned).
- `POST` `/api/function/predict` — Submit a function prediction job (queued through the durable worker).
- `GET` `/api/function/status/{job_id}` — 
- `POST` `/api/history/branch` — Create a new pipeline job branched from an existing job's results.
- `GET` `/api/history/children/{job_id}` — Return direct children of a job (for the 'branch from here' list).
- `GET` `/api/history/graph/{job_id}` — Return the full ancestry + descendants of a job as a DAG.
- `GET` `/api/interactions/{gene_name}` — 
- `GET` `/api/jobs` — 
- `GET` `/api/jobs/count` — 
- `DELETE` `/api/jobs/{job_id}` — 
- `GET` `/api/jobs/{job_id}` — 
- `GET` `/api/keys` — 
- `POST` `/api/keys` — 
- `DELETE` `/api/keys/{key_id}` — 
- `GET` `/api/md/forcefields` — Return the force field / solvent menu (verified combos only).
- `POST` `/api/md/run` — Submit an MD simulation job (queued through the durable worker).
- `GET` `/api/md/status/{job_id}` — 
- `POST` `/api/md/v2/analyze` — Run the full in-process staged MD DAG over a structure and return the audit report.
- `GET` `/api/md/v2/engine` — Report MD engine availability + versions (OpenMM primary, GROMACS gated).
- `GET` `/api/md/v2/stages` — Return the ordered stage contracts (names + human explanations) for the MD v2 DAG.
- `GET` `/api/ngs/references` — 
- `POST` `/api/ngs/run` — 
- `GET` `/api/ngs/status/{job_id}` — 
- `POST` `/api/ngs/v2/analyze` — 
- `GET` `/api/ngs/v2/benchmarks/portable` — 
- `POST` `/api/ngs/v2/clinical/evaluate` — 
- `GET` `/api/ngs/v2/demos` — 
- `POST` `/api/ngs/v2/detect` — 
- `GET` `/api/ngs/v2/production/capabilities` — 
- `POST` `/api/ngs/v2/production/plan` — 
- `GET` `/api/ngs/v2/production/runs/{run_id}` — 
- `GET` `/api/ngs/v2/production/runs/{run_id}/artifacts` — 
- `POST` `/api/ngs/v2/production/submit` — 
- `GET` `/api/ngs/v2/stages` — 
- `POST` `/api/paper/continuous` — 
- `GET` `/api/paper/continuous/subscriptions` — 
- `POST` `/api/paper/continuous/tick` — 
- `GET` `/api/paper/journal-formats` — Journal templates the Publication Engine can emit.
- `POST` `/api/pathways/detail` — 
- `POST` `/api/pathways/enrichment` — 
- `POST` `/api/pathways/enrichment/cross-validate` — Run both Reactome and g:Profiler enrichment, returning concordant pathways.
- `POST` `/api/pathways/kegg/search` — 
- `POST` `/api/pathways/search` — 
- `POST` `/api/pipeline/v2/run` — 
- `GET` `/api/pipeline/v2/status/{job_id}` — 
- `GET` `/api/pipelines/definitions` — 
- `POST` `/api/pipelines/run` — 
- `GET` `/api/pipelines/{pipeline_type}/definition` — 
- `GET` `/api/plugins` — 
- `POST` `/api/plugins/event` — 
- `POST` `/api/plugins/reload` — 
- `POST` `/api/plugins/{name}/disable` — 
- `POST` `/api/plugins/{name}/enable` — 
- `POST` `/api/primers/analyze` — Run oligo QC (hairpin, self-/hetero-dimer, Tm, GC) and in-silico PCR.
- `POST` `/api/primers/design` — 
- `POST` `/api/primers/search` — Search NCBI Nucleotide for a gene/sequence to design primers against.
- `GET` `/api/profile` — 
- `PUT` `/api/profile` — 
- `POST` `/api/seq-tools/analyze` — 
- `POST` `/api/seq-tools/dotplot` — 
- `POST` `/api/seq-tools/motif-library` — 
- `GET` `/api/seq-tools/motif-library/categories` — Return the ordered list of motif categories for UI filters.
- `GET` `/api/seq-tools/motif-library/patterns` — Return the curated motif library so the UI can offer presets.
- `POST` `/api/seq-tools/motif-scan` — 
- `POST` `/api/sequences/fetch` — 
- `POST` `/api/sequences/search` — 
- `POST` `/api/sequences/validate` — 
- `GET` `/api/sequencing/references` — 
- `POST` `/api/sequencing/run` — 
- `GET` `/api/sequencing/status/{job_id}` — 
- `POST` `/api/share` — 
- `GET` `/api/share/{token}` — 
- `GET` `/api/structure-export/structure/{identifier}` — Download a structure as PDB, mmCIF, or a styled PyMOL session (.pse).
- `POST` `/api/structure-predict/predict` — 
- `GET` `/api/structure-predict/status/{job_id}` — 
- `POST` `/api/structure-prep/run` — 
- `GET` `/api/structure-prep/status/{job_id}` — 
- `GET` `/api/structure_analysis/compare/{pdb_id}` — 
- `GET` `/api/structure_analysis/ramachandran/{pdb_id}` — 
- `GET` `/api/structure_analysis/secondary_structure/{identifier}` — 
- `POST` `/api/structures/fetch` — 
- `POST` `/api/structures/inventory` — Return lightweight chain and non-polymer inventory for workbench controls.
- `POST` `/api/structures/search` — 
- `GET` `/api/swissmodel/coordinates/{accession}` — 
- `POST` `/api/swissmodel/repository` — 
- `GET` `/api/templates` — 
- `POST` `/api/templates` — 
- `GET` `/api/templates/shared/{token}` — 
- `DELETE` `/api/templates/{template_id}` — 
- `GET` `/api/templates/{template_id}` — 
- `PUT` `/api/templates/{template_id}` — 
- `POST` `/api/templates/{template_id}/share` — 
- `GET` `/api/tools` — 
- `GET` `/api/tools/{tool_id}` — 
- `POST` `/api/uniprot/cds` — Fetch the CDS nucleotide sequence for a UniProt entry given an EMBL/GenBank accession.
- `POST` `/api/uniprot/detail` — 
- `POST` `/api/uniprot/search` — 
- `GET` `/docs` — 
- `GET` `/docs/oauth2-redirect` — 
- `GET` `/openapi.json` — 
- `GET` `/phylo/models` — 
- `POST` `/phylo/run` — 
- `GET` `/phylo/status/{job_id}` — 
- `GET` `/redoc` —