deepdna-ai Knowledge API

openapi: 3.2.0
info:
  title: DeepDNA Knowledge 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/).


    DeepDNA 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).


    **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:
  schemas:
    Gene:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Variant:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    GeneSummary:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    GeneRef:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Discovery:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    PgxPair:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Meta:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  responses:
    NotFound:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true