Ensembl VEP through GeneFoundry

Router invocation: vep_get_capabilities()

Read this first in a cold session. Returns server/tool metadata: supported assemblies (GRCh38 default, GRCh37), input formats (coordinate, rsID, HGVS, SPDI, CNV), the VEP-option allowlist, the four response_mode tiers, the deterministic error codes, the citation contract, a capabilities_version hash a warm client can compare to skip re-fetching, and a live `upstream` health summary (per-assembly Ensembl REST status from the circuit breaker). No upstream call.

Router invocation: vep_resolve_variant()

Use this when the caller's variant is an rsID, HGVS, SPDI, or loosely formatted, and you need the canonical CHR-POS-REF-ALT plus gene_symbol and most_severe_consequence that the annotation tools build on. Returns a variants[] list (one entry per ALT allele; a multi-allelic input also carries a multiple_alts warning) plus a top-level warnings[]. Coordinates are normalized locally; rsIDs/HGVS are recoded via Ensembl. Cheap (<1kB). Then call annotate_variant for the full VEP annotation.

Router invocation: vep_recode_variant()

Use this to translate a variant (or a batch, cap 200) between identifier systems -- rsID <-> HGVS (g./c./p./t.) <-> VCF string <-> SPDI -- without a full VEP annotation. Returns one result object per input. Use the optional fields filter to trim the payload to just the representations you need.

Router invocation: vep_annotate_variant()

Use this for the full VEP annotation of one variant: consequences, gene/transcript impact, HGVS, MANE/canonical flags, SIFT/PolyPhen, plus variant-level CADD/GERP under position_scores and per-transcript REVEL/AlphaMissense, and gnomAD frequencies. Input is parsed, recoded if needed, sent to the VEP region endpoint, then shaped to response_mode (start compact; widen to standard/full only if needed). The standard tier filters noisy neighbour transcripts by default (set transcripts='all' for every isoform). Carries a provenance block (endpoint + citation) and _meta.next_commands follow-ups.

Router invocation: vep_annotate_variants_batch()

Use this to annotate many variants (cap 200) in one call instead of looping annotate_variant. Returns a results list (each shaped to response_mode and tagged with its original input), a per-input errors list (parse/not-found failures that did not fail the batch), and a summary count. Identical canonical variants are de-duplicated into a single VEP request. Each result's standard-tier transcript list is filtered by default; per-result truncation is reported in that result's transcripts_summary.

Router invocation: vep_liftover_variant()

Use this to map a genomic coordinate (CHR-POS-REF-ALT) from one human assembly to the other (GRCh37 <-> GRCh38) via the Ensembl assembly-map endpoint. The two assemblies must differ. A unique mapping returns the lifted coordinate; zero mappings -> not_found, multiple -> ambiguous. HGVS/rsID inputs are unsupported (resolve_variant them first).

Router invocation: vep_check_upstream_health()

Use this to check whether the Ensembl REST hosts are healthy before a batch, or when calls start failing. Runs a live /info/ping of both assemblies (GRCh38 rest.ensembl.org, GRCh37 grch37.rest.ensembl.org) and returns each host's status (ok | recovering | down), circuit state, reachability, latency, and last error. If one build is degraded, route to the healthy one or back off. Returns <1kB.