API Reference

Dnaerys gRPC API is designed for sub-second queries across population-scale datasets. It enables filtering variants based on genomic coordinates, inheritance models, functional and clinical annotations.

Protobuf Definition: The API is defined in dnaerys.proto files
Python Client Library provides a native Python API

Querying Capabilities

The API supports:

Positional Filtering: Selecting variants by chromosome regions
Genotypic State: Filtering by zygosity
Population Statistics: Filtering by AF, including gnomAD Exome and Genome AF
Annotations: Filtering by extensive functional annotations
Inheritance Models: Native support for De Novo, Homozygous Recessive, and Heterozygous Dominant trio analysis
Analytics: Embedded Kinship search, Polygenic Risk Scores, Inbreeding coefficient, HWE
Analytical QC: Kinship analysis and Sex Mismatch checks

Functional / Clinical Annotations

Supported Annotations:

VEP: Standard Ensembl Variant Effect Predictor annotations
Clinical Significance: ClinVar annotations
Predictive Scores: AlphaMissense, CADD, PolyPhen, and SIFT classification and raw scores
Population Frequency: Filtering by gnomAD exome and genome frequencies

The full list of supported annotations can be found in API proto file.

Note

Transcripts annotations: Genes have multiple transcripts, each is annotated separately by VEP. Annotations for all transcripts are preserved.

Note

Canonical transcripts: Annotations for canonical transcripts are always the first in the list of annotations in amino_acids field. This applies for both HGVSp and native VEP's "Amino_acids" annotations.

Note

CADD, PolyPhen & SIFT: The use of CADD, PolyPhen, and SIFT annotations is subject to their respective end-user licenses.

Python Client Library

Python Client Library for Dnaerys gRPC API. This library wraps the underlying RPCs into ~27 Pythonic methods, handles enum resolution, pagination, proto-to-dataclass conversion, streaming iteration, and translates gRPC errors into a clean exception hierarchy.

Full documentation: dnaerys-python.readthedocs.io

Install

pip install dnaerys

Verify

python3 -c "
import dnaerys
from dnaerys import DnaerysClient, Region

print('PROTO_VERSION:', dnaerys.PROTO_VERSION)

with DnaerysClient('db.dnaerys.org:443') as client:
    result = client.health()
    print('Server health:', result.status)
    info = client.dataset_info()
    print('Total samples:', info.samples_total)
"

Security and Authorization

1. Perimeter Security

Authorization in Kubernetes applications is better handled at the Ingress Controller level (or before it - on API GW level, followed by mTLS between API GW & IC). By treating the Ingress Controller as a Policy Enforcement Point, the application containers remain focused on business logic while the infrastructure layer handles identity validation.

2. Node-Level Authorization

For environments lacking ICs, Dnaerys nodes support JWT authorization. You can configure nodes to validate tokens signed with a wide variety of algorithms, including:

Symmetric: HS256, HS384, HS512
Asymmetric: RS256, RS512, ES256, Ed25519

Authorization is configured independently per node at startup. Once activated, the node will reject any request that does not carry a valid, signed token.