openapi: 3.2.0
info:
  title: NCBI E-Utilities Search API
  description: The NCBI E-Utilities (Entrez Programming Utilities) are the public API to the NCBI Entrez system providing access to all 41 Entrez databases including PubMed (biomedical literature), PMC (full-text articles), Gene, Nuccore (nucleotide sequences), Protein, SNP, and more. Supports search, retrieval, linking, posting, and spelling operations. API keys from https://www.ncbi.nlm.nih.gov/account/ increase the rate limit from 3 to 10 requests per second.
  version: 1.0.0
  contact:
    name: NCBI
    url: https://www.ncbi.nlm.nih.gov/home/develop/api/
    email: info@ncbi.nlm.nih.gov
  license:
    name: Public Domain
    url: https://www.usa.gov/government-works
servers:
- url: https://eutils.ncbi.nlm.nih.gov/entrez/eutils
  description: NCBI E-Utilities API
tags:
- name: Search
  description: Search Entrez databases
paths:
  /esearch.fcgi:
    get:
      operationId: searchDatabase
      summary: Search Entrez Database
      description: Search any Entrez database and retrieve document identifiers (UIDs) matching a query. Supports full Entrez query syntax including Boolean operators, field tags, and date ranges.
      tags:
      - Search
      parameters:
      - name: db
        in: query
        description: Target Entrez database (e.g. pubmed, nuccore, protein, gene, snp, mesh, pmc)
        required: true
        schema:
          type: string
        example: pubmed
      - name: term
        in: query
        description: Entrez text query with optional field tags and Boolean operators
        required: true
        schema:
          type: string
        example: cancer[Title] AND 2023[PDAT]
      - name: api_key
        in: query
        description: NCBI API key for increased rate limits
        required: false
        schema:
          type: string
      - name: retmax
        in: query
        description: Maximum number of UIDs to return (default 20, max 10000)
        required: false
        schema:
          type: integer
          default: 20
          maximum: 10000
      - name: retstart
        in: query
        description: Index of first UID in results (for pagination)
        required: false
        schema:
          type: integer
          default: 0
      - name: retmode
        in: query
        description: Output format
        required: false
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
      - name: sort
        in: query
        description: Sort order for results
        required: false
        schema:
          type: string
          enum:
          - relevance
          - pub+date
          - Author
          - JournalName
      - name: datetype
        in: query
        description: Date type for date range filtering
        required: false
        schema:
          type: string
          enum:
          - PDAT
          - MDAT
          - EDAT
      - name: mindate
        in: query
        description: Minimum date for range filter (YYYY/MM/DD)
        required: false
        schema:
          type: string
        example: 2023/01/01
      - name: maxdate
        in: query
        description: Maximum date for range filter (YYYY/MM/DD)
        required: false
        schema:
          type: string
        example: 2023/12/31
      - name: usehistory
        in: query
        description: Store results on NCBI server (y/n)
        required: false
        schema:
          type: string
          enum:
          - y
          - n
      responses:
        '200':
          description: Search results with UIDs and counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ESearchResult'
  /espell.fcgi:
    get:
      operationId: checkSpelling
      summary: Check Query Spelling
      description: Retrieve spelling suggestions for a search term in a given Entrez database. Helpful for correcting misspelled gene names, species names, or medical terms.
      tags:
      - Search
      parameters:
      - name: db
        in: query
        description: Target Entrez database
        required: true
        schema:
          type: string
        example: pubmed
      - name: term
        in: query
        description: Query term to check spelling for
        required: true
        schema:
          type: string
        example: asthmaa
      - name: api_key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Spelling suggestions
          content:
            text/xml:
              schema:
                type: string
components:
  schemas:
    ESearchResult:
      type: object
      description: Results from an Entrez search query
      properties:
        esearchresult:
          type: object
          properties:
            count:
              type: string
              description: Total number of matching records
            retmax:
              type: string
              description: Number of UIDs returned
            retstart:
              type: string
              description: Index of first UID returned
            querykey:
              type: string
              description: Server-side query key (if usehistory=y)
            webenv:
              type: string
              description: Web environment token (if usehistory=y)
            idlist:
              type: array
              description: List of returned UIDs
              items:
                type: string
            translationset:
              type: array
              description: Query translations applied
              items:
                type: object
            querytranslation:
              type: string
              description: Translated query as used by Entrez
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: NCBI API key from https://www.ncbi.nlm.nih.gov/account/