API v2.0

AlleleAI API Documentation

Powerful genomic variant analysis API with real-time interpretation, population frequencies, and clinical annotations. Built for researchers, clinicians, and bioinformaticians.

🚀 Quick Start

1. Get API Key

Use demo key for testing:

demo_alleleai_2025_genomics

2. Make First Request

curl -H "Authorization: Bearer demo_alleleai_2025_genomics" \
  https://api.alleleai.com/v2/variants/BRAF:c.1799T>A

3. Explore Endpoints

Full variant analysis, batch processing, and population genetics available

📡 Base Configuration

Base URL https://api.alleleai.com/v2
Authentication Bearer Token (API Key)
Rate Limits 1000 requests/minute (Demo: 100/min)
Response Format JSON (UTF-8)
Timeout 30 seconds

Required Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "Accept": "application/json"
}

🔬 Core Endpoints

Variant Analysis GET

/variants/{variant_id}

Comprehensive analysis of a single genetic variant including pathogenicity prediction, population frequencies, and clinical significance.

Path Parameters
Parameter Type Required Description
variant_id string Yes Variant identifier in HGVS format (e.g., BRAF:c.1799T>A) or rsID (e.g., rs7412)
Query Parameters
Parameter Type Default Description
include_predictions boolean true Include AI pathogenicity predictions
populations array all Filter by populations: AFR, AMR, EAS, EUR, SAS, ASJ, FIN
evidence_level string standard Evidence depth: basic | standard | comprehensive
Example Request
GET /v2/variants/BRAF:c.1799T>A?include_predictions=true&populations=EUR,AMR
Authorization: Bearer demo_alleleai_2025_genomics
Response Schema
{
  "variant": {
    "id": "BRAF:c.1799T>A",
    "gene": {
      "symbol": "BRAF",
      "name": "B-Raf proto-oncogene",
      "entrez_id": 673,
      "ensembl_id": "ENSG00000157764"
    },
    "nomenclature": {
      "hgvs_c": "NM_004333.6:c.1799T>A",
      "hgvs_p": "NP_004324.2:p.Val600Glu",
      "hgvs_g": "NC_000007.14:g.140753336A>T",
      "rsid": null,
      "cosmic_id": "COSM476"
    },
    "location": {
      "chromosome": "7",
      "position": 140753336,
      "reference": "A",
      "alternate": "T",
      "assembly": "GRCh38"
    }
  },
  "clinical_significance": {
    "classification": "Pathogenic",
    "confidence": 0.997,
    "acmg_criteria": ["PS1", "PM1", "PP2", "PP3", "PP5"],
    "review_status": "Expert panel reviewed",
    "last_evaluated": "2025-08-01"
  },
  "ai_predictions": {
    "pathogenicity_score": 0.994,
    "model_version": "AlleleAI-v2.3",
    "ensemble_models": {
      "neural_network": 0.996,
      "gradient_boost": 0.991,
      "transformer": 0.995
    },
    "functional_impact": "HIGH",
    "confidence_interval": [0.989, 0.998]
  },
  "population_frequencies": {
    "global_af": 0.00047,
    "populations": [
      {
        "population": "EUR",
        "allele_frequency": 0.00062,
        "allele_count": 124,
        "allele_number": 200000,
        "homozygotes": 0
      },
      {
        "population": "AMR",
        "allele_frequency": 0.00031,
        "allele_count": 31,
        "allele_number": 100000,
        "homozygotes": 0
      }
    ],
    "max_population_af": 0.00062,
    "min_population_af": 0.00001
  },
  "clinical_annotations": {
    "diseases": [
      {
        "name": "Melanoma",
        "omim_id": "155600",
        "inheritance": "Somatic",
        "penetrance": "High"
      },
      {
        "name": "Colorectal cancer",
        "omim_id": "114500",
        "inheritance": "Somatic",
        "penetrance": "Moderate"
      }
    ],
    "drug_response": [
      {
        "drug": "Vemurafenib",
        "response": "Sensitive",
        "evidence_level": "1A",
        "fda_approved": true
      },
      {
        "drug": "Dabrafenib",
        "response": "Sensitive",
        "evidence_level": "1A",
        "fda_approved": true
      }
    ],
    "clinical_trials": 47
  },
  "evidence": {
    "pubmed_citations": 1847,
    "clinvar_submissions": 23,
    "functional_studies": 156,
    "case_reports": 892,
    "references": [
      {
        "source": "ClinVar",
        "id": "RCV000013961",
        "url": "https://www.ncbi.nlm.nih.gov/clinvar/variation/13961/"
      },
      {
        "source": "COSMIC",
        "id": "COSM476",
        "url": "https://cancer.sanger.ac.uk/cosmic/mutation/overview?id=476"
      }
    ]
  },
  "metadata": {
    "api_version": "2.0",
    "response_time_ms": 87,
    "cached": false,
    "last_updated": "2025-08-28T10:30:00Z"
  }
}

Batch Variant Analysis POST

/variants/batch

Analyze multiple variants in a single request. Supports up to 100 variants per batch.

Request Body
{
  "variants": [
    "BRCA1:c.68_69del",
    "BRAF:c.1799T>A",
    "rs7412",
    "TP53:p.R175H"
  ],
  "options": {
    "include_predictions": true,
    "populations": ["EUR", "EAS"],
    "evidence_level": "standard"
  }
}
Response
{
  "batch_id": "batch_7f8a9b2c",
  "total_variants": 4,
  "successful": 4,
  "failed": 0,
  "results": [
    {
      "variant_id": "BRCA1:c.68_69del",
      "status": "success",
      "data": { /* Full variant object */ }
    },
    // ... additional variants
  ],
  "processing_time_ms": 342
}

Population Frequency Analysis GET

/populations/{variant_id}/frequencies

Detailed population-specific allele frequencies with ancestry analysis and Hardy-Weinberg equilibrium statistics.

Response includes:
  • Allele frequencies across 26 populations
  • Hardy-Weinberg p-values
  • Fixation indices (Fst)
  • Selection signatures
  • Founder effect analysis

Gene-Level Analysis GET

/genes/{gene_symbol}/summary

Comprehensive gene-level statistics including variant burden, constraint metrics, and clinical relevance.

⚡ Advanced Features

VCF Upload & Analysis

POST /v2/vcf/analyze
Content-Type: multipart/form-data

{
  "file": "variants.vcf",
  "annotation_level": "comprehensive",
  "reference_genome": "GRCh38"
}

Process entire VCF files with up to 1M variants

Real-time Streaming

GET /v2/stream/variants
Accept: text/event-stream

data: {"variant": "BRCA2:c.5946del", "score": 0.98}
data: {"variant": "MLH1:c.199G>A", "score": 0.45}

Stream variant interpretations in real-time

GraphQL Support

POST /v2/graphql
{
  variant(id: "BRAF:c.1799T>A") {
    gene { symbol }
    clinical_significance
    ai_predictions { score }
  }
}

Flexible queries with GraphQL endpoint

⚠️ Error Handling

Status Code Error Type Description Example
200 Success Request completed successfully Normal response
400 Bad Request Invalid variant format or parameters Malformed HGVS notation
401 Unauthorized Invalid or missing API key Expired token
404 Not Found Variant not in database Novel variant
429 Rate Limited Too many requests Exceeded quota
500 Server Error Internal server error Contact support

Error Response Format

{
  "error": {
    "code": "INVALID_VARIANT_FORMAT",
    "message": "The provided variant notation is invalid",
    "details": "Expected format: GENE:c.DNA or GENE:p.Protein",
    "suggestion": "Use HGVS nomenclature: BRAF:c.1799T>A",
    "documentation": "https://api.alleleai.com/docs/variants",
    "request_id": "req_8a7b6c5d4e",
    "timestamp": "2025-08-28T15:30:00Z"
  }
}

📊 Rate Limits & Quotas

Demo Tier

100 requests/minute

1,000 requests/day

10 variants/batch

✓ Basic annotations ✓ Population frequencies ✗ VCF upload

Professional

1,000 requests/minute

100,000 requests/day

100 variants/batch

✓ Full annotations ✓ AI predictions ✓ VCF processing

Enterprise

Unlimited requests

Custom quotas

1,000+ variants/batch

✓ Priority support ✓ Custom models ✓ On-premise option

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1693238400
X-RateLimit-Reset-After: 60

💻 Code Examples

import requests
import json

# Configuration
API_KEY = "demo_alleleai_2025_genomics"
BASE_URL = "https://api.alleleai.com/v2"

# Analyze a variant
def analyze_variant(variant_id):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(
        f"{BASE_URL}/variants/{variant_id}",
        headers=headers,
        params={
            "include_predictions": True,
            "evidence_level": "comprehensive"
        }
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API Error: {response.status_code}")

# Example usage
result = analyze_variant("BRAF:c.1799T>A")
print(f"Pathogenicity: {result['clinical_significance']['classification']}")
print(f"AI Score: {result['ai_predictions']['pathogenicity_score']}")

🔔 Webhooks & Events

Subscribe to real-time events for variant reclassifications, new evidence, and annotation updates.

Available Events

Webhook Payload

{
  "event": "variant.reclassified",
  "timestamp": "2025-08-28T15:45:00Z",
  "data": {
    "variant_id": "BRCA2:c.5946del",
    "previous_classification": "VUS",
    "new_classification": "Likely Pathogenic",
    "evidence": "New functional study published",
    "confidence": 0.89
  }
}

🚀 Premium Domain Available

AlleleAI.com — The perfect domain for your genomics AI platform. Combining "Allele" (genetic variants) with "AI" instantly communicates cutting-edge genomic intelligence.

✓ $150B genomics market by 2028
✓ Exact-match SEO advantage
✓ Generic industry term
✓ Global .com authority
Inquire About Domain