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.

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 as written in the source, the effect, and sources. 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.

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 Ships with the beta

A Model Context Protocol server exposing the same endpoints as tools, lookup_gene, lookup_variant, lookup_drug_gene, and the parsing tools for beta partners, with descriptions written for models. It is not published yet; it will be listed in the public MCP directories when the beta opens. Until then, the OpenAPI works with any framework that generates tools from a spec.

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.