{"name": "Variant Evidence Agent \u2014 public API", "base_url": "https://evidra-variant-evidence-agent.hf.space", "scope": "Not for clinical use.", "synthesis": "The API serves the deterministic evidence path only; no probability is ever invented. Variants outside the frozen scored universe return found=false.", "bounds": {"batch_max_variants": 500, "batch_inline_max": 25, "batch_max_concurrent_jobs": 4, "batch_max_concurrent_jobs_exceeded": "HTTP 429", "upload_max_bytes": 2097152, "upload_extensions": [".txt", ".csv", ".tsv"], "live_lookups_per_batch_max": 50, "single_and_gene_lookups": "served from the frozen scored universe only", "out_of_universe": "found=false (GET /api/variant: HTTP 404)", "queue_max_variants": 25000, "queue_upload_max_bytes": 10485760, "queue_max_concurrent_jobs": 4, "queue_max_waiting_jobs": 8, "queue_full": "HTTP 429 \u2014 submissions beyond 4 processing + 8 waiting are refused with a clear message, never silently dropped", "queue_live_lookups": "none \u2014 queued jobs do not run live lookups; out-of-universe variants are reported 'not found in the scored universe'. The \u226450 live-lookup allowance is a per-batch rail of the standard path only.", "stored_batches_retention": "the last 20 completed batches are retained for the export endpoints; older batch ids return HTTP 404"}, "endpoints": [{"method": "GET", "path": "/api/meta", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/meta", "response": {"universe_size": "int", "gene_count": "int", "summarised_count": "int", "declined_count": "int", "synthesis_enabled": "bool", "data": "data-version block: {data_version, model_version, data_version_line, scored_universe, clinvar, alphamissense, revel, gnomad, scope} \u2014 the frozen universe, its sources and the model version this instance serves"}}, {"method": "GET", "path": "/api/variant", "params": {"allele_id": "int (alternative to gene+variant)", "gene": "gene symbol, e.g. CFTR", "variant": "variant text, e.g. c.1373G>T"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/variant?gene=CFTR&variant=c.1373G%3ET", "response": "Same JSON payload as POST /api/report: {found, allele_id, gene, name, coordinates{chrom,pos,ref,alt}, report{variant,gene,verdict,calibrated_prob_pathogenic,citations,evidence}, rendered}. Not found: HTTP 404 {found: false, error, message} \u2014 never an invented probability."}, {"method": "POST", "path": "/api/report", "params": {"allele_id": "int (optional)", "gene": "string (optional)", "variant": "string (optional)"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/report  body: {\"gene\": \"CFTR\", \"variant\": \"c.1373G>T\"}", "response": "Same payload as GET /api/variant; a variant outside the universe returns HTTP 200 {found: false, message}."}, {"method": "GET", "path": "/api/search", "params": {"q": "free text: gene and/or variant text"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/search?q=CFTR%20c.1373G%3ET", "response": {"results": "[{allele_id, gene, name, will_summarise}]"}}, {"method": "GET", "path": "/api/gene", "params": {"gene": "gene symbol"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/gene?gene=CFTR", "response": "{found, gene, counts{total,summarised,declined}, variants[], calibration|null}"}, {"method": "POST", "path": "/api/normalise", "params": {"text": "one variant reference, any accepted spelling"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/normalise  body: {\"text\": \"CFTR:c.1373G>T\"}", "response": "{input, status (summarised|declined|outside|gene-only|empty), gene, variant, allele_id, name, calibrated_prob_pathogenic, verdict}"}, {"method": "POST", "path": "/api/batch", "params": {"input": "variants, one per line or comma-separated (or a single gene name, which expands)", "gene": "string (optional)", "variants": "array (optional)"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch  body: {\"input\": \"CFTR c.1373G>T\\nOAT c.192_193del\"}", "response": "Batches of at most 25 variants return the batch inline (HTTP 200); larger batches return HTTP 202 {job_id, total} \u2014 poll GET /api/batch-job/{job_id}. Batch shape: {batch_id, exports{pdf,csv,xlsx}, summary{total,summarised,declined,live_evidence,live_not_run}, table[], results[], pack_markdown, pack_json}."}, {"method": "POST", "path": "/api/batch-file", "params": {"file": "multipart .txt/.csv/.tsv upload, at most 2 MB"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch-file (multipart form, field name: file)", "response": "Same as POST /api/batch."}, {"method": "GET", "path": "/api/batch-job/{job_id}", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch-job/<job_id>", "response": "{status (running|done|error), done, total, batch (when done), error}"}, {"method": "POST", "path": "/api/batch-queue", "params": {"input": "variants, one per line or comma-separated (or a single gene name, which expands)", "gene": "string (optional)", "variants": "array (optional) \u2014 the same parsed entries as POST /api/batch"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch-queue  body: {\"input\": \"CFTR c.1373G>T\\nOAT c.192_193del\"}", "response": "The queued scale path: at most 25,000 variants per job (more is rejected with HTTP 400). Always HTTP 202 {job_id, status, submitted_count, processed_count, summarised_count, declined_count} \u2014 poll GET /api/batch-queue/{job_id}. Jobs run FIFO: at most 4 processing concurrently and at most 8 more waiting; a submission beyond that gets HTTP 429. Queued jobs run no live lookups: out-of-universe variants are reported 'not found in the scored universe', and declined variants are exported as declined."}, {"method": "POST", "path": "/api/batch-queue-file", "params": {"file": "multipart .txt/.csv/.tsv upload, at most 10 MB (the standard /api/batch-file cap stays 2 MB)"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch-queue-file (multipart form, field name: file)", "response": "Same queued contract as POST /api/batch-queue: HTTP 202 with a job_id to poll; at most 25,000 variants per job."}, {"method": "GET", "path": "/api/batch-queue/{job_id}", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch-queue/<job_id>", "response": "{job_id, status (queued|running|complete|failed), position (1-based among waiting jobs, when queued), submitted_count, processed_count, summarised_count, declined_count, submitted_at, started_at, finished_at, error}. Counts come from the engine as it processes in chunks. On completion the payload also carries batch_id, exports {pdf,csv,xlsx}, summary and the full batch \u2014 the job's batch is registered exactly like a standard batch (last 20 batches retained), so the evidence-pack downloads work via the existing /api/batch/{batch_id}/ endpoints."}, {"method": "GET", "path": "/api/batch/{batch_id}/evidence-pack.pdf", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch/<batch_id>/evidence-pack.pdf", "response": "application/pdf download: one section per variant (variant, gene, coordinates, verdict, calibrated probability, evidence items with citations), a batch header (submitted / summarised / declined), the scope line and the data-version line. Declined variants appear as declined."}, {"method": "GET", "path": "/api/batch/{batch_id}/evidence-pack.csv", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch/<batch_id>/evidence-pack.csv", "response": "text/csv download: one row per variant (input, allele_id, gene, name, chrom, pos, ref, alt, status, verdict, calibrated_prob_pathogenic, evidence_sources, citations, evidence, retrieval_status). The first line is the header and every following line is one variant \u2014 no metadata rows are prepended, so the one-row-per-variant contract holds; the data version is in the PDF header and the XLSX About sheet."}, {"method": "GET", "path": "/api/batch/{batch_id}/evidence-pack.xlsx", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/batch/<batch_id>/evidence-pack.xlsx", "response": "Spreadsheet download whose 'Evidence pack' sheet carries the same content as the CSV, plus a separate 'About' sheet with the scope line, the data-version line and the batch counts (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)."}, {"method": "POST", "path": "/api/live", "params": {"gene": "string (optional)", "variant": "string (optional)", "allele_id": "int (optional)", "coordinates": "object (optional)"}, "example": "https://evidra-variant-evidence-agent.hf.space/api/live  body: {\"gene\": \"TP53\", \"variant\": \"c.743G>A\"}", "response": "Live retrieved public records (ClinVar, gnomAD, PubMed) \u2014 retrieval only, no model score: {label, note, clinvar, gnomad, pubmed}."}, {"method": "GET", "path": "/api/docs", "params": {}, "example": "https://evidra-variant-evidence-agent.hf.space/api/docs", "response": "This document (JSON)."}]}