# ClinVar API
> ClinVar as an API, powered by the US National Library of Medicine via NCBI E-utilities. ClinVar is the public archive of the relationships between human genetic variants and health, recording the clinical significance (interpretation) of each variant — whether it is Pathogenic, Likely pathogenic, of Uncertain significance, Likely benign or Benign — together with the conditions it is associated with. /v1/search?gene=BRCA1 searches ClinVar by gene symbol, or by free text with q= (e.g. a disease or HGVS expression), returning the total number of matching variants and a list of ClinVar variation ids. /v1/variant?id=4852102 returns a variant's summary: its ClinVar accession (VCV…), title, variant type, the variation and cDNA names, the clinical classification and review status, the associated condition(s), the gene(s) and primary gene, the chromosome and location, the protein change and the molecular consequence, plus a link to the ClinVar record. Get a variation id from /v1/search, then fetch its details. Ideal for clinical-genomics and variant-annotation pipelines, rare-disease and genetic-counselling tools, and research dashboards. Data from NCBI ClinVar (public domain). This is clinical variant interpretation — distinct from population allele-frequency databases (such as gnomAD) and from protein/sequence databases. Please keep request rates modest under NCBI fair-use.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/clinvar-api/..."
```

## Pricing
- **Free** (Free) — 2,400 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 50,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 225,000 calls/Mo, 12 req/s
- **Mega** ($62/Mo) — 820,000 calls/Mo, 35 req/s

## Endpoints

### Variants

#### `GET /v1/search` — Search ClinVar by gene or text

**Parameters:**
- `gene` (query, optional, string) — Gene symbol, e.g. BRCA1 Example: `BRCA1`
- `q` (query, optional, string) — Free text (disease/HGVS)
- `limit` (query, optional, string) — Max ids (1-100)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clinvar-api/v1/search?gene=BRCA1"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "query": "BRCA1 (gene)",
        "total": 15897,
        "variation_ids": [
            "4851990",
            "4851779",
            "4851364",
            "4851359",
            "4850689",
            "4849514",
            "4848953",
            "4848411",
            "4845640",
            "4845425",
            "4842666",
            "4842665",
            "4842664",
            "4842663",
            "4842662",
            "4842661",
            "4842660",
            "4842659",
            "4842657",
            "4842656"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:33.766Z",
        "request_id": "776a062a-3e03-4dc7-aaa5-a3a582213744"
    },
    "status": "ok",
    "message": "Search results retrieved",
    "success": true
}
```

#### `GET /v1/variant` — A variant clinical summary

**Parameters:**
- `id` (query, required, string) — ClinVar variation id (from /v1/search), e.g. 4852102 Example: `4852102`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clinvar-api/v1/variant?id=4852102"
```

**Response:**
```json
{
    "data": {
        "variant": {
            "id": "4852102",
            "url": "https://www.ncbi.nlm.nih.gov/clinvar/variation/4852102/",
            "type": "copy number loss",
            "genes": [
                "BRCC3",
                "CLIC2",
                "CMC4",
                "F8",
                "FUNDC2",
                "LOC106146143"
            ],
            "title": "GRCh38/hg38 Xq28(chrX:154890748-155334361)x1",
            "location": "00000000000154890748",
            "accession": "VCV004852102",
            "chromosome": "X",
            "conditions": [
                "See cases"
            ],
            "cdna_change": "GRCh38/hg38 Xq28(chrX:154890748-155334361)x1",
            "primary_gene": "BRCC3",
            "review_status": "criteria provided, single submitter",
            "classification": "Pathogenic",
            "protein_change": null,
            "variation_name": "GRCh38/hg38 Xq28(chrX:154890748-155334361)x1",
            "classification_type": "germline",
            "molecular_consequence": []
        }
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:33.933Z",
        "request_id": "38969713-5e4d-4140-9b89-26ec701998f8"
    },
    "status": "ok",
    "message": "Variant retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clinvar-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "ClinVar is NCBI's public archive of the relationships between human genetic variants and phenotypes, with the clinical significance of each variant. /v1/search?gene=BRCA1 = search ClinVar by gene symbol (gene=BRCA1) or by free text (q=…), returning the total hit count and a list of ClinVar variation ids; /v1/variant?id=4852102 = a variant's summary — its accession (VCV…), title, variant type, the variation/cDNA name, the clinical classification (Pathogenic, Likely pathogenic, Uncertain significance, Likely benign, Benign), the review status, the associated condition(s), the gene(s) and primary gene, chromosome and location, protein change and molecular consequence. Get a variation id from /v1/search. Data from NCBI ClinVar (public domain). This is clinical variant interpretation — distinct from population allele-frequency databases (gnomAD) and from protein/sequence databases. Ideal for clinical-genomics, variant-annotation and rare-disease tooling. Please keep request rates modest (NCBI fair use).",
        "source": "NCBI ClinVar via E-utilities (eutils.ncbi.nlm.nih.gov) — National Library of Medicine",
        "endpoints": [
            "/v1/search",
            "/v1/variant",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:34.011Z",
        "request_id": "aca3289c-c38a-45c2-8f75-baaf86c3a34e"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/clinvar-api
OpenAPI spec: https://www.oanor.com/api/clinvar-api/openapi.json