United States National Library of Medicine BLAST API

openapi: 3.0.3
info:
  title: NCBI URL BLAST API
  description: 'The NCBI BLAST URL API allows developers to submit BLAST (Basic Local Alignment Search Tool) sequence searches for processing at NCBI using HTTPS. The API operates in three phases: (1) PUT request to submit a search and receive a request ID (RID), (2) polling GET requests to check search status, (3) GET request to retrieve results in the desired format. Supports nucleotide (blastn, blastx) and protein (blastp, tblastn, tblastx) searches.'
  version: 1.0.0
  contact:
    name: NCBI BLAST
    url: https://blast.ncbi.nlm.nih.gov/doc/blast-help/developerinfo.html
  license:
    name: Public Domain
    url: https://www.usa.gov/government-works
servers:
- url: https://blast.ncbi.nlm.nih.gov/blast
  description: NCBI BLAST Server
tags:
- name: BLAST
  description: BLAST sequence search submission and retrieval
paths:
  /Blast.cgi:
    put:
      operationId: submitBlastSearch
      summary: Submit BLAST Search
      description: Submit a BLAST sequence search and receive a Request ID (RID) for status checking and result retrieval. Include CMD=Put and required parameters in the request body.
      tags:
      - BLAST
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - CMD
              - PROGRAM
              - DATABASE
              - QUERY
              properties:
                CMD:
                  type: string
                  enum:
                  - Put
                  description: Command type
                PROGRAM:
                  type: string
                  description: BLAST program to use
                  enum:
                  - blastn
                  - blastp
                  - blastx
                  - tblastn
                  - tblastx
                DATABASE:
                  type: string
                  description: Target sequence database
                  example: nt
                QUERY:
                  type: string
                  description: Query sequence in FASTA format or accession number
                FORMAT_TYPE:
                  type: string
                  description: Output format type
                  enum:
                  - XML
                  - XML2
                  - JSON2
                  - Tabular
                  - Text
                HITLIST_SIZE:
                  type: integer
                  description: Number of hits to return
                  default: 100
                EXPECT:
                  type: number
                  description: E-value threshold
                  default: 10
                WORD_SIZE:
                  type: integer
                  description: Word size for initial match
                FILTER:
                  type: string
                  description: Low complexity filter (T or F)
      responses:
        '200':
          description: HTML page containing RID and RTOE values
          content:
            text/html:
              schema:
                type: string
    get:
      operationId: getBlastResults
      summary: Get BLAST Results or Status
      description: Check the status of a BLAST search or retrieve results using the Request ID (RID). Use CMD=Get with the RID to check status or retrieve results. Format_Type parameter controls output format for results.
      tags:
      - BLAST
      parameters:
      - name: CMD
        in: query
        description: Command type (Get to check status/retrieve results)
        required: true
        schema:
          type: string
          enum:
          - Get
          - Wait
          - Delete
        example: Get
      - name: RID
        in: query
        description: Request ID from submission response
        required: true
        schema:
          type: string
        example: A1B2C3D4E5F
      - name: FORMAT_TYPE
        in: query
        description: Output format for results
        required: false
        schema:
          type: string
          enum:
          - XML
          - XML2
          - JSON2
          - Tabular
          - Text
          - HTML
          default: JSON2
      - name: HITLIST_SIZE
        in: query
        description: Number of hits to retrieve in results
        required: false
        schema:
          type: integer
          default: 100
      responses:
        '200':
          description: BLAST search status or results
          content:
            application/json:
              schema:
                type: object
            text/xml:
              schema:
                type: string
            text/plain:
              schema:
                type: string