> ## 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.

# Place one receipt-bound protein sequence into an immutable MSA component



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sequences/msa/place
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/sequences/msa/place:
    post:
      tags:
        - MSA
      summary: Place one receipt-bound protein sequence into an immutable MSA component
      operationId: sequences.msa.place
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MSAPlacementRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: OK
          headers:
            Rafflesia-Contract-Digest:
              schema:
                type: string
            Rafflesia-Version:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeMSAPlacementData'
          description: Service Unavailable
      x-codeSamples:
        - lang: bash
          source: |
            curl --request POST \
              --url "https://api.rafflesia.ai/v1/sequences/msa/place" \
              --header "Authorization: Bearer $RAFFLESIA_API_KEY" \
              --header "Content-Type: application/json" \
              --data '{
                "homology_outcome_receipt_id": "<homology_outcome_receipt_id>",
                "query": {
                  "id": "<id>",
                  "kind": "protein_sequence",
                  "sequence": "<sequence>"
                }
              }'
components:
  schemas:
    MSAPlacementRequest:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/MSAPlacementRequest.json
          format: uri
          readOnly: true
          type: string
        homology_outcome_receipt_id:
          description: Canonical outcome receipt returned by POST /v1/homology.
          pattern: ^out_[0-9a-f]{64}$
          type: string
        query:
          $ref: '#/components/schemas/MSAPlacementQuery'
      required:
        - query
        - homology_outcome_receipt_id
      type: object
    EnvelopeMSAPlacementData:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/EnvelopeMSAPlacementData.json
          format: uri
          readOnly: true
          type: string
        data:
          $ref: '#/components/schemas/MSAPlacementData'
          description: Operation result data.
        error:
          $ref: '#/components/schemas/APIError'
          description: Structured error information.
        evidence:
          $ref: '#/components/schemas/EvidenceSummary'
          description: Mechanical evidence summary for agent inspection and chaining.
        ok:
          description: Whether the operation succeeded.
          type: boolean
        provenance:
          $ref: '#/components/schemas/Provenance'
          description: Execution provenance.
        warnings:
          description: Non-fatal warnings.
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - ok
        - warnings
        - provenance
      type: object
    MSAPlacementQuery:
      additionalProperties: false
      properties:
        id:
          description: Caller-supplied FASTA record identifier for the placed query.
          maxLength: 256
          minLength: 1
          type: string
        kind:
          description: Always protein_sequence.
          enum:
            - protein_sequence
          type: string
        sequence:
          description: Protein sequence used by the referenced homology outcome.
          maxLength: 100000
          minLength: 1
          type: string
      required:
        - id
        - kind
        - sequence
      type: object
    MSAPlacementData:
      additionalProperties: false
      properties:
        artifact:
          $ref: '#/components/schemas/MSAPlacementArtifact'
        backbone_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        component_attachment_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        component_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        database_release_id:
          pattern: ^dbr_[0-9a-f]{64}$
          type: string
        encoder:
          $ref: '#/components/schemas/MSAEncoderDisclosure'
        execution:
          $ref: '#/components/schemas/MSAPlacementExecution'
        forest_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        homology_receipt:
          $ref: '#/components/schemas/MSAHomologyReceiptReference'
        id:
          pattern: ^msap_[0-9a-f]{64}$
          type: string
        msa_release_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        object:
          enum:
            - msa_placement
          type: string
        placement_object:
          $ref: '#/components/schemas/ObjectRef'
        query:
          $ref: '#/components/schemas/MSAPlacementQuery'
        release_attachment_id:
          pattern: ^[0-9a-f]{64}$
          type: string
        warnings:
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - object
        - id
        - query
        - database_release_id
        - homology_receipt
        - release_attachment_id
        - component_attachment_id
        - msa_release_id
        - component_id
        - forest_id
        - backbone_id
        - artifact
        - execution
        - encoder
        - placement_object
        - warnings
      type: object
    APIError:
      additionalProperties: false
      properties:
        code:
          description: Stable specific error code.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured error details.
          type: object
        doc_url:
          description: Stable documentation URL for this error code.
          type: string
        message:
          description: Human-readable error message.
          type: string
        param:
          description: Request field responsible for the error when known.
          type: string
        type:
          description: Stable coarse error category.
          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
        - doc_url
      type: object
    EvidenceSummary:
      additionalProperties: false
      properties:
        duration_ms:
          description: >-
            Primary elapsed duration in milliseconds when the response exposes
            one.
          format: int64
          type: integer
        input_refs:
          description: >-
            Input references detected from request fields such as object_id,
            structure_id, target_id, and sequence_id.
          items:
            type: string
          type:
            - array
            - 'null'
        object_refs:
          description: Object ids or object refs visible in the response/provenance.
          items:
            type: string
          type:
            - array
            - 'null'
        output_refs:
          description: Output references detected from response data and generated objects.
          items:
            type: string
          type:
            - array
            - 'null'
        row_count:
          description: >-
            Primary row count or returned row count when the response exposes
            one.
          format: int64
          type: integer
        warnings_count:
          description: Number of non-fatal warnings in the envelope.
          format: int64
          type: integer
      required:
        - warnings_count
      type: object
    Provenance:
      additionalProperties: false
      properties:
        cache_hit:
          description: Whether cached output was reused.
          type: boolean
        created_at:
          description: UTC timestamp.
          type: string
        database_snapshots:
          description: Database snapshots used.
          items:
            $ref: '#/components/schemas/DatabaseSnapshot'
          type:
            - array
            - 'null'
        generated_object_ids:
          description: Object ids created by the operation.
          items:
            type: string
          type:
            - array
            - 'null'
        input_hash:
          description: SHA-256 hash of canonical request input.
          type: string
        operation:
          description: Primitive operation id.
          type: string
        parameters_hash:
          description: SHA-256 hash of parameters.
          type: string
        request_id:
          description: Unique request identifier.
          type: string
        server_version:
          description: Server version.
          type: string
        tool_versions:
          description: Tool versions used.
          items:
            $ref: '#/components/schemas/ToolVersion'
          type:
            - array
            - 'null'
      required:
        - request_id
        - operation
        - created_at
        - server_version
      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
    MSAPlacementArtifact:
      additionalProperties: false
      properties:
        alignment_object:
          $ref: '#/components/schemas/ObjectRef'
        base_alignment:
          $ref: '#/components/schemas/MSAExternalArtifactDigest'
        base_column_count:
          description: >-
            Known base column count, or zero when the exact-cache path did not
            read component metadata.
          format: int64
          minimum: 0
          type: integer
        kind:
          enum:
            - cached_alignment
            - sparse_overlay
            - full_alignment
          type: string
        materialized_column_count:
          description: >-
            Known materialized column count, or zero until explicit
            materialization.
          format: int64
          minimum: 0
          type: integer
        overlay_object:
          $ref: '#/components/schemas/ObjectRef'
        sequence_count:
          description: >-
            Known row count, or zero when exact-cache placement intentionally
            returns only the external digest.
          format: int64
          minimum: 0
          type: integer
      required:
        - kind
        - sequence_count
        - base_column_count
        - materialized_column_count
      type: object
    MSAEncoderDisclosure:
      additionalProperties: false
      properties:
        conformance_class:
          enum:
            - byte_exact_canonical
            - compatible_noncanonical
          type: string
        encoder_compatibility_class_id:
          type: string
        encoder_numerics_id:
          type: string
        observed_canonical_precision:
          type: string
        semantic_profile_id:
          type: string
      required:
        - semantic_profile_id
        - encoder_numerics_id
        - encoder_compatibility_class_id
        - conformance_class
        - observed_canonical_precision
      type: object
    MSAPlacementExecution:
      additionalProperties: false
      properties:
        algorithm:
          type: string
        anchor_record_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        attachment_reads:
          $ref: '#/components/schemas/MSAObjectReadMeasurements'
        backbone_reads:
          $ref: '#/components/schemas/MSAObjectReadMeasurements'
        catalog_elapsed_ms:
          format: int64
          type: integer
        execution_elapsed_ms:
          format: int64
          type: integer
        handoff_elapsed_ms:
          format: int64
          type: integer
        is_backend_invoked:
          type: boolean
        is_complete_membership_read:
          type: boolean
        is_exact_component_cache_hit:
          type: boolean
        is_full_backbone_read:
          type: boolean
        is_homology_receipt_valid:
          type: boolean
        is_target_sequence_valid:
          type: boolean
        membership_reads:
          $ref: '#/components/schemas/MSAObjectReadMeasurements'
        strategy:
          enum:
            - exact_component_cache
            - tomato_affine_verified_backbone_delta
            - tomato_affine_native_famsa_fallback
          type: string
        target_validation_reads:
          $ref: '#/components/schemas/MSAObjectReadMeasurements'
        total_elapsed_ms:
          format: int64
          type: integer
      required:
        - algorithm
        - strategy
        - is_exact_component_cache_hit
        - is_homology_receipt_valid
        - is_target_sequence_valid
        - is_complete_membership_read
        - is_backend_invoked
        - is_full_backbone_read
        - anchor_record_ids
        - attachment_reads
        - target_validation_reads
        - membership_reads
        - backbone_reads
        - catalog_elapsed_ms
        - handoff_elapsed_ms
        - execution_elapsed_ms
        - total_elapsed_ms
      type: object
    MSAHomologyReceiptReference:
      additionalProperties: false
      properties:
        execution_receipt_id:
          minLength: 1
          type: string
        execution_receipt_sha256:
          pattern: ^sha256:[0-9a-f]{64}$
          type: string
        id:
          pattern: ^out_[0-9a-f]{64}$
          type: string
        sha256:
          pattern: ^sha256:[0-9a-f]{64}$
          type: string
      required:
        - id
        - sha256
        - execution_receipt_id
        - execution_receipt_sha256
      type: object
    ObjectRef:
      additionalProperties: false
      properties:
        bucket:
          type: string
        content_type:
          type: string
        kind:
          type: string
        object_id:
          type: string
        object_key:
          type: string
        path:
          type: string
        sha256:
          type: string
        size_bytes:
          format: int64
          type: integer
        storage_backend:
          type: string
        uri:
          type: string
      required:
        - object_id
        - kind
        - size_bytes
        - sha256
      type: object
    DatabaseSnapshot:
      additionalProperties: false
      properties:
        digest:
          type: string
        kind:
          type: string
        name:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
    ToolVersion:
      additionalProperties: false
      properties:
        name:
          type: string
        path:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
    MSAExternalArtifactDigest:
      additionalProperties: false
      properties:
        sha256:
          pattern: ^sha256:[0-9a-f]{64}$
          type: string
        size_bytes:
          format: int64
          minimum: 1
          type: integer
      required:
        - sha256
        - size_bytes
      type: object
    MSAObjectReadMeasurements:
      additionalProperties: false
      properties:
        directory_page_bytes:
          format: int64
          type: integer
        directory_page_reads:
          format: int64
          type: integer
        object_bytes:
          format: int64
          type: integer
        object_reads:
          format: int64
          type: integer
        peak_resident_directory_pages:
          format: int64
          type: integer
        range_bytes:
          format: int64
          type: integer
        range_reads:
          format: int64
          type: integer
        record_bytes:
          format: int64
          type: integer
        record_reads:
          format: int64
          type: integer
        remote_requests:
          format: int64
          type: integer
        retry_count:
          format: int64
          type: integer
      required:
        - object_reads
        - object_bytes
        - range_reads
        - range_bytes
        - record_reads
        - record_bytes
        - directory_page_reads
        - directory_page_bytes
        - peak_resident_directory_pages
        - remote_requests
        - retry_count
      type: object
  securitySchemes:
    bearerAuth:
      description: 'A Rafflesia API key, sent as `Authorization: Bearer <key>`.'
      scheme: bearer
      type: http

````