{
  "openapi": "3.1.0",
  "info": {
    "title": "DeepDNA API",
    "version": "2026-09-20",
    "summary": "Genomic and bloodwork interpretation for AI agents and developers.",
    "description": "One API in front of the messy parts of consumer genomics: every raw-data format, every knowledge base, every lab's PDF.\n\n**Status.** Layer 0 — the public knowledge endpoints under `/genes`, `/variants` and `/pgx` — is live, free, needs no key and stores nothing. The `/dna`, `/bloodwork` and `/crossover` endpoints are in **private beta**: they are specified here so you can design against them, but they are not deployed and do not answer yet, with or without a key. Access opens partner by partner; tell us what you are building at https://deepdna.ai/#beta.\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."
    },
    {
      "name": "dna",
      "description": "Private beta, not yet deployed. Designed to parse and annotate raw consumer DNA files with zero retention."
    },
    {
      "name": "bloodwork",
      "description": "Private beta, not yet deployed. Designed to turn a lab report PDF into structured biomarkers."
    },
    {
      "name": "crossover",
      "description": "Private beta. DNA + bloodwork → which predispositions have biomarkers outside the lab's range."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": [
          "knowledge"
        ],
        "summary": "Discovery: what is live, what is in beta, where 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 with guideline, phenotype groups and cited summary (level reserved, null today)",
        "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"
          }
        }
      }
    },
    "/dna/parse": {
      "post": {
        "tags": [
          "dna"
        ],
        "summary": "Private beta — any consumer raw DNA file → normalised variants",
        "operationId": "parseDna",
        "description": "Designed for 23andMe, AncestryDNA and MyHeritage exports; VCF planned later in the beta. Detects the format from the header, normalises chromosome labels and no-calls, and states the genome build explicitly in the response instead of assuming it. Nothing is stored: the file is parsed in memory and discarded when the response is sent. Not yet deployed.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-status": "private-beta",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Parsed file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParsedDna"
                }
              }
            }
          },
          "400": {
            "description": "Unrecognised format or unreadable file"
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    },
    "/dna/annotate": {
      "post": {
        "tags": [
          "dna"
        ],
        "summary": "Private beta — variants → ClinVar, PharmGKB, gnomAD, GWAS annotations",
        "operationId": "annotateDna",
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-status": "private-beta",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "enum": [
                      "GRCh37",
                      "GRCh38"
                    ]
                  },
                  "variants": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Genotype"
                    }
                  }
                },
                "required": [
                  "build",
                  "variants"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Annotated variants"
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    },
    "/bloodwork/parse": {
      "post": {
        "tags": [
          "bloodwork"
        ],
        "summary": "Private beta — any lab report PDF → structured biomarkers",
        "operationId": "parseBloodwork",
        "description": "Designed to return units normalised (mg/dL ↔ mmol/L and the rest), the lab's own reference ranges preserved, sex and age context kept where the report states it. Designed first for European laboratories. Not yet deployed.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-status": "private-beta",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured biomarkers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParsedBloodwork"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    },
    "/crossover": {
      "post": {
        "tags": [
          "crossover"
        ],
        "summary": "Private beta — DNA + bloodwork → which predispositions have biomarkers outside the lab's range",
        "operationId": "crossover",
        "description": "Something public databases cannot give you. A genotype says what could happen; a biomarker says what is happening. Given both, the response is designed to list genetic predispositions whose corresponding biomarkers are outside the laboratory's own range, and, just as usefully, the ones that are not. Not yet deployed.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-status": "private-beta",
        "responses": {
          "200": {
            "description": "Active and compensated risks"
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Private beta keys are issued by hand. Layer 0 needs none."
      }
    },
    "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"
                }
              },
              "private_beta": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "beta_signup": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "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"
        ]
      },
      "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"
            ]
          },
          "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": "CPIC, DPWG or null"
          },
          "level": {
            "type": [
              "string",
              "null"
            ],
            "description": "Guideline evidence level when the source states it; null otherwise"
          },
          "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"
        ]
      },
      "Genotype": {
        "type": "object",
        "properties": {
          "rsid": {
            "type": "string"
          },
          "chromosome": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "genotype": {
            "type": "string",
            "example": "AG"
          }
        },
        "required": [
          "rsid",
          "genotype"
        ]
      },
      "ParsedDna": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "23andme",
              "ancestrydna",
              "myheritage",
              "vcf"
            ]
          },
          "build": {
            "type": "string",
            "enum": [
              "GRCh37",
              "GRCh38"
            ]
          },
          "raw_count": {
            "type": "integer"
          },
          "normalized_count": {
            "type": "integer"
          },
          "variants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Genotype"
            }
          }
        }
      },
      "Biomarker": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "ferritin"
          },
          "value": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "value_si": {
            "type": "number"
          },
          "unit_si": {
            "type": "string"
          },
          "reference_low": {
            "type": [
              "number",
              "null"
            ]
          },
          "reference_high": {
            "type": [
              "number",
              "null"
            ]
          },
          "reference_source": {
            "type": "string",
            "description": "The lab that issued the report, not a generic range"
          },
          "flag": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "high",
              "normal",
              null
            ]
          }
        }
      },
      "ParsedBloodwork": {
        "type": "object",
        "properties": {
          "lab": {
            "type": [
              "string",
              "null"
            ]
          },
          "report_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "biomarkers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Biomarker"
            }
          }
        }
      }
    }
  }
}