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
Base URL
All API requests should be made to:
https://variantbase.com/api/v1/
Authentication (Future)
API key authentication for production use:
Authorization: Bearer YOUR_API_KEY
Demo environment requires no authentication
Make Your First Request
Try querying a variant:
curl https://variantbase.com/api/variants/BRCA1_c.68_69del.json
๐ Core Endpoints
Retrieve comprehensive variant information including ACMG classification, population frequencies, and clinical evidence.
Parameters
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."
}
Search variants by gene, genomic coordinates, or clinical significance (future endpoint).
Query Parameters
List all variants for a specific gene with filtering and pagination (future endpoint).
Path Parameters
๐ท๏ธ Variant Identifier Format
VariantBase uses a standardized naming convention for variant identifiers that follows HGVS nomenclature while ensuring URL-safe file naming.
Transformation Rules
GENE:HGVS_c
GENE_HGVS_c
c.123T>A
c.123T_A
c.123A>G
c.123A_G
c.123_124del
c.123_124del
c.123dup
c.123dup
Complete Examples
๐ Response Schema
All successful variant responses follow a consistent JSON schema with comprehensive clinical and technical information.
Core Identification
Clinical Significance
Population Data
โ ๏ธ Error Handling
The API uses standard HTTP status codes and returns detailed error information in JSON format.
Success
Request completed successfully, variant data returned
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"
}
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"
}
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
Average API response time for variant lookups
Rate Limits (Production)
API calls per hour for authenticated users
Data Freshness
Updates from ClinVar, gnomAD, and clinical sources
Uptime SLA
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.
Electronic Health Records (EHR)
Embed variant information directly into patient records with clinical decision support.
Bioinformatics Pipelines
Programmatic access for NGS analysis workflows and variant annotation pipelines.
Clinical Applications
Mobile and web applications for genetic counselors, clinicians, and researchers.
๐งช 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
๐ 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 AcquisitionAPI Documentation
This comprehensive documentation demonstrates production-ready API design for genetic variant knowledge platforms.
Download API SpecAcquistion Help
If required, professional assistance is available for domain acquisition discussions.
Contact