{ "openapi": "3.1.0", "info": { "title": "DeepDNA API", "version": "2026-09-20", "summary": "Curated, cited genomic knowledge for AI agents and developers.", "description": "Curated, cited records on genes, variants and drug–gene pairs, served from the public knowledge endpoints under `/genes`, `/variants` and `/pgx`. They are live, free, need no key or account and store nothing. The same records are served to AI agents by the remote MCP server at https://deepdna.ai/mcp (how to connect: https://deepdna.ai/connect/).\n\nDeepDNA does not parse DNA files or lab reports on its servers. To read a raw DNA file, use the free open-source local package `deepdna-mcp`, which runs on your own computer and sends nothing from the file to DeepDNA (https://deepdna.ai/docs/#local).\n\n**Every response is educational information, not medical advice or diagnosis.**", "contact": { "name": "DeepDNA", "url": "https://deepdna.ai", "email": "api@deepdna.ai" }, "termsOfService": "https://deepdna.ai/terms/" }, "servers": [ { "url": "https://deepdna.ai/api/v1" } ], "tags": [ { "name": "knowledge", "description": "Live. Public, curated, cited. No key, no personal data, nothing stored." } ], "paths": { "/": { "get": { "tags": [ "knowledge" ], "summary": "Discovery: what is live, where the MCP server and the docs are", "operationId": "discover", "responses": { "200": { "description": "Discovery document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } } } } }, "/genes": { "get": { "tags": [ "knowledge" ], "summary": "List genes in the knowledge base", "operationId": "listGenes", "responses": { "200": { "description": "Genes", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "genes": { "type": "array", "items": { "$ref": "#/components/schemas/GeneSummary" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/genes/{symbol}": { "get": { "tags": [ "knowledge" ], "summary": "One gene: function, key variants, phenotypes, drug interactions, sources", "operationId": "getGene", "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string", "example": "CYP2D6" }, "description": "HGNC symbol, case-insensitive" } ], "responses": { "200": { "description": "Gene", "content": { "application/json": { "schema": { "type": "object", "properties": { "gene": { "$ref": "#/components/schemas/Gene" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/variants/{rsid}": { "get": { "tags": [ "knowledge" ], "summary": "One variant by rsID", "operationId": "getVariant", "parameters": [ { "name": "rsid", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rs\\d+$", "example": "rs1801133" } } ], "responses": { "200": { "description": "Variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "$ref": "#/components/schemas/Variant" }, "gene": { "$ref": "#/components/schemas/GeneRef" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/pgx/{gene}": { "get": { "tags": [ "knowledge" ], "summary": "Drug–gene pairs for a pharmacogene", "operationId": "listPgx", "parameters": [ { "name": "gene", "in": "path", "required": true, "schema": { "type": "string", "example": "CYP2C19" } } ], "responses": { "200": { "description": "Pairs", "content": { "application/json": { "schema": { "type": "object", "properties": { "gene": { "type": "string" }, "count": { "type": "integer" }, "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/PgxPair" } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/pgx/{gene}/{drug}": { "get": { "tags": [ "knowledge" ], "summary": "One drug–gene pair: guideline, CPIC level, phenotype groups and cited summary", "operationId": "getPgx", "parameters": [ { "name": "gene", "in": "path", "required": true, "schema": { "type": "string", "example": "CYP2C19" } }, { "name": "drug", "in": "path", "required": true, "schema": { "type": "string", "example": "clopidogrel" } } ], "responses": { "200": { "description": "Pair", "content": { "application/json": { "schema": { "type": "object", "properties": { "pair": { "$ref": "#/components/schemas/PgxPair" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "responses": { "NotFound": { "description": "Not in the knowledge base", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "not_found" }, "resource": { "type": "string" }, "id": { "type": "string" }, "hint": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "disclaimer": { "type": "string" }, "api_version": { "type": "string" }, "docs": { "type": "string", "format": "uri" }, "status": { "type": "string" } } }, "Source": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "null for a literature citation given by author/journal/year" } }, "required": [ "label" ] }, "Discovery": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "endpoints": { "type": "object", "properties": { "live": { "type": "array", "items": { "type": "object" } } } }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "object", "properties": { "status": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "transport": { "type": "string" }, "registry_name": { "type": "string" }, "docs": { "type": "string", "format": "uri" } } } } }, "GeneRef": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } }, "GeneSummary": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "pharmacogene", "nutrigenomics", "disease_risk", "carrier" ] }, "summary": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "KeyVariant": { "type": "object", "properties": { "rsid": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "alleles": { "type": [ "string", "null" ] }, "effect": { "type": [ "string", "null" ] }, "frequency_note": { "type": [ "string", "null" ] } }, "required": [ "rsid" ], "description": "A variant highlighted on the gene record. Its alleles text matches /variants/{rsid}, where the structured reading block lives." }, "DrugInteraction": { "type": "object", "properties": { "drug": { "type": "string" }, "guideline": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] } }, "required": [ "drug" ] }, "Gene": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "function": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "key_variants": { "type": "array", "items": { "$ref": "#/components/schemas/KeyVariant" } }, "phenotypes": { "type": "array", "items": { "type": "string" } }, "clinical_relevance": { "type": [ "string", "null" ] }, "consumer_array_caveat": { "type": [ "string", "null" ], "description": "What a consumer SNP array cannot resolve for this gene. Always read this before acting on a consumer genotype." }, "drugs": { "type": "array", "items": { "$ref": "#/components/schemas/DrugInteraction" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "related_blog": { "type": [ "string", "null" ] }, "disclaimer": { "type": "string" }, "protein": { "type": [ "string", "null" ] }, "ncbi_gene_id": { "type": [ "string", "null" ] }, "locus": { "type": [ "string", "null" ] } }, "required": [ "symbol", "summary", "category", "sources", "disclaimer" ] }, "Variant": { "type": "object", "properties": { "rsid": { "type": "string" }, "gene": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "alleles": { "type": [ "string", "null" ] }, "effect": { "type": [ "string", "null" ] }, "reading": { "$ref": "#/components/schemas/Reading" }, "alphamissense": { "type": [ "object", "null" ], "description": "AlphaMissense prediction for a missense variant, from AlphaMissense_hg19 (Zenodo 10813168; Cheng et al., Science 2023; CC BY 4.0), score rounded to 3 decimals. Predicts the protein effect only: not an ACMG/ClinVar classification, not disease risk, not drug response; Google DeepMind states it is not validated or approved for clinical use. Null when not a single-letter missense change.", "properties": { "note": { "type": "string" }, "is_clinical_classification": { "type": "boolean", "const": false }, "am_class": { "type": "string", "enum": [ "likely_benign", "ambiguous", "likely_pathogenic" ], "description": "AlphaMissense bins: likely_benign < 0.34, ambiguous 0.34–0.564, likely_pathogenic > 0.564" }, "score": { "type": "number" }, "score_note": { "type": "string" }, "thresholds": { "type": "string" }, "protein_variant": { "type": "string" }, "uniprot_id": { "type": "string" }, "source": { "$ref": "#/components/schemas/Source" } } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } }, "required": [ "rsid", "gene" ] }, "PgxPair": { "type": "object", "properties": { "gene": { "type": "string" }, "drug": { "type": "string" }, "guideline": { "type": [ "string", "null" ], "description": "What the record rests on: CPIC or DPWG (optionally with \"; FDA label\"), \"drug label\" for an FDA label, or null for the primary literature" }, "level": { "type": [ "string", "null" ], "description": "CPIC level for the pair, copied from the CPIC database (\"CPIC A\" to \"CPIC D\", combined levels such as \"CPIC B/C\" as published, optionally \"(provisional)\"); null when CPIC has not rated the pair. CPIC's rating, not advice for any person." }, "summary": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "phenotypes": { "type": "array", "items": { "type": "string" }, "description": "Phenotype groups the guideline distinguishes for this pair" } }, "required": [ "gene", "drug" ] }, "Reading": { "type": "object", "description": "How to read this position in a raw DNA file, checked against dbSNP and Ensembl. DeepDNA's tools take no genotype: compare a user's file with these alleles in the agent or app, outside DeepDNA.", "properties": { "assembly": { "type": "string", "enum": [ "GRCh37" ] }, "chromosome": { "type": "string" }, "position": { "type": "integer" }, "reference_allele": { "type": [ "string", "null" ], "description": "Plus strand of GRCh37, as 23andMe raw data reports it; check the orientation of other providers' files. Null for insertions and deletions." }, "variant_allele": { "type": [ "string", "null" ], "description": "Plus-strand allele the record's effect refers to. Null for insertions and deletions." }, "gene_strand": { "type": "string", "enum": [ "plus", "minus" ] }, "countable": { "type": "boolean", "description": "True when copies of variant_allele at this one position can be counted from a raw file and that allele is, on its own, the variant the record describes. False for a haplotype-only position, an allele that common star alleles of different function share (as at rs1065852, carried by both *4 and *10), and insertions or deletions. Rarer alleles can share a countable allele, so a count is of the allele only: not a star-allele call, an isoform or a metabolizer status, and not a judgement on how reliable a chip call is. On chromosome X, males carry one copy, so counting needs the person's sex." }, "strand_ambiguous": { "type": "boolean", "description": "A/T or C/G: the letters are the same on both strands, so you can't tell which strand a file uses, and a homozygote on the other strand reads as the other allele. Count it only when the file is known to be on the plus strand of GRCh37." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } }, "required": [ "assembly", "chromosome", "position", "reference_allele", "variant_allele", "gene_strand", "countable", "strand_ambiguous", "sources" ] } } } }