OmevraOmevra · Variant Evidence Agent — API
Variant Evidence Agent — API
The public API: endpoints, enforced bounds, and copyable examples with real responses.
Base URL and framing
Base URL: https://evidra-variant-evidence-agent.hf.space. Responses are JSON. This is a research-use API over a frozen scored universe: the 27,748 variants of the temporal test set (train frozen Jan 2024), of which 10,357 are summarised with cited evidence and 17,391 are declined. The served model is GBM+R (gradient boosting + REVEL + isotonic), adopted 2026-10-26 — /api/meta reports it as model version “v3 gradient boosting (GBM+R)”. A variant outside the universe returns “not found” rather than an invented answer — the API never fabricates a score or a summary. Live-evidence lookups (ClinVar / gnomAD / PubMed, retrieved at request time) are labelled as live context and carry no model score.
Not for clinical use.
Endpoints
| Method and path | Parameters | Returns |
|---|---|---|
GET /api/meta | — | Universe size, gene count, summarised and declined counts, synthesis flag |
GET /api/variant | allele_id, or gene + variant | One variant's stored record and its evidence report |
GET /api/search | q — gene, variant text, or allele id fragment | Matching variants with allele_id, gene, name and will_summarise |
GET /api/gene | gene | The gene's counts (total / summarised / declined) and its variants with status and calibrated probability |
POST /api/report | JSON body: allele_id, or gene + variant | The variant's evidence report — verdict, calibrated probability, citations, evidence lines, rendered text |
POST /api/batch | JSON body: input — variants one per line (or comma-separated), or a single gene name to expand it | A summary (total / summarised / declined / live-evidence), a verdict table, per-variant results and the pack markdown |
POST /api/batch-file | Multipart file upload, field file (.txt, .csv or .tsv) | The same batch result as POST /api/batch, for an uploaded variant list |
GET /api/docs | — | This documentation, served by the API as JSON |
Live-status note (recaptured 2026-10-26). Every endpoint in the table was exercised against the live service during this page's build and returned the responses excerpted below — including GET /api/variant and GET /api/docs, which returned 404 when this page was first built and are live now. The /api/meta body below is the real current body, captured verbatim.
Enforced bounds
- Batch: at most 500 variants per batch.
- Inline batch (in the page): at most 25 variants.
- At most 4 concurrent batch jobs — beyond that, the API returns 429.
- File upload: at most 2 MB (.txt, .csv or .tsv).
- At most 50 out-of-universe live lookups per batch — beyond that, remaining out-of-universe variants are reported as live-evidence not run, never guessed.
Examples — real calls, real responses
1 · Single-variant GET — search for one variant
curl "https://evidra-variant-evidence-agent.hf.space/api/search?q=c.154C"
Response excerpt (live, 2026-10-26):
{"results": [{"allele_id": 45977, "gene": "BRCA1", "name": "NM_007294.4(BRCA1):c.154C>T (p.Leu52Phe)", "will_summarise": true}, {"allele_id": 1030394, "gene": "MEN1", "name": "NM_001370259.2(MEN1):c.154C>G (p.Arg52Gly)", "will_summarise": true}]}
The full current body of GET /api/meta, captured live on 2026-10-26: {"universe_size": 27748, "gene_count": 3084, "summarised_count": 10357, "declined_count": 17391, "synthesis_enabled": false, "data": {"data_version": "evaluation universe v1", "model_version": "v3 gradient boosting (GBM+R)", "data_version_line": "Data version: evaluation universe v1 · Model: v3 gradient boosting (GBM+R) · ClinVar monthly release, January 2024 freeze — evaluation universe v1, 27,748 variants", "scored_universe": "ClinVar monthly release, January 2024 freeze — evaluation universe v1, 27,748 variants", "clinvar": "ClinVar monthly release, January 2024 freeze — evaluation universe v1, 27,748 variants", "alphamissense": "precomputed scores, CC BY-NC-SA 4.0, linked not redistributed", "revel": "v1.3, public Zenodo record 7072866", "gnomad": "allele frequencies via Ensembl VEP REST; Ensembl-served gnomAD freeze (Ensembl serves its own gnomAD freeze)", "scope": "Not for clinical use."}} — and the same variant's full report, from POST /api/report with body {"gene": "BRCA1", "variant": "c.154C>T"}: verdict “evidence summary (not a clinical classification)”, calibrated_prob_pathogenic: 0.464, citations ["AM:17:43106514:G>A", "CLINVAR:allele45977", "GENEPRIOR:BRCA1:frozen2024"].
2 · Small batch POST — one summarised, one declined
curl -X POST "https://evidra-variant-evidence-agent.hf.space/api/batch" -H "Content-Type: application/json" -d '{"input": "BRCA1 c.154C>T\nBRCA1 c.5406+5G>T"}'
Response excerpt (live, 2026-10-26):
{"summary": {"total": 2, "summarised": 1, "declined": 1, "live_evidence": 0, "live_not_run": 0, "not_found": 0}, "table": [{"variant": "NM_007294.4(BRCA1):c.154C>T (p.Leu52Phe)", "gene": "BRCA1", "variant_text": "c.154C>T", "status": "summarised", "verdict": "evidence summary (not a clinical classification)", "calibrated_prob_pathogenic": 0.464}, {"variant": "NM_007294.4(BRCA1):c.5406+5G>T", "gene": "BRCA1", "variant_text": "c.5406+5G>T", "status": "declined", "verdict": "insufficient evidence — remains VUS", "calibrated_prob_pathogenic": null}]}
The declined variant carries no probability and no summary — that is the cite-or-decline contract working as designed, over the API exactly as in the application.
Product: Variant Evidence Agent · Proof: Evaluations · Tools: Tools directory.