# Structural Variants API
> Human genomic structural variation as an API — powered by NCBI dbVar, the archive of structural variants (SVs): copy-number variants (CNVs), large deletions, duplications, insertions, inversions and translocations, typically larger than 50 base pairs. This is the structural counterpart to single-nucleotide variant databases: search structural variants overlapping a gene (or by free text) and get each variant's dbVar accession, the study it came from, its type, the genes it overlaps, its genomic placement on GRCh38 and its clinical significance; then look up any variant for the full record — placements on both GRCh37 and GRCh38 assemblies, variant type, genes, clinical significance, study type, methods and variant counts. From BRCA1 CNVs to Cri-du-chat deletions, it is ideal for genomics, cytogenetics, rare-disease and bioinformatics work. A structural-variation / CNV resource — distinct from clinical single-nucleotide variant interpretation (ClinVar), population allele frequencies (gnomAD) and trait associations (GWAS). Open data from NCBI dbVar (public domain).

## 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/dbvar-api/..."
```

## Pricing
- **Free** (Free) — 2,280 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 45,500 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 228,000 calls/Mo, 20 req/s
- **Mega** ($57/Mo) — 830,000 calls/Mo, 50 req/s

## Endpoints

### Structural Variants

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

**Parameters:**
- `gene` (query, optional, string) — Gene symbol Example: `BRCA1`
- `q` (query, optional, string) — Free-text query (alternative to gene)
- `limit` (query, optional, string) — Max results (1-100, default 20)

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

**Response:**
```json
{
    "data": {
        "count": 20,
        "query": "gene:BRCA1",
        "total": 2790,
        "variants": [
            {
                "genes": [
                    "BRCA1"
                ],
                "study": "nstd232",
                "organism": "human",
                "taxon_id": 9606,
                "accession": "nsv7897183",
                "placement": {
                    "end": 43094800,
                    "start": 43094800,
                    "assembly": "GRCh38.p12",
                    "chromosome": "17"
                },
                "object_type": "VARIANT",
                "variant_type": "insertion",
                "clinical_significance": null
            },
            {
                "genes": [
                    "BRCA1"
                ],
                "study": "nstd232",
                "organism": "human",
                "taxon_id": 9606,
                "accession": "nsv7897034",
                "placement": {
                    "end": 43099831,
                    "start": 43099831,
                    "assembly": "GRCh38.p12",
                    "chromosome": "17"
                },
                "object_type": "VARIANT",
                "variant_type": "insertion",
                "clinical_significance": null
            },
            {
                "genes": [
                    "BRCA1"
                ],
                "study": "nstd232",
                "organism": "human",
                "taxon_id": 9606
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/variant` — A structural variant's full record

**Parameters:**
- `id` (query, optional, string) — A dbVar accession (from /v1/search) Example: `nsv7897183`

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

**Response:**
```json
{
    "data": {
        "variant": {
            "uid": "57738222",
            "url": "https://www.ncbi.nlm.nih.gov/dbvar/variants/nsv7897183/",
            "genes": [
                "BRCA1"
            ],
            "study": "nstd232",
            "methods": [
                "Sequencing"
            ],
            "organism": "human",
            "taxon_id": 9606,
            "accession": "nsv7897183",
            "placement": {
                "end": 43094800,
                "start": 43094800,
                "assembly": "GRCh38.p12",
                "chromosome": "17"
            },
            "placements": [
                {
                    "end": 41246817,
                    "start": 41246817,
                    "assembly": "GRCh37",
                    "chromosome": "17"
                },
                {
                    "end": 43094800,
                    "start": 43094800,
                    "assembly": "GRCh38.p12",
                    "chromosome": "17"
                }
            ],
            "study_type": null,
            "object_type": "VARIANT",
            "variant_type": "insertion",
            "variant_count": null,
            "variant_call_count": 1,
            "clinical_significance": null
        }
    },
    "meta": {
        "timestamp": "2026-06-01T23:41:01.024Z",
        "request_id": "f094f383-fdac-4e44-8654-9c51529cb61e"
    },
    "status": "ok",
    "message": "Variant retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Endpoint catalogue & notes

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

**Response:**
```json
{
    "data": {
        "note": "dbVar is NCBI's archive of human genomic structural variation — structural variants (SVs) larger than ~50 bp: copy-number variants (CNVs), large deletions and duplications, insertions, inversions and translocations. /v1/search?gene=BRCA1 finds structural variants overlapping a gene (or use q= for free-text), returning each variant's dbVar accession (e.g. nsv7897183), the study it came from, variant type, organism, overlapping genes, GRCh38 genomic placement and clinical significance; /v1/variant?id=nsv7897183 returns a single variant's full record — placements on all assemblies (GRCh37 and GRCh38), variant type, genes, clinical significance, study type, methods and variant counts (you may also pass the numeric uid). Accessions look like nsv… (variant), nssv… (variant call) or nstd… (study). Data from NCBI dbVar (public domain). A structural-variation / CNV resource — distinct from clinical single-nucleotide variant interpretation (ClinVar), population allele frequencies (gnomAD) and trait associations (GWAS). Ideal for genomics, cytogenetics, rare-disease and bioinformatics tools.",
        "source": "NCBI dbVar — database of genomic structural variation (ncbi.nlm.nih.gov/dbvar)",
        "endpoints": [
            "/v1/search",
            "/v1/variant",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T23:41:01.124Z",
        "request_id": "91116d99-5379-4d8e-94db-373ca2ae4cb1"
    },
    "s
…(truncated, see openapi.json for full schema)
```


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