Clarivate Searches API

openapi: 3.2.0
info:
  title: Derwent Sequence Search Searches API
  version: V1@2026-06-09
  description: OpenAPI Docs & Interactive UI
  license:
    name: Commercially Licensed Product
    url: https://clarivate.com/derwent/solutions/derwent-sequence-base/
servers:
- url: https://api.clarivate.com/derwent-sequence-search
security:
- key: []
tags:
- name: Searches
  description: Searches management endpoints
paths:
  /reports/{report_id}/searches:
    parameters:
    - name: report_id
      in: path
      description: Report ID
      required: true
      schema:
        type: integer
    get:
      summary: List searches
      tags:
      - Searches
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 1
        description: Page number for pagination
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 25
        description: Number of items per page
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                    - id: '8'
                      type: search
                      attributes:
                        id: 8
                        program: blastn
                        title: Voluptas vel officia.
                        status: queued
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:50Z'
                        started_at: '2026-06-09T06:48:50Z'
                        completed_at: '2026-06-09T06:49:50Z'
                    - id: '9'
                      type: search
                      attributes:
                        id: 9
                        program: swn
                        title: Quo libero necessitatibus.
                        status: running
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:50Z'
                        started_at: '2026-06-09T06:48:50Z'
                        completed_at: '2026-06-09T06:49:50Z'
                    - id: '10'
                      type: search
                      attributes:
                        id: 10
                        program: motifn
                        title: Numquam facilis dolorum et et quasi.
                        status: completed
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:50Z'
                        started_at: '2026-06-09T06:48:50Z'
                        completed_at: '2026-06-09T06:49:50Z'
                    meta:
                      total: 3
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v1/reports/53/searches?limit=25&page=1
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Search'
                  meta:
                    $ref: '#/components/schemas/JsonApiPaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                required:
                - data
                - meta
                - links
      operationId: getReportsByReportIdSearches
      x-operation-id-source: derived
    post:
      summary: Create search
      tags:
      - Searches
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              examples:
                created:
                  value:
                    data:
                    - id: '14'
                      type: search
                      attributes:
                        id: 14
                        program: swn
                        title: Specific program search
                        status: queued
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:50Z'
                        started_at: null
                        completed_at: null
                  summary: Successful search creation
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Search'
                required:
                - data
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                bad_request:
                  value:
                    errors:
                    - status: '400'
                      detail: Program 'invalid_program' is not supported.
                  summary: Bad Request
              schema:
                $ref: '#/components/schemas/errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                unprocessable_entity:
                  value:
                    errors:
                    - status: '422'
                      title: Invalid Attribute
                      detail: 'Search name can''t be blank '
                    - status: '422'
                      title: Invalid Attribute
                      detail: 'Query coverage is not a number '
                  summary: Unprocessable Entity
              schema:
                $ref: '#/components/schemas/errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCreateParams'
            examples:
              single_query_blast:
                summary: Single query — BLAST
                value:
                  search:
                    title: Single query BLAST search
                    query: CGCGGTCGGGTCGTG
                    program: blastn
              single_query_sw:
                summary: Single query — Smith-Waterman with databases
                value:
                  search:
                    title: Single query Smith-Waterman search
                    query: CGCGGTCGGGTCGTG
                    program: swn
                    databases:
                    - usgene_patents
                    - geneseq
              multi_sequence:
                summary: Multi-sequence (MSS) search
                value:
                  search:
                    title: Multi-sequence search
                    queries:
                    - '>seq1

                      CGCGGTCGGGTCGTG'
                    - '>seq2

                      ATGCATGCATGCATGC'
                    mss: true
                    program: swn
              with_advanced_options:
                summary: Single query with search & program options
                value:
                  search:
                    title: Search with advanced options
                    query: CGCGGTCGGGTCGTG
                    program: blastn
                    databases:
                    - usgene_patents
                    - usgene_applications
                    - geneseq
                    - fastalert
                    search_options:
                      query_coverage_threshold: 80
                      identities_percent_threshold: 90
                      exclude_mega_patents: true
                    program_options:
                      evalue: 0.001
                      max_target_seqs: 500
                      word_size: 11
              cdr_search:
                summary: Antibody / CDR Search
                value:
                  search:
                    title: Antibody (CDR) search example
                    program: cdrn
                    queries:
                    - TGGACGTGG
                    - TGTGCAGAA
                    - TGGATGGGA
                    - TGTGTTTGG
                    - TGGGGAGGG
                    - TGTGCTGGG
                    - ATGGGATGGGGAGGG
                    - ATGTGTTTGTGCTGG
                    search_options:
                      cdr_mismatches:
                      - 1
                      - 1
                      - 1
                      - 1
                      - 1
                      - 1
                      heavy_chain_identity: 90
                      light_chain_identity: 90
              keyword_search:
                summary: Keyword (FTS) Search
                value:
                  search:
                    title: Keyword search example
                    program: keyword
                    databases:
                    - usgene_patents
                    program_options:
                      sequences_type: protein
                      max_documents_per_source: 100
                    query_builder:
                      patents:
                        '0':
                          keyword: ALL
                          boolean_operator: AND
                          value: Homo sapiens
                          position: '0'
              modification_search:
                summary: Sequence Modification Search
                value:
                  search:
                    title: Modification search example
                    program: modification
                    query: CGCGGTCGGGTCGTG
                    databases:
                    - usgene_patents
                    program_options:
                      program: modificationn
                    seqmod_query_builder:
                      default:
                        '0':
                          keyword: MT
                          boolean_operator: AND
                          value: substitution
                          position: '0'
        required: true
      operationId: postReportsByReportIdSearches
      x-operation-id-source: derived
  /reports/{report_id}/searches/{id}:
    parameters:
    - name: report_id
      in: path
      description: Report ID
      required: true
      schema:
        type: integer
    - name: id
      in: path
      description: Search ID
      required: true
      schema:
        type: string
    get:
      summary: Show search
      tags:
      - Searches
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                      id: '64'
                      type: search
                      attributes:
                        id: 64
                        program: blastn
                        title: Facere minus eos voluptatem.
                        status: queued
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:51Z'
                        started_at: '2026-06-09T06:48:51Z'
                        completed_at: '2026-06-09T06:49:51Z'
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Search'
                required:
                - data
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
      operationId: getReportsByReportIdSearchesById
      x-operation-id-source: derived
    patch:
      summary: Update search
      tags:
      - Searches
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                      id: '70'
                      type: search
                      attributes:
                        id: 70
                        program: blastn
                        title: Updated Search Title
                        status: queued
                        completion: 0
                        search_results_count: 0
                        redundant_search_results_count: 0
                        created_at: '2026-06-09T06:50:51Z'
                        started_at: '2026-06-09T06:48:51Z'
                        completed_at: '2026-06-09T06:49:51Z'
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Search'
                required:
                - data
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchUpdateParams'
        required: true
      operationId: patchReportsByReportIdSearchesById
      x-operation-id-source: derived
    delete:
      summary: Delete search
      tags:
      - Searches
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                      type: search
                      id: '78'
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - id
                    - type
                    properties:
                      id:
                        type: string
                      type:
                        type: string
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
      operationId: deleteReportsByReportIdSearchesById
      x-operation-id-source: derived
  /reports/{report_id}/searches/destroy_bulk:
    parameters:
    - name: report_id
      in: path
      description: Report ID
      required: true
      schema:
        type: integer
    delete:
      summary: Destroy bulk searches
      tags:
      - Searches
      parameters:
      - name: ids[]
        description: Search IDs
        in: query
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: true
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                    - type: search
                      id: '84'
                    - type: search
                      id: '82'
                    - type: search
                      id: '83'
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - type
                      properties:
                        id:
                          type: string
                        type:
                          type: string
      operationId: deleteReportsByReportIdSearchesDestroyBulk
      x-operation-id-source: derived
components:
  schemas:
    SearchCreateSingleQueryParams:
      type: object
      required:
      - search
      properties:
        search:
          type: object
          required:
          - program
          - query
          properties:
            title:
              type: string
              maxLength: 255
              description: Search title
            program:
              type: string
              enum:
              - blastn
              - blastp
              - blastx
              - tblastn
              - tblastx
              - swn
              - swp
              - cdrn
              - cdrp
              - motifn
              - motifp
              - bestseqn
              - bestseqp
              - keyword
              - modification
              - modificationn
              - modificationp
              example: blastn
              description: Search algorithm
            databases:
              type: array
              items:
                type: string
                enum:
                - usgene_patents
                - usgene_applications
                - geneseq
                - fastalert
                - wogene
                - genbank
                - genbank_pat
              description: Convenience shorthand for enabling specific databases (maps to search_options)
            exclude_geneseq_from:
              type: array
              items:
                type: string
                enum:
                - usgene
                - wogene
              description: Exclude GeneSeq documents from specified databases
            search_options:
              type: object
              description: Search-level options (thresholds, database toggles, date filters, etc.)
              properties:
                query_coverage_threshold:
                  type: number
                  description: Minimum query coverage (%)
                identities_percent_threshold:
                  type: number
                  description: Minimum identity (%)
                auto_params_for_short_sequences:
                  type: boolean
                  description: Auto-tune parameters for short sequences (blastn/blastp)
                search_usgene_patents:
                  type: boolean
                search_usgene_applications:
                  type: boolean
                search_geneseq:
                  type: boolean
                search_fastalert:
                  type: boolean
                search_wipo:
                  type: boolean
                search_genbank:
                  type: boolean
                search_genbank_pat:
                  type: boolean
                exclude_geneseq_documents_from_usgene:
                  type: boolean
                exclude_geneseq_documents_from_wipo:
                  type: boolean
                exclude_mega_patents:
                  type: boolean
                exclude_non_published_applications:
                  type: boolean
                patent_priority_date_from:
                  type: string
                  description: Filter by patent priority date (start)
                patent_priority_date_to:
                  type: string
                  description: Filter by patent priority date (end)
                patent_application_date_from:
                  type: string
                  description: Filter by patent application date (start)
                patent_application_date_to:
                  type: string
                  description: Filter by patent application date (end)
                patent_publication_date_from:
                  type: string
                  description: Filter by patent publication date (start)
                patent_publication_date_to:
                  type: string
                  description: Filter by patent publication date (end)
                cdr_mismatches:
                  type: array
                  items:
                    type: integer
                  description: Mismatch counts allowed per CDR region (heavy/light chains)
                heavy_chain_identity:
                  type: number
                  description: Heavy chain identity threshold (%)
                light_chain_identity:
                  type: number
                  description: Light chain identity threshold (%)
                individual_identities:
                  type: boolean
                  description: Whether to evaluate individual identities (MSS)
                individual_coverage:
                  type: boolean
                  description: Whether to evaluate individual query coverages (MSS)
            program_options:
              type: object
              description: Program-specific options (varies by program). Common options include evalue, gapopen, gapextend, max_target_seqs, word_size, strand, matrix, etc.
              properties:
                evalue:
                  type: number
                  description: Expectation value threshold (BLAST programs)
                gapopen:
                  type: integer
                  description: Gap opening penalty (BLAST programs)
                gapextend:
                  type: integer
                  description: Gap extension penalty (BLAST programs)
                max_target_seqs:
                  type: integer
                  minimum: 1
                  description: Max target sequences (BLAST programs)
                word_size:
                  type: integer
                  description: Word size for initial match
                strand:
                  type: string
                  enum:
                  - both
                  - minus
                  - plus
                  description: Query strand (nucleotide programs)
                matrix:
                  type: string
                  description: 'Scoring matrix (protein programs: PAM30, PAM70, BLOSUM45, BLOSUM62, BLOSUM80)'
                task:
                  type: string
                  description: BLAST sub-task (e.g. blastn, megablast)
                subject_length_min:
                  type: integer
                  minimum: 1
                  maximum: 100000
                  description: Minimum subject length
                subject_length_max:
                  type: integer
                  minimum: 1
                  maximum: 100000
                  description: Maximum subject length
                ungapped:
                  type: boolean
                  description: Perform ungapped alignment (BLAST programs)
                mat:
                  type: string
                  description: 'Scoring matrix (SW programs: DNA, NUC.4.4)'
                gapo:
                  type: integer
                  description: Gap opening penalty (SW programs)
                gape:
                  type: integer
                  description: Gap extension penalty (SW programs)
                min_score:
                  type: integer
                  minimum: 1
                  description: Minimum alignment score (SW programs)
                topscore_num:
                  type: integer
                  minimum: 1
                  description: Number of top scoring sequences (SW programs)
                reverse:
                  type: boolean
                  description: Search reverse complement (SW nucleotide)
                sequences_type:
                  type: string
                  enum:
                  - protein
                  - nucleotide
                  description: Sequences type for keyword/FTS search
                max_documents_per_source:
                  type: integer
                  description: FTS limit on documents per database source
            query_builder:
              type: object
              description: Advanced query builder filters for refining search scope
            seqmod_query_builder:
              type: object
              description: Sequence modification query builder configuration (type, position, name)
            monitor_options:
              type: object
              description: Search monitoring configuration for recurring searches
            query:
              type: string
              example: CGCGGTCGGGTCGTG
              description: Single sequence query string
    SearchAttributes:
      type: object
      required:
      - id
      - program
      - title
      - status
      - completion
      - search_results_count
      - redundant_search_results_count
      - created_at
      properties:
        id:
          type: integer
        program:
          type: string
        title:
          type: string
        status:
          type: string
        completion:
          type: integer
        search_results_count:
          type: integer
        redundant_search_results_count:
          type: integer
        created_at:
          type: string
          format: date-time
        started_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        completed_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
    Search:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the Search.
          example: '1'
        type:
          type: string
          description: Resource type.
          enum:
          - search
        attributes:
          $ref: '#/components/schemas/SearchAttributes'
      required:
      - id
      - type
      - attributes
    errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    SearchCreateMultiSequenceParams:
      type: object
      required:
      - search
      properties:
        search:
          type: object
          required:
          - program
          - queries
          - mss
          properties:
            title:
              type: string
              maxLength: 255
              description: Search title
            program:
              type: string
              enum:
              - blastn
              - blastp
              - blastx
              - tblastn
              - tblastx
              - swn
              - swp
              - cdrn
              - cdrp
              - motifn
              - motifp
              - bestseqn
              - bestseqp
              - keyword
              - modification
              - modificationn
              - modificationp
              example: blastn
              description: Search algorithm
            databases:
              type: array
              items:
                type: string
                enum:
                - usgene_patents
                - usgene_applications
                - geneseq
                - fastalert
                - wogene
                - genbank
                - genbank_pat
              description: Convenience shorthand for enabling specific databases (maps to search_options)
            exclude_geneseq_from:
              type: array
              items:
                type: string
                enum:
                - usgene
                - wogene
              description: Exclude GeneSeq documents from specified databases
            search_options:
              type: object
              description: Search-level options (thresholds, database toggles, date filters, etc.)
              properties:
                query_coverage_threshold:
                  type: number
                  description: Minimum query coverage (%)
                identities_percent_threshold:
                  type: number
                  description: Minimum identity (%)
                auto_params_for_short_sequences:
                  type: boolean
                  description: Auto-tune parameters for short sequences (blastn/blastp)
                search_usgene_patents:
                  type: boolean
                search_usgene_applications:
                  type: boolean
                search_geneseq:
                  type: boolean
                search_fastalert:
                  type: boolean
                search_wipo:
                  type: boolean
                search_genbank:
                  type: boolean
                search_genbank_pat:
                  type: boolean
                exclude_geneseq_documents_from_usgene:
                  type: boolean
                exclude_geneseq_documents_from_wipo:
                  type: boolean
                exclude_mega_patents:
                  type: boolean
                exclude_non_published_applications:
                  type: boolean
                patent_priority_date_from:
                  type: string
                  description: Filter by patent priority date (start)
                patent_priority_date_to:
                  type: string
                  description: Filter by patent priority date (end)
                patent_application_date_from:
                  type: string
                  description: Filter by patent application date (start)
                patent_application_date_to:
                  type: string
                  description: Filter by patent application date (end)
                patent_publication_date_from:
                  type: string
                  description: Filter by patent publication date (start)
                patent_publication_date_to:
                  type: string
                  description: Filter by patent publication date (end)
                cdr_mismatches:
                  type: array
                  items:
                    type: integer
                  description: Mismatch counts allowed per CDR region (heavy/light chains)
                heavy_chain_identity:
                  type: number
                  description: Heavy chain identity threshold (%)
                light_chain_identity:
                  type: number
                  description: Light chain identity threshold (%)
                individual_identities:
                  type: boolean
                  description: Whether to evaluate individual identities (MSS)
                individual_coverage:
                  type: boolean
                  description: Whether to evaluate individual query coverages (MSS)
            program_options:
              type: object
              description: Program-specific options (varies by program). Common options include evalue, gapopen, gapextend, max_target_seqs, word_size, strand, matrix, etc.
              properties:
                evalue:
                  type: number
                  description: Expectation value threshold (BLAST programs)
                gapopen:
                  type: integer
                  description: Gap opening penalty (BLAST programs)
                gapextend:
                  type: integer
                  description: Gap extension penalty (BLAST programs)
                max_target_seqs:
                  type: integer
                  minimum: 1
                  description: Max target sequences (BLAST programs)
                word_size:
                  type: integer
                  description: Word size for initial match
                strand:
                  type: string
                  enum:
                  - both
                  - minus
                  - plus
                  description: Query strand (nucleotide programs)
                matrix:
                  type: string
                  description: 'Scoring matrix (protein programs: PAM30, PAM70, BLOSUM45, BLOSUM62, BLOSUM80)'
                task:
                  type: string
                  description: BLAST sub-task (e.g. blastn, megablast)
                subject_length_min:
                  type: integer
                  minimum: 1
                  maximum: 100000
                  description: Minimum subject length
                subject_length_max:
                  type: integer
                  minimum: 1
                  maximum: 100000
                  description: Maximum subject length
                ungapped:
                  type: boolean
                  description: Perform ungapped alignment (BLAST programs)
                mat:
                  type: string
                  description: 'Scoring matrix (SW programs: DNA, NUC.4.4)'
                gapo:
                  type: integer
                  description: Gap

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clarivate/refs/heads/main/openapi/clarivate-searches-api-openapi.yml