VariantBase API Documentation

RESTful API for genetic variant knowledge and clinical interpretation

DEMONSTRATION API โ€” Not for clinical use or medical decisions

๐Ÿ“š API Overview

The VariantBase API provides programmatic access to genetic variant knowledge, ACMG/AMP classifications, population frequencies, and clinical interpretation data. This demonstration showcases a production-ready API structure for genetic variant databases and clinical genomics platforms.

๐Ÿงฌ

50M+ Variant Records

Comprehensive collection from ClinVar, gnomAD, COSMIC, and proprietary clinical datasets

โšก

Sub-100ms Response

High-performance API with advanced genomic coordinate indexing and caching

๐ŸŽฏ

ACMG/AMP Standards

Automated classification following clinical genetics guidelines with confidence scoring

๐Ÿ”—

Universal Integration

RESTful design compatible with LIMS, EMR systems, and bioinformatics pipelines

๐Ÿš€ Quick Start

1

Base URL

All API requests should be made to:

https://variantbase.com/api/v1/
2

Authentication (Future)

API key authentication for production use:

Authorization: Bearer YOUR_API_KEY

Demo environment requires no authentication

3

Make Your First Request

Try querying a variant:

curl https://variantbase.com/api/variants/BRCA1_c.68_69del.json

๐Ÿ”Œ Core Endpoints

GET
/api/variants/{variant_id}.json

Retrieve comprehensive variant information including ACMG classification, population frequencies, and clinical evidence.

Parameters

variant_id
string
required
Variant identifier in GENE_HGVS_c format

Example Request

GET /api/variants/BRCA1_c.68_69del.json HTTP/1.1
Host: variantbase.com
Accept: application/json

Response (200 OK)

{
  "id": "BRCA1:c.68_69del",
  "gene": "BRCA1",
  "chromosome": "17",
  "position": {
    "start": 43124016,
    "end": 43124017,
    "assembly": "GRCh38"
  },
  "hgvs": {
    "c": "NM_007294.4:c.68_69del",
    "p": "p.Glu23Valfs*17",
    "g": "g.43124016_43124017del"
  },
  "variant_type": "deletion",
  "clinical_significance": {
    "interpretation": "Pathogenic",
    "confidence": "high",
    "acmg_criteria": ["PVS1", "PM2", "PP3"],
    "evidence_level": "criteria_provided_multiple"
  },
  "population_data": {
    "gnomad": {
      "allele_frequency": 0.00001,
      "allele_count": 12,
      "allele_number": 251456,
      "populations": {
        "nfe": 0.00002,
        "afr": 0.000005,
        "asj": 0.00008
      }
    }
  },
  "functional_annotation": {
    "consequence": "frameshift_variant",
    "impact": "high",
    "protein_effect": "loss_of_function"
  },
  "evidence_sources": [
    {
      "database": "ClinVar",
      "accession": "VCV000014145",
      "url": "https://www.ncbi.nlm.nih.gov/clinvar/variation/14145/",
      "last_updated": "2025-01-15"
    },
    {
      "database": "gnomAD",
      "version": "v4.0.0",
      "url": "https://gnomad.broadinstitute.org/variant/17-43124016-GAG-G",
      "last_updated": "2024-10-01"
    }
  ],
  "clinical_context": {
    "associated_conditions": ["Hereditary breast and ovarian cancer syndrome"],
    "inheritance_pattern": "autosomal_dominant",
    "penetrance": "high"
  },
  "computational_predictions": {
    "cadd_score": 35.2,
    "revel_score": 0.932,
    "spliceai_score": 0.01
  },
  "metadata": {
    "last_reviewed": "2025-01-20",
    "review_status": "expert_panel",
    "api_version": "v1.2.0",
    "response_time_ms": 45
  },
  "disclaimer": "Demo data for illustration only. Not for clinical use or medical decisions."
}
GET
/api/variants/search

Search variants by gene, genomic coordinates, or clinical significance (future endpoint).

Query Parameters

gene
string
optional
Gene symbol (e.g., BRCA1, TP53)
chr:pos
string
optional
Genomic coordinates (e.g., 17:43124016)
significance
enum
optional
pathogenic, likely_pathogenic, vus, likely_benign, benign
limit
integer
optional
Results per page (default: 20, max: 100)
GET
/api/genes/{gene_symbol}/variants

List all variants for a specific gene with filtering and pagination (future endpoint).

Path Parameters

gene_symbol
string
required
Official gene symbol (e.g., BRCA1, BRCA2, TP53)

๐Ÿท๏ธ Variant Identifier Format

VariantBase uses a standardized naming convention for variant identifiers that follows HGVS nomenclature while ensuring URL-safe file naming.

Transformation Rules

Input Format
API Identifier
Description
GENE:HGVS_c
GENE_HGVS_c
Replace colon with underscore
c.123T>A
c.123T_A
Replace greater-than with underscore
c.123A>G
c.123A_G
Handle substitutions
c.123_124del
c.123_124del
Deletions remain unchanged
c.123dup
c.123dup
Duplications remain unchanged

Complete Examples

BRCA1:c.68_69del
โ†’
BRCA1_c.68_69del.json
Deletion
BRAF:c.1799T>A
โ†’
BRAF_c.1799T_A.json
Substitution
TP53:c.524G>A
โ†’
TP53_c.524G_A.json
Substitution
KRAS:c.35G>A
โ†’
KRAS_c.35G_A.json
Substitution

๐Ÿ“‹ Response Schema

All successful variant responses follow a consistent JSON schema with comprehensive clinical and technical information.

Core Identification

id
string
Original HGVS identifier (GENE:c.notation)
gene
string
Official gene symbol
chromosome
string
Chromosome identifier (1-22, X, Y, MT)

Clinical Significance

interpretation
enum
Pathogenic, Likely pathogenic, VUS, Likely benign, Benign
acmg_criteria
array
Applied ACMG/AMP criteria (PVS1, PS1, PM2, etc.)
confidence
enum
high, moderate, low

Population Data

gnomad.allele_frequency
float
Overall allele frequency in gnomAD
gnomad.populations
object
Population-specific frequencies (nfe, afr, asj, etc.)

โš ๏ธ Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

200

Success

Request completed successfully, variant data returned

404

Not Found

Variant identifier not found in database

{
  "error": "not_found",
  "message": "Variant not in demo set",
  "details": "Variant ID 'INVALID_c.123G_T' does not exist",
  "timestamp": "2025-01-20T10:30:00Z",
  "request_id": "req_abc123"
}
400

Bad Request

Invalid variant identifier format or malformed request

{
  "error": "invalid_format",
  "message": "Invalid variant identifier format",
  "details": "Expected format: GENE_c.notation (e.g., BRCA1_c.68_69del)",
  "timestamp": "2025-01-20T10:30:00Z"
}
500

Server Error

Internal server error (rare in production systems)

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "request_id": "req_xyz789",
  "timestamp": "2025-01-20T10:30:00Z"
}

๐Ÿ”— Integration Examples

cURL Command Line

# Basic variant lookup
curl -X GET "https://variantbase.com/api/variants/BRCA1_c.68_69del.json" \
  -H "Accept: application/json"

# With error handling
curl -X GET "https://variantbase.com/api/variants/BRCA1_c.68_69del.json" \
  -H "Accept: application/json" \
  -w "HTTP Status: %{http_code}\n" \
  -o response.json

JavaScript / Node.js

// Using fetch API
async function getVariant(variantId) {
  try {
    const response = await fetch(
      `https://variantbase.com/api/variants/${variantId}.json`
    );
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const variant = await response.json();
    return variant;
  } catch (error) {
    console.error('Variant lookup failed:', error);
    return null;
  }
}

// Usage
const variant = await getVariant('BRCA1_c.68_69del');
if (variant) {
  console.log('Clinical significance:', variant.clinical_significance.interpretation);
  console.log('ACMG criteria:', variant.clinical_significance.acmg_criteria);
}

Python

import requests
import json

class VariantBaseAPI:
    def __init__(self, base_url="https://variantbase.com/api"):
        self.base_url = base_url
    
    def get_variant(self, variant_id):
        """
        Retrieve variant information by ID
        
        Args:
            variant_id (str): Variant identifier (e.g., 'BRCA1_c.68_69del')
        
        Returns:
            dict: Variant data or None if not found
        """
        url = f"{self.base_url}/variants/{variant_id}.json"
        
        try:
            response = requests.get(url, timeout=10)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API request failed: {e}")
            return None

# Usage example
api = VariantBaseAPI()
variant = api.get_variant('BRCA1_c.68_69del')

if variant:
    print(f"Gene: {variant['gene']}")
    print(f"Clinical significance: {variant['clinical_significance']['interpretation']}")
    print(f"ACMG criteria: {', '.join(variant['clinical_significance']['acmg_criteria'])}")
    print(f"Population frequency: {variant['population_data']['gnomad']['allele_frequency']}")
else:
    print("Variant not found")

R

# Install required packages if needed
# install.packages(c("httr", "jsonlite"))

library(httr)
library(jsonlite)

# Function to query VariantBase API
get_variant <- function(variant_id, base_url = "https://variantbase.com/api") {
  url <- paste0(base_url, "/variants/", variant_id, ".json")
  
  tryCatch({
    response <- GET(url, timeout(10))
    
    if (status_code(response) == 200) {
      content <- content(response, "text", encoding = "UTF-8")
      variant_data <- fromJSON(content)
      return(variant_data)
    } else {
      warning(paste("API request failed with status:", status_code(response)))
      return(NULL)
    }
  }, error = function(e) {
    warning(paste("Request error:", e$message))
    return(NULL)
  })
}

# Usage example
variant <- get_variant("BRCA1_c.68_69del")

if (!is.null(variant)) {
  cat("Gene:", variant$gene, "\n")
  cat("Clinical significance:", variant$clinical_significance$interpretation, "\n")
  cat("ACMG criteria:", paste(variant$clinical_significance$acmg_criteria, collapse = ", "), "\n")
  cat("Population frequency:", variant$population_data$gnomad$allele_frequency, "\n")
} else {
 cat("Variant not found\n")
}

โšก Performance & Limits

๐Ÿš€

Response Time

< 100ms

Average API response time for variant lookups

๐Ÿ“Š

Rate Limits (Production)

1000/hour

API calls per hour for authenticated users

๐Ÿ’พ

Data Freshness

Weekly

Updates from ClinVar, gnomAD, and clinical sources

๐Ÿ”„

Uptime SLA

99.9%

Service availability guarantee for production

Optimization Tips

  • Batch Requests: Use multiple API calls efficiently rather than sequential requests
  • Caching: Cache responses locally for frequently accessed variants
  • Error Handling: Implement retry logic for transient failures
  • Compression: Use gzip compression to reduce response size

๐Ÿ—๏ธ Platform Integration

VariantBase API is designed for seamless integration with existing clinical genomics and laboratory information systems.

๐Ÿงช

Laboratory Information Management Systems (LIMS)

Direct integration with laboratory workflows for automated variant interpretation and reporting.

Epic Beaker Cerner PowerChart LabWare LIMS
๐Ÿ“‹

Electronic Health Records (EHR)

Embed variant information directly into patient records with clinical decision support.

Epic MyChart Cerner PowerChart Allscripts
๐Ÿ”ฌ

Bioinformatics Pipelines

Programmatic access for NGS analysis workflows and variant annotation pipelines.

Nextflow WDL/Cromwell Snakemake
๐Ÿ“ฑ

Clinical Applications

Mobile and web applications for genetic counselors, clinicians, and researchers.

Clinical Dashboards Mobile Apps Decision Support

๐Ÿงช Try the Demo API

Test the API with these demonstration variants from our curated dataset:

๐Ÿ”ด Pathogenic Variants

๐ŸŸก VUS (Variants of Unknown Significance)

๐ŸŸข Benign Variants

Select a variant above to test the API
Select a variant to begin testing

๐Ÿ“ž Support & Domain Acquisition

๐Ÿ’Ž

Domain Acquisition

VariantBase.com represents a premium opportunity in the clinical genomics market. Perfect for companies building variant interpretation platforms.

Inquire About Acquisition
๐Ÿ“š

API Documentation

This comprehensive documentation demonstrates production-ready API design for genetic variant knowledge platforms.

Download API Spec
๐ŸŽฏ

Acquistion Help

If required, professional assistance is available for domain acquisition discussions.

Contact

Why Acquire VariantBase.com?

๐ŸŽฏ Perfect brand alignment for genetic variant platforms
๐Ÿ“ˆ $2.8B clinical genomics market opportunity
๐Ÿ” Exact-match SEO advantages for variant database searches
โšก Complete demonstration platform included