DeepDNA Pharmacogenomics

npx add-mcp 'https://deepdna.ai/mcp'

DeepDNA API reference

Base URL https://deepdna.ai/api/v1. The knowledge endpoints are live and free with no key. Everything else is specified so you can build against the contract now, and is opened as a private beta.

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

Endpoint	Status	Auth
GET / discovery	Live	none
GET /genes, /genes/{symbol}	Live	none
GET /variants/{rsid}	Live	none
GET /pgx/{gene}, /pgx/{gene}/{drug}	Live	none
POST /dna/parse, /dna/annotate	Private beta	Bearer key
POST /bloodwork/parse	Private beta	Bearer key
POST /crossover	Private beta	Bearer key

"Private beta" means the endpoint is specified but not deployed: it does not answer yet, with or without a key. We would rather say that plainly than ship an endpoint that returns a mock. Access opens partner by partner, and the first keys go to the people who tell us what they are building.

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:

Field	What 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_caveat	Read 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. 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, DPWG or null. level is reserved for the guideline's evidence grade and is null for every pair today: the curated sources give the recommendation but not the grade, and it will be filled from the CPIC dataset rather than guessed. 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.

Parsing endpoints Private beta

These are the endpoints that touch personal data, and they are designed around that: parse in memory, return, retain nothing. They are specified here and in the OpenAPI so you can build against the contract; none of them is deployed yet.

POST /dna/parse

Multipart upload of a raw consumer DNA export. Designed to detect 23andMe, AncestryDNA and MyHeritage from the header (VCF later in the beta), normalise chromosome labels and no-calls, and state the genome build explicitly instead of assuming it. Ancestry reports GRCh37, and a silent build mismatch inverts every position.

curl -X POST https://deepdna.ai/api/v1/dna/parse \
  -H "Authorization: Bearer $DEEPDNA_KEY" \
  -F file=@genome_export.txt
{ "format": "ancestrydna", "build": "GRCh37", "raw_count": 677312, "normalized_count": 668904, "variants": [ … ] }

POST /dna/annotate

Variants in, annotations out: designed to return ClinVar significance, PharmGKB clinical annotations, gnomAD frequencies and GWAS associations on one evidence scale, with a source on every record. Send the output of /dna/parse or your own list.

POST /bloodwork/parse

Multipart upload of a lab report PDF. Designed to return structured biomarkers with the value as printed, the value in SI, and the reference range the laboratory itself printed, not a generic one, because a ferritin of 250 is normal on one lab's range and flagged on another's. Designed first for European laboratories.

{ "lab": "…", "report_date": "2026-08-14",
  "biomarkers": [ { "code": "ferritin", "value": 612, "unit": "ng/mL",
      "reference_low": 30, "reference_high": 400, "reference_source": "lab", "flag": "high" } ] }

POST /crossover

DNA and bloodwork together. Designed to return genetic predispositions whose corresponding biomarkers are outside the lab's range, inside it, or unmeasured (and which test would answer it). A genotype says what could happen; a biomarker says what is.

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. Each variant 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 (countable) and whether it is strand-ambiguous. An agent that reads a raw DNA file compares the genotype with it in the agent, outside DeepDNA. The server does not compute a phenotype, a metabolizer status or a risk.

One tool writes: request_beta_access registers interest in the private beta with an email and an optional use case, and only when the agent sets user_consent after asking the user. It stores the same record as the beta form; see the privacy policy. The parsing tools join the server when the beta endpoints are deployed.

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

Setup for each client and 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.

Data handling

• Knowledge endpoints receive nothing personal and store nothing. Requests are served from a curated dataset bundled into the function; there is no database and no third-party call at request time.
• Parsing endpoints are designed for zero retention. Files are parsed in memory and discarded when the response is sent. No genome on disk, no genome in a database.
• Processor, not controller. If your users' data goes through the beta, DeepDNA acts as your processor (GDPR Art. 28) for special-category data (Art. 9); you remain the controller and need an Art. 9(2) basis, typically explicit consent. A data processing agreement, the processing location and the list of subprocessors will be published before the beta handles a real file, not after.
• Based in Europe. DeepDNA operates from Spain under Spanish and EU law. The pipeline is designed for EU-only processing with no transfers of genetic data outside the EEA.

Not medical advice

Every response says it, and the API terms that ship with the beta will require it of what you build: this is educational information, not diagnosis, prescription or dosing. The API reports genotypes, guideline positions and their sources so that a clinician has something concrete to look at. It does not replace one.

Changelog

• 2026-09-20 — Knowledge endpoints live: /genes, /variants, /pgx. OpenAPI 3.1 published. Private beta announced for the parsing endpoints; contract published, nothing deployed yet.