REST Endpoints
All endpoints are under the base path /api/v1 and require authentication. Every list endpoint supports limit / offset pagination.
The interactive OpenAPI spec (/openapi.json) is the always-current source of truth for request parameters and response schemas; the catalog below is the map.
Service
| Method |
Path |
Description |
GET |
/health |
Liveness check (no auth). |
GET |
/api/v1/stats |
Graph-wide summary statistics. |
Taxa
| Method |
Path |
GET |
/taxa |
GET |
/taxa/{taxon_id} |
GET |
/taxa/{taxon_id}/children |
GET |
/taxa/{taxon_id}/lineage |
GET |
/taxa/{taxon_id}/diseases |
GET |
/taxa/{taxon_id}/metabolites |
GET |
/taxa/search/{query} |
GET |
/taxa/compare |
Diseases
| Method |
Path |
GET |
/diseases |
GET |
/diseases/{disease_id} |
GET |
/diseases/{disease_id}/taxa |
GET |
/diseases/{disease_id}/related |
GET |
/diseases/{disease_id}/metabolites |
GET |
/diseases/compare |
| Method |
Path |
GET |
/metabolites |
GET |
/metabolites/{metabolite_id} |
GET |
/metabolites/{metabolite_id}/producers |
GET |
/metabolites/{metabolite_id}/diseases |
GET |
/metabolites/{metabolite_id}/pathways |
GET |
/metabolites/categories/list |
Drugs
| Method |
Path |
GET |
/drugs |
GET |
/drugs/search/{query} |
GET |
/drugs/{drug_id} |
GET |
/drugs/{drug_id}/taxa |
GET |
/drugs/{drug_id}/diseases |
Genes
| Method |
Path |
GET |
/genes |
GET |
/genes/search/{query} |
GET |
/genes/{gene_id} |
GET |
/genes/{gene_id}/taxa |
GET |
/genes/{gene_id}/pathways |
Proteins
| Method |
Path |
GET |
/proteins |
GET |
/proteins/{protein_id} |
GET |
/proteins/{protein_id}/drugs |
Pathways
| Method |
Path |
GET |
/pathways |
GET |
/pathways/search/{query} |
GET |
/pathways/{pathway_id} |
GET |
/pathways/{pathway_id}/metabolites |
GET |
/pathways/{pathway_id}/genes |
GET |
/pathways/{pathway_id}/taxa |
Papers
| Method |
Path |
GET |
/papers |
GET |
/papers/search/{query} |
GET |
/papers/{pmid} |
GET |
/papers/taxon/{taxon_id} |
GET |
/papers/disease/{disease_id} |
Biomarkers
| Method |
Path |
GET |
/biomarkers |
GET |
/biomarkers/disease/{disease_id} |
GET |
/biomarkers/{signature_id} |
Networks & discovery
| Method |
Path |
Description |
GET |
/networks/cross-feeding |
Cross-feeding network. |
GET |
/networks/cross-feeding/{taxon_id} |
Cross-feeding for one taxon. |
GET |
/discovery/probiotics/{disease_id} |
Candidate probiotics for a disease. |
GET |
/discovery/scfa-producers |
SCFA-producing taxa. |
Search
| Method |
Path |
Description |
GET |
/search |
Cross-entity search. |
GET |
/search/suggest |
Autocomplete suggestions. |
GET |
/search/counts |
Result counts by entity type. |
Graph traversal
| Method |
Path |
Description |
GET |
/graph/path |
Shortest path between two entities. |
GET |
/graph/connections |
Direct connections of an entity. |
GET |
/graph/neighborhood |
Neighborhood subgraph around an entity. |
Provenance
| Method |
Path |
Description |
GET |
/provenance/sources |
Data sources behind the graph. |
GET |
/provenance/entity/{entity_id} |
Provenance for one entity. |
GET |
/provenance/stats |
Provenance summary statistics. |
POST |
/provenance/lineage |
Trace experiment → analysis → assertion lineage. |
POST |
/provenance/decisions |
Ingest a DecisionEvent. |
POST |
/provenance/query |
Query decision provenance. |
POST |
/provenance/current |
Current assertions for an entity. |
POST |
/provenance/as-of |
Point-in-time assertions. |
POST |
/provenance/ledger |
Decision ledger. |
POST |
/provenance/search |
Search provenance. |
See Provenance & write-back for the workflow and Schemas for the contracts.
