Evo2 Variant Intelligence API

A production-grade API for predicting pathogenicity of genetic variants using the Evo2 deep learning model. The API supports Single Nucleotide Variants (SNVs), deletions, and insertions across multiple genome assemblies.

Fast Inference

Powered by NVIDIA H100 GPUs for rapid variant analysis

Secure

API key authentication and production-grade security

Multiple Genomes

Support for hg38, hg19, and other UCSC genome assemblies

Quick Start

Get started with the API in minutes. First, obtain your API key, then make your first request.

1. Get Your API Key

Contact support to obtain your API key. Include it in the X-API-Key header.

2. Analyze a Variant

Make a POST request to analyze a single nucleotide variant:

curl -X POST https://your-api-url.modal.run/analyze_single_variant \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "variant_position": 43119628,
    "alternative": "G",
    "genome": "hg38",
    "chromosome": "chr17",
    "mutation_type": "SNV"
  }'

3. Response

{
  "position": 43119628,
  "chromosome": "chr17",
  "genome": "hg38",
  "reference": "A",
  "alternative": "G",
  "delta_score": -0.001234,
  "prediction": "Likely pathogenic",
  "classification_confidence": 0.85,
  "mutation_type": "SNV"
}

API Reference

Complete reference for all API endpoints and parameters.

POST/analyze_single_variant

Analyze a single genetic variant for pathogenicity prediction.

Request Body

Parameter	Type	Required	Description
variant_position	integer	Yes	1-based genomic position
alternative	string	Yes	Alternative allele (nucleotide(s) or "-" for deletion)
genome	string	Yes	Genome assembly (e.g., "hg38", "hg19")
chromosome	string	Yes	Chromosome (e.g., "chr17", "chr1")
mutation_type	enum	No	"SNV", "DELETION", "INSERTION", "DUPLICATION", "MICROSATELLITE", "INDEL", "INVERSION", or "TRANSLOCATION" (default: "SNV")
reference	string	No	Reference allele (auto-detected if not provided)

Response

{
  "position": 43119628,
  "chromosome": "chr17",
  "genome": "hg38",
  "reference": "A",
  "alternative": "G",
  "delta_score": -0.001234,
  "prediction": "Likely pathogenic" | "Likely benign",
  "classification_confidence": 0.85,
  "mutation_type": "SNV"
}

Mutation Types

The API supports multiple types of genetic mutations. Each type has specific requirements for the request parameters.

SNV (Single Nucleotide Variant)

A substitution of a single nucleotide. This is the default mutation type.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "G",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "SNV"
}

• alternative must be a single nucleotide (A, C, G, or T)

Deletion

Removal of one or more nucleotides from the reference sequence.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "-",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "DELETION",
  "reference": "A"
}

• alternative should be "-" or empty string
• reference specifies the nucleotide(s) to delete

Insertion

Addition of one or more nucleotides after the reference position.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "ACGT",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "INSERTION",
  "reference": "A"
}

• alternative is the sequence to insert (non-empty, A/C/G/T only)
• reference is the nucleotide before the insertion point

Duplication

Duplication of a sequence segment. The reference sequence is duplicated one or more times.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "2",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "DUPLICATION",
  "reference": "ATCG"
}

• alternative can be a number of copies (e.g., "2", "3") or the duplicated sequence itself
• reference specifies the sequence to duplicate

Microsatellite

Short tandem repeat expansion or contraction. Used for analyzing microsatellite instability.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "CAGCAGCAG",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "MICROSATELLITE",
  "reference": "CAG"
}

• alternative is the expanded/contracted repeat sequence
• reference is the repeat unit (e.g., "CAG")

INDEL

Combined insertion and deletion. The reference sequence is deleted and replaced with the alternative sequence.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "ACGT",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "INDEL",
  "reference": "AT"
}

• alternative is the sequence to insert
• reference is the sequence to delete

Inversion

Reversal of a sequence segment. The reference sequence is reversed in place.

Example Request:

{
  "variant_position": 43119628,
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "INVERSION",
  "reference": "ATCG"
}

• alternative is optional (sequence will be automatically reversed)
• reference is the sequence to reverse

Translocation

Movement of a sequence to a different location. The reference sequence is removed and the alternative is inserted.

Example Request:

{
  "variant_position": 43119628,
  "alternative": "ATCG",
  "genome": "hg38",
  "chromosome": "chr17",
  "mutation_type": "TRANSLOCATION",
  "reference": "GCAT"
}

• alternative is the sequence to insert at new location
• reference is the sequence to remove from original location

Authentication

The API uses API key authentication for secure access. Include your API key in the request headers.

API Key Header

Include your API key in the X-API-Key header:

curl -X POST https://your-api-url.modal.run/analyze_single_variant \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{...}'

Note: If no API key is configured in the environment, the API operates in development mode and accepts requests without authentication. Always use API keys in production.

Code Examples

Examples in various programming languages to help you get started quickly.

import requests

url = "https://your-api-url.modal.run/analyze_single_variant"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here"
}
payload = {
    "variant_position": 43119628,
    "alternative": "G",
    "genome": "hg38",
    "chromosome": "chr17",
    "mutation_type": "SNV"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Prediction: {result['prediction']}")
print(f"Delta Score: {result['delta_score']}")
print(f"Confidence: {result['classification_confidence']:.2%}")

Architecture

Understanding how the API works under the hood.

System Architecture

1

Request Reception

API receives variant analysis request via FastAPI endpoint

2

Genome Sequence Fetching

Fetches 8kb window around variant position from UCSC Genome Browser API

3

Variant Sequence Construction

Constructs variant sequence based on mutation type (SNV/deletion/insertion)

4

Evo2 Model Inference

Runs Evo2 7B model on NVIDIA H100 GPU to score reference and variant sequences

5

Pathogenicity Prediction

Calculates delta score and classifies variant as pathogenic or benign with confidence

Model Details

Model:Evo2 7B

Hardware:NVIDIA H100 GPU

Sequence Window:8,192 bp

Scoring Method:Delta log-likelihood

Error Handling

The API returns standard HTTP status codes and error messages.

400 Bad Request

Invalid request parameters

{
  "detail": "For SNV, alternative must be a single nucleotide (A, C, G, or T)"
}

401 Unauthorized

Missing API key

{
  "detail": "API key required. Please provide X-API-Key header."
}

403 Forbidden

Invalid API key

{
  "detail": "Invalid API key."
}

500 Internal Server Error

Server-side error

{
  "detail": "Internal server error"
}