openapi: 3.2.0
info:
  title: STRING REST Homology API
  description: 'STRING is a protein-protein interaction network database providing scored associations between proteins across thousands of organisms. The REST API enables programmatic access to interaction scores, network visualizations, functional enrichment analysis, homology data, and protein annotations. STRING integrates data from genomic context, co-expression, text mining, biochemical and genetic experiments, and curated databases.

    '
  version: '12.0'
  contact:
    name: STRING Consortium
    url: https://string-db.org
  license:
    name: Creative Commons Attribution
    url: https://string-db.org/cgi/access?footer_active_subpage=licensing
  termsOfService: https://string-db.org/cgi/info?footer_active_subpage=cookies
servers:
- url: https://string-db.org
  description: STRING Production Server
security: []
tags:
- name: homology
  description: Protein homology and similarity scores
paths:
  /api/{format}/homology:
    get:
      operationId: getHomology
      summary: Homology
      description: 'Return Smith-Waterman bit scores between all pairs of proteins in the input set.

        '
      tags:
      - homology
      parameters:
      - $ref: '#/components/parameters/format'
      - name: identifiers
        in: query
        required: true
        description: Protein identifiers, newline-separated (%0d in URL)
        schema:
          type: string
      - $ref: '#/components/parameters/species'
      - $ref: '#/components/parameters/caller_identity'
      responses:
        '200':
          description: Homology scores
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TsvResponse'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HomologyResult'
        '400':
          $ref: '#/components/responses/BadRequest'
  /api/{format}/homology_best:
    get:
      operationId: getHomologyBest
      summary: Best Homology
      description: 'Return the best cross-species homology hits for input proteins. Useful for finding orthologs across species.

        '
      tags:
      - homology
      parameters:
      - $ref: '#/components/parameters/format'
      - name: identifiers
        in: query
        required: true
        description: Protein identifiers (source species), newline-separated (%0d in URL)
        schema:
          type: string
      - $ref: '#/components/parameters/species'
      - name: species_b
        in: query
        required: false
        description: 'NCBI taxon ID for the target species (default: all species)'
        schema:
          type: integer
          example: 10090
      - $ref: '#/components/parameters/caller_identity'
      responses:
        '200':
          description: Best homology hits across species
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TsvResponse'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HomologyBestResult'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  responses:
    BadRequest:
      description: Bad request (invalid parameters)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        text/plain:
          schema:
            type: string
  parameters:
    caller_identity:
      name: caller_identity
      in: query
      required: false
      description: 'A string identifying your application or organization. Strongly recommended; helps STRING admins contact you if there are issues.

        '
      schema:
        type: string
        example: my_bioinformatics_pipeline
    format:
      name: format
      in: path
      required: true
      description: Output format
      schema:
        type: string
        enum:
        - tsv
        - tsv-no-header
        - json
        - xml
        example: json
    species:
      name: species
      in: query
      required: false
      description: 'NCBI taxon ID to restrict results to a specific organism. Common values: 9606 (human), 10090 (mouse), 10116 (rat), 7227 (D. melanogaster), 6239 (C. elegans), 4932 (S. cerevisiae), 3702 (A. thaliana), 7955 (zebrafish).

        '
      schema:
        type: integer
        example: 9606
  schemas:
    HomologyResult:
      type: object
      description: Smith-Waterman homology score between two proteins
      properties:
        stringId_A:
          type: string
          description: STRING identifier for protein A
        stringId_B:
          type: string
          description: STRING identifier for protein B
        bitscore:
          type: number
          description: Smith-Waterman bit score
        identity:
          type: number
          description: Sequence identity (0-100%)
    TsvResponse:
      type: string
      description: Tab-separated values response with header row
    HomologyBestResult:
      type: object
      description: Best cross-species homology hit
      properties:
        stringId:
          type: string
          description: Source protein STRING identifier
        ncbiTaxonId_A:
          type: integer
          description: Source species NCBI taxon ID
        ncbiTaxonId_B:
          type: integer
          description: Target species NCBI taxon ID
        stringId_B:
          type: string
          description: Target protein STRING identifier
        bitscore:
          type: number
          description: Smith-Waterman bit score of the best hit
        identity:
          type: number
          description: Sequence identity percentage
    Error:
      type: object
      properties:
        status:
          type: integer
        error:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: 'API key required only for Values/Ranks Enrichment endpoints. Obtain via POST /api/json/get_api_key. All other endpoints are publicly accessible without authentication.

        '
externalDocs:
  description: STRING API Documentation
  url: https://string-db.org/help/api/