API Documentation

Query genetic variants programmatically. No authentication required.

The genome.sh API gives you access to ClinVar, gnomAD, dbSNP, AlphaMissense, and more through a simple REST interface. All endpoints return JSON. Rate limits are generous and no API key is needed.

Base URL

All API requests use this base URL. The API is served over HTTPS only.

URL

https://api.genome.sh

Authentication

The genome.sh API is completely free and open. No API key, no registration, no authentication of any kind. Just send requests.

bash

# No API key needed
curl https://api.genome.sh/v1/stats

Errors

The API uses standard HTTP status codes. Errors return a JSON object with an error field describing the issue.

Status	Meaning
200	Success
400	Invalid query format
500	Internal database error
502	Upstream API error (gnomAD proxy)

Error response

{
 "error": "Invalid query: not a valid rsID, gene, or HGVS notation"
}

GET/v1/query/:query

Look up a variant by rsID, gene name, or HGVS notation. Returns clinical significance, gene, position, and associated conditions from ClinVar.

Parameters

Name	Type	Required	Description
query	string	Required	rsID (e.g. rs1799945), gene name (e.g. BRCA1), or HGVS notation
limit	integer	Optional	Maximum number of results to return. Default: 100

curl

curl https://api.genome.sh/v1/query/rs1799945

Response

[{
 "rsid": "rs1799945",
 "chromosome": "chr6",
 "position": 26090951,
 "ref": "C",
 "alt": "G",
 "gene": "HFE",
 "clinical_significance": "Pathogenic",
 "condition": "Hereditary hemochromatosis"
}]

GET/v1/variant/:chrom/:pos/:ref/:alt

Query a specific variant by exact genomic coordinates. Provide chromosome, position, reference allele, and alternate allele.

Parameters

Name	Type	Description
chrom	string	Chromosome (e.g. chr6 or 6)
pos	integer	Genomic position
ref	string	Reference allele
alt	string	Alternate allele

curl

curl https://api.genome.sh/v1/variant/chr6/26090951/C/G

GET/v1/gene/:gene

Retrieve all known variants for a given gene. Returns a list of ClinVar entries with clinical significance and conditions.

Parameters

Name	Type	Required	Description
gene	string	Required	Gene symbol (e.g. BRCA1, HFE). Case insensitive.
limit	integer	Optional	Maximum number of results to return. Default: 100

curl

curl https://api.genome.sh/v1/gene/BRCA1?limit=5

GET/v1/gnomad/:rsid

Fetch population frequency data from gnomAD for a given variant. Data is proxied and cached from the gnomAD GraphQL API.

Parameters

Name	Type	Description
rsid	string	rsID of the variant (e.g. rs1799945)

curl

curl https://api.genome.sh/v1/gnomad/rs1799945

Response

{
 "rsid": "rs1799945",
 "genome": {
 "af": 0.0921,
 "ac": 14032,
 "an": 152312,
 "homozygote_count": 712
 }
}

GET/v1/sources

List all data sources in the database with their version, variant count, and last update timestamp.

curl

curl https://api.genome.sh/v1/sources

Response

[{
 "source": "clinvar",
 "version": "2026-03",
 "variant_count": 2843191,
 "updated_at": "2026-03-01T00:00:00Z"
}]

GET/v1/stats

Get database statistics including total variant count across all sources.

curl

curl https://api.genome.sh/v1/stats

Response

{
 "total_variants": 2843191,
 "sources": [...]
}

GET/health

Health check endpoint. Returns 200 with status "ok" if the API server is running.

curl

curl https://api.genome.sh/health

Response

{ "status": "ok" }

CLI Reference

Install the CLI to query variants locally, annotate VCF files, or pipe output to other tools. All commands support JSON, TSV, and human-readable output.

Install

bash

cargo install genome-sh

genome query

Look up variants by rsID, gene, or coordinates. Uses the API by default, add --local for offline mode.

bash

genome query rs1799945

genome annotate

Annotate a VCF file with clinical data from all databases.

bash

genome annotate my_variants.vcf

genome compare

Compare two VCF files. Shows shared and unique variants with kinship estimation.

bash

genome compare sample1.vcf sample2.vcf

genome predict

Get AlphaMissense pathogenicity predictions for variants.

bash

genome predict rs1799945

genome db build

Download and build the local database from open sources.

bash

genome db build --tier full

genome db stats

Show database statistics and source versions.

bash

genome db stats

genome serve

Start the REST API server locally.

bash

genome serve --port 3042