> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafflesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search for protein homology candidates in a batch

> Runs 1 to 16 ordered typed protein queries with shared search controls. The operation is bounded, synchronous, and all-or-nothing: it returns completed candidate sets in query order or one error for the complete batch.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/homology/batch
openapi: 3.1.0
info:
  description: >-
    Deterministic biological evidence primitives. Every response is the same
    envelope: ok, data, warnings, provenance.
  title: Rafflesia API
  version: 0.1.0
servers:
  - description: Production
    url: https://api.rafflesia.ai
security:
  - bearerAuth: []
paths:
  /v1/homology/batch:
    post:
      tags:
        - Homology
      summary: Search for protein homology candidates in a batch
      description: >-
        Runs 1 to 16 ordered typed protein queries with shared search controls.
        The operation is bounded, synchronous, and all-or-nothing: it returns
        completed candidate sets in query order or one error for the complete
        batch.
      operationId: homology_many
      parameters:
        - description: >-
            Optional retry identity for the complete all-or-nothing batch. Reuse
            the same key only with the same request. When omitted, each item in
            each HTTP request is a distinct billable operation.
          in: header
          name: Idempotency-Key
          schema:
            description: >-
              Optional retry identity for the complete all-or-nothing batch.
              Reuse the same key only with the same request. When omitted, each
              item in each HTTP request is a distinct billable operation.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HomologyBatchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyBatchSearchResponse'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            Rafflesia-API-Version:
              schema:
                type: string
            Rafflesia-Contract-Digest:
              schema:
                type: string
            Retry-After:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Too Many Requests
          headers:
            Retry-After:
              description: Whole seconds to wait before retrying this query.
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Service Unavailable
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomologyErrorResponse'
          description: Gateway Timeout
      x-codeSamples:
        - lang: bash
          source: |
            curl --request POST \
              --url "https://api.rafflesia.ai/v1/homology/batch" \
              --header "Authorization: Bearer $RAFFLESIA_API_KEY" \
              --header "Content-Type: application/json" \
              --data '{
                "queries": [
                  {
                    "kind": "protein_sequence",
                    "sequence": "<sequence>"
                  }
                ]
              }'
components:
  schemas:
    HomologyBatchRequest:
      additionalProperties: false
      allOf:
        - not:
            required:
              - database
              - database_release_id
            type: object
        - not:
            required:
              - target_space_id
              - database
            type: object
        - not:
            required:
              - target_space_id
              - database_release_id
            type: object
        - not:
            required:
              - target_space_id
              - filter
            type: object
      properties:
        database:
          description: >-
            Database id or slug from homology.databases.list. Omit both database
            selectors to use the server-advertised default database and its
            default release. Mutually exclusive with database_release_id.
          maxLength: 256
          minLength: 1
          type: string
        database_release_id:
          description: >-
            Exact immutable dbr_ release id returned by the catalog. Omit both
            database selectors to use the server-advertised default database and
            its default release. Mutually exclusive with database.
          pattern: ^dbr_[0-9a-f]{64}$
          type: string
        evidence:
          default: pairwise_sequence_alignment
          enum:
            - candidate_measurement
            - pairwise_sequence_alignment
          type: string
        filter:
          $ref: '#/components/schemas/HomologyDocumentFilter'
          description: >-
            Optional exact metadata predicate applied before the release-owned
            search policy.
        guarantee:
          default: approximate
          enum:
            - approximate
            - exhaustive
          type: string
        include_attributes:
          items:
            enum:
              - record_id
            type: string
          maxItems: 1
          type:
            - array
            - 'null'
          uniqueItems: true
        limit:
          default: 25
          description: Maximum ranked results returned for each query.
          format: int64
          maximum: 1000
          minimum: 1
          type: integer
        queries:
          description: >-
            An ordered batch of 1 to 16 typed biological queries sharing every
            search control.
          items:
            $ref: '#/components/schemas/HomologyQuery'
          maxItems: 16
          minItems: 1
          type: array
        significance:
          default: if_available
          enum:
            - not_requested
            - if_available
            - required
          type: string
        target_space_id:
          description: >-
            Immutable reusable target space shared by every query. Mutually
            exclusive with database, database_release_id, and filter.
          pattern: ^htsp_[0-9a-f]{64}$
          type: string
      required:
        - queries
      type: object
    HomologyBatchSearchResponse:
      $ref: '#/components/schemas/HomologyBatchResponse'
    HomologyErrorResponse:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/HomologyPublicError'
      required:
        - error
      type: object
    HomologyDocumentFilter:
      additionalProperties: false
      description: >-
        Recursive metadata predicate defining the eligible target population.
        Field/operator compatibility and limits come from the immutable filter
        schema for the selected release. Missing fields use strong Kleene logic;
        only true records are eligible.
      discriminator:
        mapping:
          and:
            $ref: '#/components/schemas/HomologyFilterAnd'
          contains:
            $ref: '#/components/schemas/HomologyFilterContains'
          contains_all:
            $ref: '#/components/schemas/HomologyFilterContainsAll'
          contains_any:
            $ref: '#/components/schemas/HomologyFilterContainsAny'
          eq:
            $ref: '#/components/schemas/HomologyFilterEq'
          exists:
            $ref: '#/components/schemas/HomologyFilterExists'
          gt:
            $ref: '#/components/schemas/HomologyFilterGt'
          gte:
            $ref: '#/components/schemas/HomologyFilterGte'
          in:
            $ref: '#/components/schemas/HomologyFilterIn'
          lt:
            $ref: '#/components/schemas/HomologyFilterLt'
          lte:
            $ref: '#/components/schemas/HomologyFilterLte'
          not:
            $ref: '#/components/schemas/HomologyFilterNot'
          or:
            $ref: '#/components/schemas/HomologyFilterOr'
        propertyName: op
      oneOf:
        - $ref: '#/components/schemas/HomologyFilterAnd'
        - $ref: '#/components/schemas/HomologyFilterOr'
        - $ref: '#/components/schemas/HomologyFilterNot'
        - $ref: '#/components/schemas/HomologyFilterEq'
        - $ref: '#/components/schemas/HomologyFilterIn'
        - $ref: '#/components/schemas/HomologyFilterLt'
        - $ref: '#/components/schemas/HomologyFilterLte'
        - $ref: '#/components/schemas/HomologyFilterGt'
        - $ref: '#/components/schemas/HomologyFilterGte'
        - $ref: '#/components/schemas/HomologyFilterContains'
        - $ref: '#/components/schemas/HomologyFilterContainsAny'
        - $ref: '#/components/schemas/HomologyFilterContainsAll'
        - $ref: '#/components/schemas/HomologyFilterExists'
      properties:
        field:
          maxLength: 256
          pattern: ^[a-z0-9_]+$
          type: string
        filter:
          $ref: '#/components/schemas/HomologyDocumentFilter'
        filters:
          items:
            $ref: '#/components/schemas/HomologyDocumentFilter'
          maxItems: 256
          minItems: 1
          type: array
        op:
          enum:
            - and
            - or
            - not
            - eq
            - in
            - lt
            - lte
            - gt
            - gte
            - contains
            - contains_any
            - contains_all
            - exists
          type: string
        value:
          oneOf:
            - maxLength: 16384
              type: string
            - type: integer
            - type: boolean
        values:
          items:
            oneOf:
              - maxLength: 16384
                type: string
              - type: integer
              - type: boolean
          maxItems: 4096
          minItems: 1
          type: array
      required:
        - op
      type: object
    HomologyQuery:
      discriminator:
        mapping:
          protein_sequence:
            $ref: '#/components/schemas/ProteinSequenceQuery'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/ProteinSequenceQuery'
    HomologyBatchResponse:
      additionalProperties: false
      properties:
        object:
          description: Always homology_search_result_set_batch.
          enum:
            - homology_search_result_set_batch
          type: string
        performance:
          $ref: '#/components/schemas/HomologyResponsePerformance'
        request_id:
          type: string
        responses:
          items:
            $ref: '#/components/schemas/HomologyBatchQueryResponse'
          maxItems: 16
          minItems: 1
          type: array
        result_sha256:
          type: string
        usage:
          $ref: '#/components/schemas/HomologyResponseUsage'
        warnings:
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - object
        - request_id
        - responses
        - result_sha256
        - usage
        - performance
        - warnings
      type: object
    HomologyPublicError:
      additionalProperties: false
      properties:
        code:
          type: string
        details:
          additionalProperties: {}
          type: object
        doc_url:
          type: string
        message:
          type: string
        param:
          type: string
        request_id:
          type: string
        type:
          enum:
            - invalid_request_error
            - resource_missing
            - resource_expired
            - conflict_error
            - rate_limit_error
            - authentication_error
            - permission_error
            - billing_error
            - api_error
          type: string
      required:
        - type
        - code
        - message
        - request_id
        - doc_url
      type: object
    HomologyFilterAnd:
      additionalProperties: false
      properties:
        filters:
          items:
            $ref: '#/components/schemas/HomologyDocumentFilter'
          maxItems: 256
          minItems: 1
          type: array
        op:
          enum:
            - and
          type: string
      required:
        - op
        - filters
      type: object
    HomologyFilterContains:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - contains
          type: string
        value:
          maxLength: 16384
          type: string
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterContainsAll:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - contains_all
          type: string
        values:
          items:
            maxLength: 16384
            type: string
          maxItems: 4096
          minItems: 1
          type: array
      required:
        - op
        - field
        - values
      type: object
    HomologyFilterContainsAny:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - contains_any
          type: string
        values:
          items:
            maxLength: 16384
            type: string
          maxItems: 4096
          minItems: 1
          type: array
      required:
        - op
        - field
        - values
      type: object
    HomologyFilterEq:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - eq
          type: string
        value:
          oneOf:
            - maxLength: 16382
              type: string
            - type: integer
            - type: boolean
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterExists:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - exists
          type: string
        value:
          type: boolean
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterGt:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - gt
          type: string
        value:
          type: integer
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterGte:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - gte
          type: string
        value:
          type: integer
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterIn:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - in
          type: string
        values:
          items:
            oneOf:
              - maxLength: 16382
                type: string
              - type: integer
              - type: boolean
          maxItems: 4096
          minItems: 1
          type: array
      required:
        - op
        - field
        - values
      type: object
    HomologyFilterLt:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - lt
          type: string
        value:
          type: integer
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterLte:
      additionalProperties: false
      properties:
        field:
          maxLength: 256
          not:
            enum:
              - id
          pattern: ^[a-z0-9_]+$
          type: string
        op:
          enum:
            - lte
          type: string
        value:
          type: integer
      required:
        - op
        - field
        - value
      type: object
    HomologyFilterNot:
      additionalProperties: false
      properties:
        filter:
          $ref: '#/components/schemas/HomologyDocumentFilter'
        op:
          enum:
            - not
          type: string
      required:
        - op
        - filter
      type: object
    HomologyFilterOr:
      additionalProperties: false
      properties:
        filters:
          items:
            $ref: '#/components/schemas/HomologyDocumentFilter'
          maxItems: 256
          minItems: 1
          type: array
        op:
          enum:
            - or
          type: string
      required:
        - op
        - filters
      type: object
    ProteinSequenceQuery:
      additionalProperties: false
      properties:
        kind:
          enum:
            - protein_sequence
          type: string
        sequence:
          description: >-
            Raw amino-acid sequence text. ASCII whitespace is ignored, letters
            are uppercased, and one trailing stop symbol is removed. The
            normalized sequence may contain at most 100,000 residues.
          maxLength: 110000
          minLength: 1
          type: string
      required:
        - kind
        - sequence
      type: object
    HomologyResponsePerformance:
      additionalProperties: false
      properties:
        is_cache_hit:
          description: >-
            Whether the completed scientific result was reused from a prior
            identical execution.
          type: boolean
        queue_wait_ms:
          description: Time spent waiting for execution capacity, in integer milliseconds.
          format: int64
          type: integer
        search_execution_ms:
          description: Time spent executing the resolved search, in integer milliseconds.
          format: int64
          type: integer
        server_total_ms:
          description: >-
            Total time spent serving the request, in integer milliseconds,
            including queueing.
          format: int64
          type: integer
      required:
        - server_total_ms
        - queue_wait_ms
        - search_execution_ms
        - is_cache_hit
      type: object
    HomologyBatchQueryResponse:
      additionalProperties: false
      properties:
        candidates:
          items:
            $ref: '#/components/schemas/HomologyResult'
          type: array
        database:
          $ref: '#/components/schemas/HomologyResponseDatabase'
        evidence_summary:
          $ref: '#/components/schemas/HomologyEvidenceSummary'
        execution:
          $ref: '#/components/schemas/HomologyResponseExecution'
        is_result_limit_reached:
          type: boolean
        object:
          description: Always homology_candidate_set.
          enum:
            - homology_candidate_set
          type: string
        query:
          $ref: '#/components/schemas/HomologyResponseQuery'
        query_index:
          format: int64
          minimum: 0
          type: integer
        ranking:
          $ref: '#/components/schemas/HomologyResponseRanking'
        receipt:
          $ref: '#/components/schemas/HomologyResponseReceipt'
        result_sha256:
          type: string
        usage:
          $ref: '#/components/schemas/HomologyResponseUsage'
        warnings:
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - object
        - query_index
        - query
        - database
        - execution
        - ranking
        - evidence_summary
        - receipt
        - candidates
        - is_result_limit_reached
        - result_sha256
        - usage
        - warnings
      type: object
    HomologyResponseUsage:
      additionalProperties: false
      properties:
        billable_formula_id:
          type: string
        billable_units:
          format: int64
          minimum: 0
          type: integer
        logical_bytes_read:
          format: int64
          minimum: 0
          type: integer
        logical_bytes_returned:
          format: int64
          minimum: 0
          type: integer
      required:
        - logical_bytes_returned
      type: object
    Warning:
      additionalProperties: false
      properties:
        code:
          description: Stable warning code.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured warning details.
          type: object
        message:
          description: Human-readable warning message.
          type: string
      required:
        - code
        - message
      type: object
    HomologyResult:
      additionalProperties: false
      properties:
        alignment:
          $ref: '#/components/schemas/HomologyPairwiseAlignment'
        measurements:
          $ref: '#/components/schemas/HomologyResultMeasurements'
        rank:
          format: int64
          type: integer
        significance:
          $ref: '#/components/schemas/HomologyResultSignificance'
        target:
          $ref: '#/components/schemas/HomologyResultTarget'
      required:
        - rank
        - target
        - measurements
      type: object
    HomologyResponseDatabase:
      additionalProperties: false
      properties:
        canonical_filter_sha256:
          type: string
        corpus_snapshot_id:
          type: string
        id:
          type: string
        release_id:
          pattern: ^dbr_[0-9a-f]{64}$
          type: string
        searched_residue_count:
          format: int64
          minimum: 0
          type: integer
        searched_target_count:
          format: int64
          minimum: 0
          type: integer
        slug:
          type: string
        target_space_id:
          description: >-
            Immutable reusable target-space identity when this search consumed
            one.
          pattern: ^htsp_[0-9a-f]{64}$
          type: string
      required:
        - id
        - slug
        - release_id
        - corpus_snapshot_id
        - searched_target_count
        - searched_residue_count
      type: object
    HomologyEvidenceSummary:
      additionalProperties: false
      properties:
        alignment:
          $ref: '#/components/schemas/HomologyEvidenceAvailability'
        is_complete:
          type: boolean
        requested:
          enum:
            - candidate_measurement
            - pairwise_sequence_alignment
          type: string
        significance:
          $ref: '#/components/schemas/HomologySignificanceAvailability'
      required:
        - requested
        - alignment
        - significance
        - is_complete
      type: object
    HomologyResponseExecution:
      additionalProperties: false
      properties:
        engine:
          type: string
        engine_release:
          type: string
        policy:
          $ref: '#/components/schemas/HomologyResponsePolicy'
        semantic_profile_id:
          type: string
      required:
        - engine
        - semantic_profile_id
        - policy
      type: object
    HomologyResponseQuery:
      additionalProperties: false
      properties:
        kind:
          enum:
            - protein_sequence
          type: string
        normalization_id:
          type: string
        normalized_length:
          format: int64
          type: integer
        sha256:
          type: string
      required:
        - kind
        - normalized_length
        - normalization_id
        - sha256
      type: object
    HomologyResponseRanking:
      additionalProperties: false
      properties:
        order:
          enum:
            - ascending
            - descending
          type: string
        primary_measurement:
          enum:
            - maxsim.bidirectional
            - affine.normalized_score
          type: string
        scope:
          enum:
            - resolved_policy_frontier
          type: string
        tie_breakers:
          items:
            $ref: '#/components/schemas/HomologyRankingComparator'
          type:
            - array
            - 'null'
      required:
        - primary_measurement
        - order
        - tie_breakers
        - scope
      type: object
    HomologyResponseReceipt:
      additionalProperties: false
      properties:
        bytes:
          format: int64
          minimum: 1
          type: integer
        execution_receipt_bytes:
          format: int64
          minimum: 1
          type: integer
        execution_receipt_id:
          description: >-
            Identity of the lower-level Tomato executor or distributed-job
            receipt.
          minLength: 1
          type: string
        execution_receipt_sha256:
          pattern: ^sha256:[0-9a-f]{64}$
          type: string
        id:
          description: >-
            Opaque content-addressed identity of the complete canonical search
            outcome.
          pattern: ^out_[0-9a-f]{64}$
          type: string
        sha256:
          description: Digest of the exact retained canonical outcome-receipt bytes.
          pattern: ^sha256:[0-9a-f]{64}$
          type: string
      required:
        - id
        - sha256
        - bytes
        - execution_receipt_id
        - execution_receipt_sha256
        - execution_receipt_bytes
      type: object
    HomologyPairwiseAlignment:
      additionalProperties: false
      properties:
        aligned_residue_count:
          format: int64
          type: integer
        cigar:
          type: string
        cigar_dialect:
          type: string
        coordinate_system:
          type: string
        gap_opening_count:
          format: int64
          type: integer
        gap_residue_count:
          format: int64
          type: integer
        identical_residue_count:
          format: int64
          type: integer
        query_coverage_ratio:
          format: double
          type: number
        query_end:
          format: int64
          type: integer
        query_length:
          format: int64
          type: integer
        query_start:
          format: int64
          type: integer
        sequence_identity_ratio:
          description: Identical residue count divided by aligned residue count.
          format: double
          maximum: 1
          minimum: 0
          type: number
        target_coverage_ratio:
          format: double
          type: number
        target_end:
          format: int64
          type: integer
        target_length:
          format: int64
          type: integer
        target_start:
          format: int64
          type: integer
      required:
        - coordinate_system
        - cigar_dialect
        - query_length
        - target_length
        - query_start
        - query_end
        - target_start
        - target_end
        - query_coverage_ratio
        - target_coverage_ratio
        - aligned_residue_count
        - identical_residue_count
        - sequence_identity_ratio
        - gap_residue_count
        - gap_opening_count
        - cigar
      type: object
    HomologyResultMeasurements:
      additionalProperties: false
      properties:
        affine:
          $ref: '#/components/schemas/HomologyAffineMeasurements'
        late_interaction:
          $ref: '#/components/schemas/HomologyLateInteractionMeasurements'
        maxsim:
          $ref: '#/components/schemas/HomologyMaxSimMeasurements'
      type: object
    HomologyResultSignificance:
      additionalProperties: false
      properties:
        measurements:
          $ref: '#/components/schemas/HomologySignificanceMeasurements'
        reason:
          type: string
        status:
          enum:
            - supported_empirical
            - supported_tail_model
            - insufficient_tail_resolution
            - out_of_support
          type: string
      required:
        - status
      type: object
    HomologyResultTarget:
      additionalProperties: false
      properties:
        attributes:
          additionalProperties:
            type: string
          description: >-
            Requested release-backed target attributes. Unrequested attributes
            are omitted.
          type: object
        id:
          description: >-
            Stable target record id within the selected immutable database
            release.
          type: string
        sequence:
          description: >-
            Canonical amino-acid sequence from the selected immutable database
            release.
          minLength: 1
          type: string
      required:
        - id
        - sequence
      type: object
    HomologyEvidenceAvailability:
      additionalProperties: false
      properties:
        affected_result_count:
          format: int64
          minimum: 0
          type: integer
        reason:
          type: string
        result_count:
          format: int64
          minimum: 0
          type: integer
        status:
          enum:
            - not_requested
            - returned
            - partial
            - unavailable
          type: string
      required:
        - status
        - result_count
        - affected_result_count
      type: object
    HomologySignificanceAvailability:
      additionalProperties: false
      properties:
        affected_result_count:
          format: int64
          minimum: 0
          type: integer
        reason:
          type: string
        requirement:
          enum:
            - not_requested
            - if_available
            - required
          type: string
        result_count:
          format: int64
          minimum: 0
          type: integer
        status:
          enum:
            - not_requested
            - returned
            - partial
            - unavailable
          type: string
      required:
        - requirement
        - status
        - result_count
        - affected_result_count
      type: object
    HomologyResponsePolicy:
      additionalProperties: false
      properties:
        is_deterministic:
          type: boolean
        is_exhaustive:
          type: boolean
        is_fallback:
          type: boolean
        outcome:
          enum:
            - complete_exact
            - complete_for_policy
          type: string
        requested_guarantee:
          enum:
            - approximate
            - exhaustive
          type: string
        resolution_reason:
          type: string
        resolved_guarantee:
          enum:
            - approximate
            - exhaustive
          type: string
        search_policy_id:
          type: string
      required:
        - requested_guarantee
        - resolved_guarantee
        - search_policy_id
        - outcome
        - is_fallback
        - is_exhaustive
        - is_deterministic
        - resolution_reason
      type: object
    HomologyRankingComparator:
      additionalProperties: false
      properties:
        field:
          enum:
            - maxsim.bidirectional
            - affine.normalized_score
            - affine.raw_score
            - late_interaction.distance
            - target.ordinal
          type: string
        order:
          enum:
            - ascending
            - descending
          type: string
      required:
        - field
        - order
      type: object
    HomologyAffineMeasurements:
      additionalProperties: false
      properties:
        normalized_score:
          format: double
          type: number
        raw_score:
          format: double
          type: number
      required:
        - raw_score
        - normalized_score
      type: object
    HomologyLateInteractionMeasurements:
      additionalProperties: false
      properties:
        distance:
          format: double
          type: number
        mean_closest_cosine_distance:
          format: double
          type: number
        mean_closest_cosine_similarity:
          format: double
          type: number
        query_token_count:
          format: int64
          type: integer
      required:
        - distance
        - query_token_count
        - mean_closest_cosine_distance
        - mean_closest_cosine_similarity
      type: object
    HomologyMaxSimMeasurements:
      additionalProperties: false
      properties:
        bidirectional:
          format: double
          type: number
        query_to_target:
          format: double
          type: number
        target_to_query:
          format: double
          type: number
      required:
        - query_to_target
        - target_to_query
        - bidirectional
      type: object
    HomologySignificanceMeasurements:
      additionalProperties: false
      properties:
        bit_score:
          description: >-
            Database-size-independent score from the fitted tail:
            (lambda*raw_score - ln k)/ln 2. When support_status is
            supported_tail_model the identity expected_false_hits =
            searched_sequence_count * 2^-bit_score holds exactly. In the counted
            regime the probability comes from the empirical null instead, so
            treat bit_score there as the same score on a comparable scale, not
            as a restatement of expected_false_hits.
          format: double
          type: number
        calibration_bin:
          type: string
        calibration_id:
          type: string
        calibration_sample_count:
          format: int64
          type: integer
        confidence:
          description: >-
            Bucket derived from expected_false_hits: high at 1e-5 or below,
            moderate to 1e-3, low to 1, none above. Omitted when no E-value is
            supported.
          enum:
            - high
            - moderate
            - low
            - none
          type: string
        expected_false_hits:
          description: >-
            Expected number of sequences in this search scoring at least this
            well by chance, over searched_sequence_count. Comparable to a BLAST
            E-value.
          format: double
          type: number
        family_wise_exceedance_probability:
          format: double
          type: number
        is_family_wise_lower_bound:
          description: >-
            True when a null replay frontier truncated above this score, making
            family_wise_exceedance_probability a lower bound.
          type: boolean
        minimum_resolvable_probability:
          description: >-
            Smallest probability the counted null can resolve. Below it the
            estimate comes from the fitted tail model, reported as
            support_status supported_tail_model.
          format: double
          type: number
        pair_tail_probability:
          format: double
          type: number
        q_value:
          format: double
          type: number
        searched_residue_count:
          format: int64
          type: integer
        searched_sequence_count:
          description: >-
            Sequences actually searched after any metadata filter.
            expected_false_hits is scaled to this, so it stays comparable across
            filtered and unfiltered searches.
          format: int64
          type: integer
        support_status:
          enum:
            - supported_empirical
            - supported_tail_model
            - insufficient_tail_resolution
            - out_of_support
            - missing_calibration
          type: string
        tail_model:
          $ref: '#/components/schemas/HomologyTailModel'
      required:
        - is_family_wise_lower_bound
        - searched_sequence_count
        - searched_residue_count
        - calibration_sample_count
        - support_status
        - calibration_id
      type: object
    HomologyTailModel:
      additionalProperties: false
      properties:
        fit_exceedance_count:
          format: int64
          type: integer
        holdout_exceedance_count:
          description: >-
            Held-out observations the goodness-of-fit test used. Read the KS
            distance with this; the distance alone means little without the
            sample size behind it.
          format: int64
          type: integer
        holdout_kolmogorov_smirnov:
          format: double
          type: number
        holdout_significance_level:
          format: double
          type: number
        k:
          format: double
          type: number
        lambda:
          format: double
          type: number
        threshold_score:
          description: >-
            Lower bound of the fitted tail region. Extrapolation is only
            actually used once the counted null runs out, which support_status
            reports as supported_tail_model; a score above this threshold may
            still be served empirically.
          format: double
          type: number
      required:
        - threshold_score
        - lambda
        - k
        - fit_exceedance_count
        - holdout_exceedance_count
        - holdout_kolmogorov_smirnov
        - holdout_significance_level
      type: object
  securitySchemes:
    bearerAuth:
      description: 'A Rafflesia API key, sent as `Authorization: Bearer <key>`.'
      scheme: bearer
      type: http

````