openapi: 3.0.3
info:
  title: NCBI E-utilities API
  description: >-
    The Entrez Programming Utilities (E-utilities) are a public API to the NCBI
    Entrez system, providing access to all Entrez databases including PubMed,
    PMC, Gene, Nuccore, and Protein. The E-utilities are a suite of nine
    server-side programs that accept a fixed URL syntax for search, link, and
    retrieval operations. Maintained by the National Center for Biotechnology
    Information (NCBI), part of the U.S. National Library of Medicine.
  version: '1.0'
  contact:
    name: NCBI Information Engineering Branch
    url: https://www.ncbi.nlm.nih.gov/home/about/contact/
    email: eutilities@ncbi.nlm.nih.gov
  license:
    name: NCBI Public Domain
    url: https://www.ncbi.nlm.nih.gov/home/about/policies/
servers:
  - url: https://eutils.ncbi.nlm.nih.gov/entrez/eutils
    description: NCBI E-utilities production server
tags:
  - name: Search
    description: Search Entrez databases for matching records.
  - name: Retrieve
    description: Retrieve full or summary records from Entrez databases.
  - name: Discovery
    description: Discover database metadata, related records, and citations.
  - name: History
    description: Manage server-side history sets via the Entrez History server.
paths:
  /esearch.fcgi:
    get:
      tags:
        - Search
      summary: Search a database
      description: >-
        Returns a list of UIDs matching a text query, optionally posting the
        results to the Entrez History server for downstream operations.
      operationId: eSearch
      parameters:
        - name: db
          in: query
          required: true
          description: Database to search (e.g. pubmed, pmc, gene, protein, nuccore).
          schema:
            type: string
            default: pubmed
        - name: term
          in: query
          required: true
          description: Entrez text query, URL-encoded.
          schema:
            type: string
        - name: usehistory
          in: query
          description: Set to 'y' to post UIDs to the History server.
          schema:
            type: string
            enum: [y, n]
        - name: retmax
          in: query
          description: Maximum number of UIDs to return (default 20, max 10000).
          schema:
            type: integer
        - name: retstart
          in: query
          description: Sequential index of the first UID to return (zero-based).
          schema:
            type: integer
        - name: retmode
          in: query
          description: Output format.
          schema:
            type: string
            enum: [xml, json]
        - name: api_key
          in: query
          description: NCBI API key for higher rate limits.
          schema:
            type: string
      responses:
        '200':
          description: Successful search response with UID list.
  /efetch.fcgi:
    get:
      tags:
        - Retrieve
      summary: Fetch full records by UID
      description: Returns formatted data records for a list of UIDs.
      operationId: eFetch
      parameters:
        - name: db
          in: query
          required: true
          schema:
            type: string
        - name: id
          in: query
          required: true
          description: Comma-separated list of UIDs or a WebEnv/query_key reference.
          schema:
            type: string
        - name: rettype
          in: query
          description: Retrieval type (e.g. abstract, fasta, gb, medline).
          schema:
            type: string
        - name: retmode
          in: query
          description: Retrieval mode (e.g. xml, text, json, asn.1).
          schema:
            type: string
        - name: api_key
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Records returned in the requested rettype/retmode.
  /esummary.fcgi:
    get:
      tags:
        - Retrieve
      summary: Retrieve document summaries
      description: Returns document summaries for a list of input UIDs.
      operationId: eSummary
      parameters:
        - name: db
          in: query
          required: true
          schema:
            type: string
        - name: id
          in: query
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: Set to '2.0' for the newer DocSum schema.
          schema:
            type: string
        - name: retmode
          in: query
          schema:
            type: string
            enum: [xml, json]
      responses:
        '200':
          description: Document summaries.
  /einfo.fcgi:
    get:
      tags:
        - Discovery
      summary: Database statistics and field metadata
      description: Returns the list of all valid Entrez databases or, when 'db' is supplied, statistics and indexing fields for that database.
      operationId: eInfo
      parameters:
        - name: db
          in: query
          schema:
            type: string
        - name: retmode
          in: query
          schema:
            type: string
            enum: [xml, json]
      responses:
        '200':
          description: Database information.
  /elink.fcgi:
    get:
      tags:
        - Discovery
      summary: Find related records across Entrez databases
      description: Returns UIDs in a destination database linked to UIDs in a source database, including computed neighbors and external LinkOut links.
      operationId: eLink
      parameters:
        - name: dbfrom
          in: query
          required: true
          schema:
            type: string
        - name: db
          in: query
          schema:
            type: string
        - name: id
          in: query
          required: true
          schema:
            type: string
        - name: linkname
          in: query
          schema:
            type: string
        - name: cmd
          in: query
          description: Command mode (neighbor, neighbor_history, llinks, prlinks, etc.).
          schema:
            type: string
      responses:
        '200':
          description: Linked UIDs and metadata.
  /epost.fcgi:
    post:
      tags:
        - History
      summary: Post UIDs to the Entrez History server
      description: Uploads a list of UIDs and returns a WebEnv and query_key for downstream calls.
      operationId: ePost
      parameters:
        - name: db
          in: query
          required: true
          schema:
            type: string
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: WebEnv and query_key for the posted set.
  /espell.fcgi:
    get:
      tags:
        - Discovery
      summary: Spelling suggestions for a query term
      description: Returns NCBI-suggested corrections for a misspelled query term.
      operationId: eSpell
      parameters:
        - name: db
          in: query
          required: true
          schema:
            type: string
        - name: term
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Suggested replacement terms.
  /ecitmatch.cgi:
    get:
      tags:
        - Discovery
      summary: Match citations to PubMed UIDs
      description: Resolves bibliographic citation strings to PubMed UIDs.
      operationId: eCitMatch
      parameters:
        - name: db
          in: query
          required: true
          schema:
            type: string
            enum: [pubmed]
        - name: rettype
          in: query
          schema:
            type: string
            enum: [xml]
        - name: bdata
          in: query
          required: true
          description: Pipe-delimited citation strings.
          schema:
            type: string
      responses:
        '200':
          description: Matched PMIDs.
  /egquery.fcgi:
    get:
      tags:
        - Search
      summary: Global cross-database query
      description: Returns the number of records in every Entrez database matching a single text query.
      operationId: eGQuery
      parameters:
        - name: term
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Per-database hit counts.