A genetic variant REST API that refuses genome files
Public identifiers only: rsIDs, gene symbols, HGVS strings, and genomic coordinates. The server will not take a VCF, BAM, CRAM, or consumer DNA export.
That split is the product. Lookup of public records can be remote. Raw genomes stay on the machine that holds them. If a hosted API offers both, treat the upload path as a different product with a different threat model.
There is no API key for ordinary identifier lookup. AlphaGenome prediction is a separate opt-in CLI command with a key. It is not an HTTP upload route.
- Accepted: rs1799945, BRCA1, chr6:26090951, NM_000410.4:c.187C>G
- Rejected: VCF, BAM, CRAM, 23andMe, AncestryDNA, MyHeritage files
- Auth: none for /v1/query, /v1/gnomad, /v1/sources, /v1/stats, /v1/health
Endpoints, identifiers, and JSON
Base URL: https://api.genome.sh. JSON responses. No authentication header. Query values look like rs1799945, BRCA1, chr6:26090951, chr6:26090951:C:G, or HGVS such as NM_000410.4:c.187C>G.
GET /v1/query/:query is the joined lookup. GET /v1/gene/:gene lists known variants for a symbol. GET /v1/gnomad/:rsid returns population frequencies. GET /v1/sources, /v1/stats, and /v1/health describe the running server and its probe.
The website query page uses the same lookup. Machine-readable notes live in /llms.txt and /genome-catalog.json. Human docs live at /docs.
- GET /v1/query/:query: rsID, gene, HGVS, or coordinates
- GET /v1/gene/:gene: variants for a symbol such as BRCA1
- GET /v1/gnomad/:rsid: population frequencies
- GET /v1/sources and /v1/stats: versions and counts
- GET /v1/health: liveness
Call /v1/query, /v1/gnomad, and /v1/sources
curl and jq are enough. There is no SDK you must install. Limit gene catalogs with the documented query string when you only need a handful of rows.
Use rsIDs when you have them. rs334, rs429358, rs1800562, and rs1799945 are reliable tests because they exist in ClinVar and gnomAD. Coordinates need the assembly that matches the database.
If you are building a product on top, cache public identifiers. Do not send a user file to genome.sh. There is no endpoint for it.
curl -s https://api.genome.sh/v1/query/rs1799945 | jq . curl -s https://api.genome.sh/v1/query/BRCA1?limit=5 | jq . curl -s https://api.genome.sh/v1/gnomad/rs429358 | jq . curl -s https://api.genome.sh/v1/sources | jq .
No API key, and what that still forbids
Open lookup is for public records. It is not a license to ship genotypes in query strings, logs, or chat transcripts. Browser apps should keep file parsing on the client.
Rate limits exist. For ordinary interactive use you will not notice them. For 100,000 rsIDs, install a local database with genome db install and stay off the network.
The same privacy rule applies to coding agents. Give the agent an rsID, a gene, or a path to a local file plus the local CLI. Do not paste a 23andMe export into a prompt that then calls the API.
When the CLI is the right tool instead
Use the CLI for VCF annotation, batch files, CRAM extraction, and anything that contains genotypes. Use the API for identifier lookup from a server that must not hold genomes.
Install path: cargo install genome-sh, then genome db install lite|standard|full. Formats: human, json, compact. genome annotate file.vcf.gz --format json streams locally.
The in-browser importer at /import also parses VCF in the tab. It does not upload the file to genome.sh. That is the web equivalent of the CLI privacy boundary.
cargo install genome-sh genome db install standard genome query rs334 --format json genome annotate sample.vcf.gz --filter clinical --format json
Compared with NCBI E-utilities and myvariant.info
NCBI E-utilities are the official live path into ClinVar and dbSNP. They return XML, want pacing, and want a key at higher rates. genome.sh returns JSON from a snapshot.
myvariant.info is a hosted aggregator of many sources behind one getvariant call. genome.sh is a local-first CLI with an optional open API for the sources it ships: ClinVar, gnomAD, dbSNP, AlphaMissense, ClinGen, PharmGKB, UniProt.
Field names differ. Map JSON explicitly. If a source exists only on another aggregator, use that aggregator for that identifier. If you are annotating a VCF, stay local.
Rate, bulk, and caching public identifiers
Cache rsID responses. Public annotations change on database releases, not every second. Record /v1/sources next to anything you persist.
Do not fan out one HTTP call per VCF row from a web app. That is slow, noisy, and the wrong privacy model once you already have genotypes on disk.
The CLI is the bulk tool. genome annotate reads the file once and joins local SQLite. That is the jq-shaped path the project is named for.
CORS, agents, and genotypes that must not become URLs
The public API is meant to be called from tools and servers. CORS on identifier GET is not permission to put GT values in the path. Keep sample columns on disk.
A coding agent that can run genome query --format json on the user's machine does not need a screenshot of ClinVar. Give it the agent guide. Copy the report template out of the repo before filling personal data.
genome.sh is informational software, not a medical device. The API prints public annotations. It does not diagnose.
Questions
Is there a free genetic variant REST API without a key?
Yes. https://api.genome.sh answers identifier queries without authentication. It does not accept genome files.
Can I POST a VCF to the genetic variant API?
No. Annotate VCFs with the local CLI or the in-browser importer. The HTTP API never accepts VCF, BAM, or 23andMe files.
Is there a rate limit?
Yes. For ordinary interactive use you will not notice it. For 100,000 rsIDs, install a local database with genome db install.
How is this different from myvariant.info?
myvariant.info is a hosted aggregator of many sources. genome.sh is a local-first CLI with an optional open API for the sources it ships. Field names differ.
Does the genetic variant API support CORS?
The public API is meant to be called from tools and servers. Browser apps should still avoid putting genotypes in query strings.
Where is the OpenAPI file?
The human docs are at /docs. Machine-readable notes are in /llms.txt and /genome-catalog.json.
Can I query a gene such as BRCA1?
Yes. GET /v1/query/BRCA1 or GET /v1/gene/BRCA1. Add a limit when you only need a few rows. A gene catalog is not a personal report.
Do I need the API after cargo install genome-sh?
No. Local query is the default after genome db install. The API is for identifier lookup without a local DB.