DeepDNA API reference

Base URL https://deepdna.ai/api/v1. The knowledge endpoints are live and free with no key. The same records are served to AI agents by the MCP server, and a free local package reads a raw DNA file on your own computer. DeepDNA does not parse DNA files or lab reports on its servers.

Quickstart

No account, no key. Ask for a drug–gene pair and read the answer with its sources:

curl https://deepdna.ai/api/v1/pgx/CYP2C19/clopidogrel

Or ask what a variant in a 23andMe file means:

curl https://deepdna.ai/api/v1/variants/rs1801133

Or list everything the base knows about a gene, including what a consumer array cannot resolve for it:

curl https://deepdna.ai/api/v1/genes/CYP2D6

Lookups are case-insensitive. Responses are JSON, UTF-8, CORS-open, and cacheable for an hour.

Status

EndpointStatusAuth
GET / discoveryLivenone
GET /genes, /genes/{symbol}Livenone
GET /variants/{rsid}Livenone
GET /pgx/{gene}, /pgx/{gene}/{drug}Livenone

Response shape

Every successful response is an object with the resource at the top level and a meta block. The disclaimer is in every payload, on purpose: an agent that forwards our answer forwards the caveat with it.

{
  "gene": { … },
  "meta": {
    "disclaimer": "Educational information only, not medical advice or diagnosis. …",
    "api_version": "2026-09-20",
    "docs": "https://deepdna.ai/docs/",
    "status": "live"
  }
}

Versioning is by date in meta.api_version and the X-DeepDNA-Api-Version header. Fields are added, never removed or renamed, without a new version.

Errors

Errors are 404 with a machine-readable code and a human hint that is meant to be shown to a model:

{
  "error": {
    "code": "not_found",
    "resource": "pgx",
    "id": "CYP2C19/aspirin",
    "hint": "Drugs curated for CYP2C19: clopidogrel, omeprazole, …"
  },
  "meta": { … }
}

The hint lists what is available so an agent can recover in one more call instead of guessing.

Knowledge endpoints Live

Curated from primary sources — ClinVar, PharmGKB, PharmVar, CPIC and DPWG guidelines, OMIM, dbSNP and the primary literature — and reviewed before publication. Coverage starts with the pharmacogenes and the most-searched nutrigenomic and risk genes, and grows. See the current list. If your code calls PharmGKB’s own API, its old hostname no longer resolves: moving to api.clinpgx.org.

GET /genes

Every gene in the base with symbol, name, category and a one-paragraph summary.

GET /genes/{symbol}

One gene in full. The fields worth knowing:

FieldWhat it is
key_variants[]The rsIDs that matter for this gene, with alleles and effect.
phenotypes[]Metabolizer or trait phenotypes, in the guideline's own terms.
consumer_array_caveatRead this before acting on a consumer genotype. What a 23andMe-class array cannot resolve for this gene — copy-number variants, phasing, rare alleles.
drugs[]Drug–gene pairs with the guideline (CPIC/DPWG), the phenotype groups it distinguishes, and a cited summary.
sources[]Label and URL for every claim.

GET /variants/{rsid}

One variant by dbSNP rsID. Returns the gene it sits in, the alleles described on the plus strand of GRCh37, the effect, sources, and a reading block: assembly, chromosome, position, reference_allele and variant_allele (plus strand), gene_strand, countable and strand_ambiguous, with dbSNP and Ensembl links. For a missense variant, alphamissense carries the AlphaMissense prediction for the protein change, taken from the published dataset (AlphaMissense_hg19, Zenodo record 10813168; Cheng et al., Science 2023; CC BY 4.0) with the score rounded to 3 decimals: a note, is_clinical_classification: false, am_class in AlphaMissense’s own bins (likely_benign below 0.34, ambiguous, likely_pathogenic above 0.564), score from 0 to 1, protein_variant and uniprot_id. It predicts how the change affects the protein. It is not an ACMG/ClinVar classification, not a measure of disease risk and not evidence about drug response: alleles with established effects can score likely_benign (APOE ε4, CYP2C9 *2 and *3) and common alleles that cause no disease can score likely_pathogenic (MTHFR C677T). Google DeepMind states that AlphaMissense is not validated or approved for clinical use. It is null for variants that are not a single-letter missense change. A malformed ID (anything that is not rs followed by digits) is rejected before lookup.

GET /pgx/{gene}/{drug}

One drug–gene pair. guideline is CPIC or DPWG (optionally followed by ; FDA label), drug label (the record rests on an FDA label) or null (it rests on the primary literature). level is CPIC’s level for the gene–drug pair, copied from the CPIC database. On CPIC’s A–D scale, which combines the strength of the evidence with how actionable the pair is, CPIC A means genetic information should be used to change prescribing, CPIC B that it could be, and CPIC C or CPIC D that CPIC recommends no prescribing action. Combined levels such as CPIC B/C are copied as CPIC publishes them. “(provisional)” marks a pair CPIC has not yet covered in a guideline; the record’s guideline field says what it actually rests on. A record for a drug class carries the level CPIC gives each of its members when they share one (G6PD and sulfonamides: CPIC C). It is null when CPIC has not rated the pair. It is not the strength of any one recommendation, it describes CPIC’s rating rather than advice for any person, and DeepDNA assigns no levels of its own. GET /pgx/{gene} lists every pair for a gene. Worked example in Python: CYP2C19 and SLCO1B1 from a raw DNA file, from genotype to CPIC phenotype to this endpoint.

The API reports what the guideline says about a phenotype. It does not compute a phenotype from a genotype, and it does not recommend a dose. That line is deliberate — see not medical advice.

MCP server Live

A remote Model Context Protocol server at https://deepdna.ai/mcp (Streamable HTTP, stateless, no key) exposes the knowledge layer as tools with descriptions written for models: list_genes, lookup_gene, lookup_variant, lookup_drug_gene and check_medications, which screens a list of generic drug names for curated drug–gene records and says whether each rests on a CPIC or DPWG guideline, a drug label or the literature. Same dataset and the same disclaimer as the endpoints above. Two prompts, medication_review and explain_variant, package the common questions.

No genotypes. The tools take gene symbols, rsIDs and drug names. An argument a tool does not declare, such as a genotype, is refused, and its value is not used, stored or counted. What is typed into a declared field is used to answer that request. We record it only as a short lookup label: an rsID in the form rs123, a gene symbol from our list of known pharmacogenes (for example CYP2C19 or TPMT), or a drug name when it is one we cover. Anything else, whatever it is, is recorded as “(other)”. Please don’t type a personal genetic result into these fields. In the REST API, each variant record also carries a reading block (assembly GRCh37, position, reference and variant allele on the plus strand, the gene’s strand, whether the position can be read on its own and whether it is strand-ambiguous); the MCP tools return the alleles as text. An agent that reads a raw DNA file compares the genotype with them in the agent, outside DeepDNA. The server does not compute a phenotype, a metabolizer status or a risk.

Every tool is read-only: none of them writes data or stores an email, and requests are counted only as described above.

{
  "mcpServers": {
    "deepdna": { "type": "http", "url": "https://deepdna.ai/mcp" }
  }
}

Setup for each client: connect the MCP server. A worked example: a pharmacogenomics MCP server for Claude, Cursor and VS Code. Registry name: ai.deepdna/knowledge. Clients that cannot speak MCP can still generate tools from the OpenAPI.

Local package for raw DNA files Live

The remote server takes no genotype. For a raw DNA file there is deepdna-mcp, a free MCP server that runs on the user’s own computer. It reads 23andMe, AncestryDNA and MyHeritage/FamilyTreeDNA exports (.txt, .csv or .zip); VCF files are not supported. It is MIT-licensed, on PyPI, with its source on GitHub and the registry name ai.deepdna/local.

Its read_dna_file tool reports what the file shows at the curated positions for the genes requested, with the record’s text and sources, and, where a position is countable, how many copies of the variant allele the file shows. It checks the file’s strand first, and a missing or unreadable position is reported as unknown, never as normal. APOE, BRCA1 and HFE are disease-risk genes, so they are read only when named in the request. lookup_drug_gene asks the public API above for a drug–gene record and sends only the gene and drug names. Like the remote server, it gives no metabolizer status, diplotype or dose, and what it returns is educational information, not a diagnosis.

The package sends nothing from the file to DeepDNA: it downloads the same public records for every user. What read_dna_file returns, the letters and counts at the positions asked for, becomes part of the conversation with the AI model, under its provider’s terms. This is only true while the assistant reads the file through the tool: in Claude Code, start it from a folder that does not contain the file, directly or in a subfolder, and refuse its own Read, Grep or Bash on the file.

Claude Code, with uv installed:

claude mcp add --scope user deepdna-local -- uvx deepdna-mcp@0.1.1

Setup for Claude Desktop, a real result and what to approve: read your 23andMe file with Claude, without uploading it.

Data handling

Not medical advice

Every response says it, and we ask the same of what you build on it: this is educational information, not diagnosis, prescription or dosing. The API reports what guidelines say about genes, variants and drug–gene pairs, with their sources, so that a clinician has something concrete to look at. It does not replace one.

Changelog