United States National Library of Medicine Genome API

openapi: 3.2.0
info:
  title: NCBI Datasets REST Genome API
  description: The NCBI Datasets REST API v2 provides programmatic access to biological data across NCBI databases including genome assemblies, gene records, and protein sequences. Returns data packages or metadata for genomes by taxon, assembly accession, or biosample; genes by gene ID or symbol; and viruses by taxon. The full OpenAPI specification is available at https://www.ncbi.nlm.nih.gov/datasets/docs/v2/openapi3/openapi3.docs.yaml and on GitHub at github.com/ncbi/datasets.
  version: 2.0.0
  contact:
    name: NCBI Datasets
    url: https://www.ncbi.nlm.nih.gov/datasets/docs/v2/
  license:
    name: Public Domain
    url: https://www.usa.gov/government-works
  externalDocs:
    url: https://www.ncbi.nlm.nih.gov/datasets/docs/v2/openapi3/openapi3.docs.yaml
    description: Full OpenAPI 3.0 Specification
servers:
- url: https://api.ncbi.nlm.nih.gov/datasets/v2
  description: NCBI Datasets API v2
tags:
- name: Genome
  description: Genome assembly data and metadata
paths:
  /genome/taxon/{taxons}/dataset_report:
    get:
      operationId: getGenomeDatasetReport
      summary: Get Genome Dataset Report
      description: Retrieve a report of genome assemblies for one or more taxonomic groups. Returns assembly metadata including accession, assembly level, total length, chromosome count, and submission dates.
      tags:
      - Genome
      parameters:
      - name: taxons
        in: path
        description: Comma-separated list of taxa (species names, common names, or NCBI taxonomy IDs)
        required: true
        schema:
          type: string
        example: human
      - name: api_key
        in: query
        description: NCBI API key for increased rate limits
        required: false
        schema:
          type: string
      - name: filters.assembly_level
        in: query
        description: Filter by assembly level
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - chromosome
            - complete_genome
            - contig
            - scaffold
        style: form
        explode: true
      - name: filters.assembly_source
        in: query
        description: Filter by assembly source
        required: false
        schema:
          type: string
          enum:
          - refseq
          - genbank
      - name: page_size
        in: query
        description: Number of results per page (max 1000)
        required: false
        schema:
          type: integer
          default: 20
      - name: page_token
        in: query
        description: Token for the next page of results
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Genome assembly report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenomeDatasetReport'
  /genome/accession/{accessions}/dataset_report:
    get:
      operationId: getGenomeByAccession
      summary: Get Genome by Accession
      description: Retrieve genome assembly metadata for specific assembly accessions (e.g. GCF_000001405.40 for the human reference genome).
      tags:
      - Genome
      parameters:
      - name: accessions
        in: path
        description: Comma-separated assembly accession numbers
        required: true
        schema:
          type: string
        example: GCF_000001405.40
      - name: api_key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Genome assembly metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenomeDatasetReport'
components:
  schemas:
    GenomeAssembly:
      type: object
      description: A genome assembly record
      properties:
        accession:
          type: string
          description: Assembly accession (e.g. GCF_000001405.40)
        currentAccession:
          type: string
        submitter:
          type: string
        organism:
          type: object
          properties:
            taxId:
              type: integer
            sciName:
              type: string
            commonName:
              type: string
        assemblyInfo:
          type: object
          properties:
            assemblyLevel:
              type: string
            assemblyStatus:
              type: string
            assemblyName:
              type: string
            submissionDate:
              type: string
              format: date
            releaseDate:
              type: string
              format: date
        assemblyStats:
          type: object
          properties:
            totalLength:
              type: integer
            numberOfChromosomes:
              type: integer
            contigN50:
              type: integer
            scaffoldN50:
              type: integer
            gcCount:
              type: integer
            gcPercent:
              type: number
    GenomeDatasetReport:
      type: object
      description: Genome assembly dataset report
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/GenomeAssembly'
        totalCount:
          type: integer
        nextPageToken:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key