Search for protein homology candidates in a batch

cURL

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>"
      }
    ]
  }'

{
  "object": "homology_search_result_set_batch",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 123,
    "search_execution_ms": 123,
    "server_total_ms": 123
  },
  "request_id": "<string>",
  "responses": [
    {
      "candidates": [
        {
          "measurements": {
            "affine": {
              "normalized_score": 123,
              "raw_score": 123
            },
            "late_interaction": {
              "distance": 123,
              "mean_closest_cosine_distance": 123,
              "mean_closest_cosine_similarity": 123,
              "query_token_count": 123
            },
            "maxsim": {
              "bidirectional": 123,
              "query_to_target": 123,
              "target_to_query": 123
            }
          },
          "rank": 123,
          "target": {
            "id": "<string>",
            "sequence": "<string>",
            "attributes": {}
          },
          "alignment": {
            "aligned_residue_count": 123,
            "cigar": "<string>",
            "cigar_dialect": "<string>",
            "coordinate_system": "<string>",
            "gap_opening_count": 123,
            "gap_residue_count": 123,
            "identical_residue_count": 123,
            "query_coverage_ratio": 123,
            "query_end": 123,
            "query_length": 123,
            "query_start": 123,
            "sequence_identity_ratio": 0.5,
            "target_coverage_ratio": 123,
            "target_end": 123,
            "target_length": 123,
            "target_start": 123
          },
          "significance": {
            "measurements": {
              "calibration_id": "<string>",
              "calibration_sample_count": 123,
              "is_family_wise_lower_bound": true,
              "searched_residue_count": 123,
              "searched_sequence_count": 123,
              "bit_score": 123,
              "calibration_bin": "<string>",
              "expected_false_hits": 123,
              "family_wise_exceedance_probability": 123,
              "minimum_resolvable_probability": 123,
              "pair_tail_probability": 123,
              "q_value": 123,
              "tail_model": {
                "fit_exceedance_count": 123,
                "holdout_exceedance_count": 123,
                "holdout_kolmogorov_smirnov": 123,
                "holdout_significance_level": 123,
                "k": 123,
                "lambda": 123,
                "threshold_score": 123
              }
            },
            "reason": "<string>"
          }
        }
      ],
      "database": {
        "corpus_snapshot_id": "<string>",
        "id": "<string>",
        "release_id": "<string>",
        "searched_residue_count": 1,
        "searched_target_count": 1,
        "slug": "<string>",
        "canonical_filter_sha256": "<string>",
        "target_space_id": "<string>"
      },
      "evidence_summary": {
        "alignment": {
          "affected_result_count": 1,
          "result_count": 1,
          "reason": "<string>"
        },
        "is_complete": true,
        "significance": {
          "affected_result_count": 1,
          "result_count": 1,
          "reason": "<string>"
        }
      },
      "execution": {
        "engine": "<string>",
        "policy": {
          "is_deterministic": true,
          "is_exhaustive": true,
          "is_fallback": true,
          "resolution_reason": "<string>",
          "search_policy_id": "<string>"
        },
        "semantic_profile_id": "<string>",
        "engine_release": "<string>"
      },
      "is_result_limit_reached": true,
      "object": "homology_candidate_set",
      "query": {
        "kind": "protein_sequence",
        "normalization_id": "<string>",
        "normalized_length": 123,
        "sha256": "<string>"
      },
      "query_index": 1,
      "ranking": {
        "scope": "resolved_policy_frontier",
        "tie_breakers": [
          {}
        ]
      },
      "receipt": {
        "bytes": 2,
        "execution_receipt_bytes": 2,
        "execution_receipt_id": "<string>",
        "execution_receipt_sha256": "<string>",
        "id": "<string>",
        "sha256": "<string>"
      },
      "result_sha256": "<string>",
      "usage": {
        "logical_bytes_returned": 1,
        "billable_formula_id": "<string>",
        "billable_units": 1,
        "logical_bytes_read": 1
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>",
          "details": {}
        }
      ]
    }
  ],
  "result_sha256": "<string>",
  "usage": {
    "logical_bytes_returned": 1,
    "billable_formula_id": "<string>",
    "billable_units": 1,
    "logical_bytes_read": 1
  },
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

POST

homology

batch

cURL

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>"
      }
    ]
  }'

{
  "object": "homology_search_result_set_batch",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 123,
    "search_execution_ms": 123,
    "server_total_ms": 123
  },
  "request_id": "<string>",
  "responses": [
    {
      "candidates": [
        {
          "measurements": {
            "affine": {
              "normalized_score": 123,
              "raw_score": 123
            },
            "late_interaction": {
              "distance": 123,
              "mean_closest_cosine_distance": 123,
              "mean_closest_cosine_similarity": 123,
              "query_token_count": 123
            },
            "maxsim": {
              "bidirectional": 123,
              "query_to_target": 123,
              "target_to_query": 123
            }
          },
          "rank": 123,
          "target": {
            "id": "<string>",
            "sequence": "<string>",
            "attributes": {}
          },
          "alignment": {
            "aligned_residue_count": 123,
            "cigar": "<string>",
            "cigar_dialect": "<string>",
            "coordinate_system": "<string>",
            "gap_opening_count": 123,
            "gap_residue_count": 123,
            "identical_residue_count": 123,
            "query_coverage_ratio": 123,
            "query_end": 123,
            "query_length": 123,
            "query_start": 123,
            "sequence_identity_ratio": 0.5,
            "target_coverage_ratio": 123,
            "target_end": 123,
            "target_length": 123,
            "target_start": 123
          },
          "significance": {
            "measurements": {
              "calibration_id": "<string>",
              "calibration_sample_count": 123,
              "is_family_wise_lower_bound": true,
              "searched_residue_count": 123,
              "searched_sequence_count": 123,
              "bit_score": 123,
              "calibration_bin": "<string>",
              "expected_false_hits": 123,
              "family_wise_exceedance_probability": 123,
              "minimum_resolvable_probability": 123,
              "pair_tail_probability": 123,
              "q_value": 123,
              "tail_model": {
                "fit_exceedance_count": 123,
                "holdout_exceedance_count": 123,
                "holdout_kolmogorov_smirnov": 123,
                "holdout_significance_level": 123,
                "k": 123,
                "lambda": 123,
                "threshold_score": 123
              }
            },
            "reason": "<string>"
          }
        }
      ],
      "database": {
        "corpus_snapshot_id": "<string>",
        "id": "<string>",
        "release_id": "<string>",
        "searched_residue_count": 1,
        "searched_target_count": 1,
        "slug": "<string>",
        "canonical_filter_sha256": "<string>",
        "target_space_id": "<string>"
      },
      "evidence_summary": {
        "alignment": {
          "affected_result_count": 1,
          "result_count": 1,
          "reason": "<string>"
        },
        "is_complete": true,
        "significance": {
          "affected_result_count": 1,
          "result_count": 1,
          "reason": "<string>"
        }
      },
      "execution": {
        "engine": "<string>",
        "policy": {
          "is_deterministic": true,
          "is_exhaustive": true,
          "is_fallback": true,
          "resolution_reason": "<string>",
          "search_policy_id": "<string>"
        },
        "semantic_profile_id": "<string>",
        "engine_release": "<string>"
      },
      "is_result_limit_reached": true,
      "object": "homology_candidate_set",
      "query": {
        "kind": "protein_sequence",
        "normalization_id": "<string>",
        "normalized_length": 123,
        "sha256": "<string>"
      },
      "query_index": 1,
      "ranking": {
        "scope": "resolved_policy_frontier",
        "tie_breakers": [
          {}
        ]
      },
      "receipt": {
        "bytes": 2,
        "execution_receipt_bytes": 2,
        "execution_receipt_id": "<string>",
        "execution_receipt_sha256": "<string>",
        "id": "<string>",
        "sha256": "<string>"
      },
      "result_sha256": "<string>",
      "usage": {
        "logical_bytes_returned": 1,
        "billable_formula_id": "<string>",
        "billable_units": 1,
        "logical_bytes_read": 1
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>",
          "details": {}
        }
      ]
    }
  ],
  "result_sha256": "<string>",
  "usage": {
    "logical_bytes_returned": 1,
    "billable_formula_id": "<string>",
    "billable_units": 1,
    "logical_bytes_read": 1
  },
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "doc_url": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": {},
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A Rafflesia API key, sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

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.

Body

application/json

queries

object[]

required

An ordered batch of 1 to 16 typed biological queries sharing every search control.

Required array length: 1 - 16 elements

Show child attributes

database

string

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.

Required string length: 1 - 256

database_release_id

string

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}$

evidence

enum<string>

default:pairwise_sequence_alignment

Available options:

candidate_measurement,

pairwise_sequence_alignment

filter

object

Optional exact metadata predicate applied before the release-owned search policy.

Show child attributes

guarantee

enum<string>

default:approximate

Available options:

approximate,

exhaustive

include_attributes

enum<string>[] | null

Maximum array length: 1

Available options:

record_id

limit

integer<int64>

default:25

Maximum ranked results returned for each query.

Required range: 1 <= x <= 1000

significance

enum<string>

default:if_available

Available options:

not_requested,

if_available,

required

target_space_id

string

Immutable reusable target space shared by every query. Mutually exclusive with database, database_release_id, and filter.

Pattern: ^htsp_[0-9a-f]{64}$

Response

object

enum<string>

required

Always homology_search_result_set_batch.

Available options:

homology_search_result_set_batch

performance

object

required

Show child attributes

request_id

string

required

responses

object[]

required

Required array length: 1 - 16 elements

Show child attributes

result_sha256

string

required

usage

object

required

Show child attributes

warnings

object[] | null

required

Show child attributes

Search for protein homology candidates

List searchable homology databases

Reference

Endpoints

Search for protein homology candidates in a batch

Authorizations

Headers

Body

Response