> ## 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 homologous protein sequences 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 results 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 homologous protein sequences 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 results 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.
          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.
            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
            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
        '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
components:
  schemas:
    HomologyBatchRequest:
      additionalProperties: false
      allOf:
        - oneOf:
            - not:
                required:
                  - database_release_id
                type: object
              properties:
                database:
                  type: string
              required:
                - database
              type: object
            - not:
                required:
                  - database
                type: object
              properties:
                database_release_id:
                  type: string
              required:
                - database_release_id
              type: object
      properties:
        database:
          description: >-
            Database id or slug from homology.databases.list. Exactly one of
            database or database_release_id is required.
          maxLength: 256
          minLength: 1
          type: string
        database_release_id:
          description: >-
            Exact immutable release id. Exactly one of database or
            database_release_id is required.
          maxLength: 256
          minLength: 1
          type: string
        filter:
          $ref: '#/components/schemas/HomologyDocumentFilter'
          description: >-
            Optional exact metadata predicate applied before candidate
            generation.
        guarantee:
          default: approximate
          description: >-
            Minimum search guarantee. Approximate permits a qualified
            approximate policy or a stronger exhaustive fallback; exhaustive
            requires the release's exhaustive reference policy.
          enum:
            - approximate
            - exhaustive
          type: string
        include:
          default:
            - alignment
          description: >-
            Scientific result representations to return. Pairwise alignment is
            included by default. Pass an empty array for candidate measurements
            only.
          items:
            enum:
              - alignment
            type: string
          maxItems: 1
          type: array
          uniqueItems: true
        include_attributes:
          description: >-
            Optional target attributes to project. The current Tomato catalog
            can project record_id; unsupported attributes are rejected instead
            of fabricated.
          items:
            enum:
              - record_id
            type: string
          maxItems: 1
          type:
            - array
            - 'null'
          uniqueItems: true
        limit:
          default: 25
          description: >-
            Maximum number of ranked results to return per query. queries count
            multiplied by limit must fit the include-sensitive aggregate batch
            cap.
          format: int64
          maximum: 10000
          minimum: 1
          type: integer
        max_billable_units:
          description: >-
            Optional hard ceiling on deterministic billable work across the
            complete batch. The batch fails before exceeding it.
          format: int64
          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
          description: >-
            Whether database-aware significance is omitted, included when a
            compatible calibration exists, or required for the request to
            succeed.
          enum:
            - not_requested
            - if_available
            - required
          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:
        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:
        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:
        - 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
    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
    HomologyFilterNot:
      additionalProperties: false
      properties:
        filter:
          $ref: '#/components/schemas/HomologyDocumentFilter'
        op:
          enum:
            - not
          type: string
      required:
        - op
        - filter
      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: 16384
              type: string
            - type: integer
            - type: boolean
      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: 16384
                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
    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
    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
    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
    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
    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
    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:
        database:
          $ref: '#/components/schemas/HomologyResponseDatabase'
        is_result_limit_reached:
          type: boolean
        method:
          $ref: '#/components/schemas/HomologyResponseMethod'
        query:
          $ref: '#/components/schemas/HomologyResponseQuery'
        query_index:
          format: int64
          minimum: 0
          type: integer
        result_sha256:
          type: string
        results:
          items:
            $ref: '#/components/schemas/HomologyResult'
          type: array
        usage:
          $ref: '#/components/schemas/HomologyResponseUsage'
        warnings:
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - query_index
        - query
        - database
        - method
        - results
        - is_result_limit_reached
        - result_sha256
        - usage
        - warnings
      type: object
    HomologyResponseUsage:
      additionalProperties: false
      properties:
        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
    HomologyResponseDatabase:
      additionalProperties: false
      properties:
        canonical_filter_sha256:
          type: string
        corpus_snapshot_id:
          type: string
        id:
          type: string
        release_id:
          type: string
        searched_residue_count:
          format: int64
          minimum: 0
          type: integer
        searched_target_count:
          format: int64
          minimum: 0
          type: integer
        slug:
          type: string
      required:
        - id
        - slug
        - release_id
        - corpus_snapshot_id
        - searched_target_count
        - searched_residue_count
      type: object
    HomologyResponseMethod:
      additionalProperties: false
      properties:
        calibration_id:
          type: string
        engine:
          type: string
        engine_release:
          type: string
        is_deterministic:
          type: boolean
        is_exhaustive:
          type: boolean
        outcome:
          enum:
            - complete_exact
            - complete_for_policy
          type: string
        search_policy_id:
          type: string
        semantic_profile_id:
          type: string
      required:
        - engine
        - search_policy_id
        - semantic_profile_id
        - is_exhaustive
        - is_deterministic
      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
    HomologyResult:
      additionalProperties: false
      properties:
        affine:
          $ref: '#/components/schemas/HomologyAffineMeasurements'
        alignment:
          $ref: '#/components/schemas/HomologyPairwiseAlignment'
        maxsim:
          $ref: '#/components/schemas/HomologyMaxSimMeasurements'
        rank:
          format: int64
          type: integer
        significance:
          $ref: '#/components/schemas/HomologySignificanceMeasurements'
        target:
          $ref: '#/components/schemas/HomologyResultTarget'
      required:
        - rank
        - target
        - maxsim
      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
    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
        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
        - gap_residue_count
        - gap_opening_count
        - cigar
      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:
        calibration_bin:
          type: string
        calibration_id:
          type: string
        calibration_sample_count:
          format: int64
          type: integer
        expected_false_hits:
          format: double
          type: number
        family_wise_exceedance_probability:
          format: double
          type: number
        minimum_resolvable_probability:
          format: double
          type: number
        pair_tail_probability:
          format: double
          type: number
        q_value:
          format: double
          type: number
        support_status:
          enum:
            - supported_empirical
            - supported_tail_model
            - insufficient_tail_resolution
            - out_of_support
            - missing_calibration
          type: string
      required:
        - calibration_sample_count
        - support_status
        - calibration_id
      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
      required:
        - id
      type: object
  securitySchemes:
    bearerAuth:
      description: 'A Rafflesia API key, sent as `Authorization: Bearer <key>`.'
      scheme: bearer
      type: http

````