cURL

curl --request POST \
  --url "https://api.rafflesia.ai/v1/homology" \
  --header "Authorization: Bearer $RAFFLESIA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": {
      "kind": "protein_sequence",
      "sequence": "<sequence>"
    }
  }'

{
  "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": 2,
      "target": {
        "id": "<string>",
        "sequence": "<string>",
        "attributes": {}
      },
      "alignment": {
        "aligned_residue_count": 1,
        "cigar": "<string>",
        "cigar_dialect": "extended",
        "coordinate_system": "zero_based_half_open",
        "gap_opening_count": 1,
        "gap_residue_count": 1,
        "identical_residue_count": 1,
        "query_coverage_ratio": 0.5,
        "query_end": 1,
        "query_length": 2,
        "query_start": 1,
        "sequence_identity_ratio": 0.5,
        "target_coverage_ratio": 0.5,
        "target_end": 1,
        "target_length": 2,
        "target_start": 1
      },
      "significance": {
        "status": "supported_empirical",
        "measurements": {
          "calibration_id": "<string>",
          "calibration_sample_count": 1,
          "is_family_wise_lower_bound": true,
          "searched_residue_count": 1,
          "searched_sequence_count": 1,
          "support_status": "supported_empirical",
          "bit_score": 123,
          "calibration_bin": "<string>",
          "e_value_calibration_id": "<string>",
          "e_value_conditioning_context_id": "<string>",
          "e_value_estimand": "<string>",
          "e_value_maximum_log_extrapolation_factor": 1,
          "e_value_method": "<string>",
          "e_value_null_population_id": "<string>",
          "e_value_qualification_id": "<string>",
          "e_value_search_policy_id": "<string>",
          "e_value_searched_inventory_id": "<string>",
          "e_value_supported_log_maximum": 123,
          "e_value_supported_log_minimum": 123,
          "e_value_tail_coordinate": 123,
          "e_value_target_stratum_count": 1,
          "expected_false_hits": 1,
          "family_wise_exceedance_probability": 0.5,
          "is_e_value_upper_bound": true,
          "log_expected_false_hits": 123,
          "minimum_resolvable_probability": 0.5,
          "pair_tail_log_probability": 123,
          "pair_tail_probability": 0.5,
          "pair_tail_surprisal_bits": 1,
          "q_value": 0.5,
          "tail_model": {
            "fit_exceedance_count": 1,
            "holdout_exceedance_count": 1,
            "holdout_kolmogorov_smirnov": 0.5,
            "holdout_significance_level": 0.5,
            "k": 1,
            "lambda": 1,
            "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_candidate_count": 1,
      "candidate_count": 1,
      "status": "not_requested",
      "reason": "<string>"
    },
    "is_requested_evidence_complete": true,
    "requested": "candidate_measurement",
    "significance": {
      "affected_candidate_count": 1,
      "candidate_count": 1,
      "requirement": "not_requested",
      "status": "not_requested",
      "reason": "no_qualified_calibration"
    }
  },
  "execution": {
    "created_at": "2023-11-07T05:31:56Z",
    "engine": "<string>",
    "policy": {
      "is_deterministic": true,
      "is_exhaustive": true,
      "is_fallback": true,
      "outcome": "complete_exact",
      "requested_guarantee": "approximate",
      "resolution_reason": "<string>",
      "resolved_guarantee": "approximate"
    },
    "semantic_profile_id": "<string>",
    "server_version": "<string>",
    "engine_release": "<string>"
  },
  "is_result_limit_reached": true,
  "object": "homology_candidate_set",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 1,
    "search_execution_ms": 1,
    "server_total_ms": 1
  },
  "query": {
    "kind": "protein_sequence",
    "normalization_id": "<string>",
    "normalized_length": 50000,
    "sha256": "<string>"
  },
  "ranking": {
    "comparability": "within_query_only",
    "order": "ascending",
    "primary_measurement": "maxsim.bidirectional",
    "scope": "resolved_policy_frontier",
    "tie_breakers": [
      {
        "field": "maxsim.bidirectional",
        "order": "ascending"
      }
    ]
  },
  "receipt": {
    "bytes": 2,
    "id": "<string>",
    "sha256": "<string>"
  },
  "request_id": "<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": {}
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

Search for protein homology candidates

Runs one typed protein query against one resolved immutable database release and returns completed ranked candidates and requested evidence directly. Candidates are retrieval measurements, not asserted homologs. This bounded stateless operation returns at most 5,000 rows inline. POST /v1/runs with endpoint rafflesia/homology executes the same scientific contract but adds the uniform retained-run resource, provenance, billing, and optional background/event lifecycle. Use this direct route for the smallest synchronous HTTP exchange; use runs for the model-platform lifecycle, or create a retained homology search when cursor pagination or up to 10,000 rows is required.

POST

homology

cURL

curl --request POST \
  --url "https://api.rafflesia.ai/v1/homology" \
  --header "Authorization: Bearer $RAFFLESIA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": {
      "kind": "protein_sequence",
      "sequence": "<sequence>"
    }
  }'

{
  "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": 2,
      "target": {
        "id": "<string>",
        "sequence": "<string>",
        "attributes": {}
      },
      "alignment": {
        "aligned_residue_count": 1,
        "cigar": "<string>",
        "cigar_dialect": "extended",
        "coordinate_system": "zero_based_half_open",
        "gap_opening_count": 1,
        "gap_residue_count": 1,
        "identical_residue_count": 1,
        "query_coverage_ratio": 0.5,
        "query_end": 1,
        "query_length": 2,
        "query_start": 1,
        "sequence_identity_ratio": 0.5,
        "target_coverage_ratio": 0.5,
        "target_end": 1,
        "target_length": 2,
        "target_start": 1
      },
      "significance": {
        "status": "supported_empirical",
        "measurements": {
          "calibration_id": "<string>",
          "calibration_sample_count": 1,
          "is_family_wise_lower_bound": true,
          "searched_residue_count": 1,
          "searched_sequence_count": 1,
          "support_status": "supported_empirical",
          "bit_score": 123,
          "calibration_bin": "<string>",
          "e_value_calibration_id": "<string>",
          "e_value_conditioning_context_id": "<string>",
          "e_value_estimand": "<string>",
          "e_value_maximum_log_extrapolation_factor": 1,
          "e_value_method": "<string>",
          "e_value_null_population_id": "<string>",
          "e_value_qualification_id": "<string>",
          "e_value_search_policy_id": "<string>",
          "e_value_searched_inventory_id": "<string>",
          "e_value_supported_log_maximum": 123,
          "e_value_supported_log_minimum": 123,
          "e_value_tail_coordinate": 123,
          "e_value_target_stratum_count": 1,
          "expected_false_hits": 1,
          "family_wise_exceedance_probability": 0.5,
          "is_e_value_upper_bound": true,
          "log_expected_false_hits": 123,
          "minimum_resolvable_probability": 0.5,
          "pair_tail_log_probability": 123,
          "pair_tail_probability": 0.5,
          "pair_tail_surprisal_bits": 1,
          "q_value": 0.5,
          "tail_model": {
            "fit_exceedance_count": 1,
            "holdout_exceedance_count": 1,
            "holdout_kolmogorov_smirnov": 0.5,
            "holdout_significance_level": 0.5,
            "k": 1,
            "lambda": 1,
            "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_candidate_count": 1,
      "candidate_count": 1,
      "status": "not_requested",
      "reason": "<string>"
    },
    "is_requested_evidence_complete": true,
    "requested": "candidate_measurement",
    "significance": {
      "affected_candidate_count": 1,
      "candidate_count": 1,
      "requirement": "not_requested",
      "status": "not_requested",
      "reason": "no_qualified_calibration"
    }
  },
  "execution": {
    "created_at": "2023-11-07T05:31:56Z",
    "engine": "<string>",
    "policy": {
      "is_deterministic": true,
      "is_exhaustive": true,
      "is_fallback": true,
      "outcome": "complete_exact",
      "requested_guarantee": "approximate",
      "resolution_reason": "<string>",
      "resolved_guarantee": "approximate"
    },
    "semantic_profile_id": "<string>",
    "server_version": "<string>",
    "engine_release": "<string>"
  },
  "is_result_limit_reached": true,
  "object": "homology_candidate_set",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 1,
    "search_execution_ms": 1,
    "server_total_ms": 1
  },
  "query": {
    "kind": "protein_sequence",
    "normalization_id": "<string>",
    "normalized_length": 50000,
    "sha256": "<string>"
  },
  "ranking": {
    "comparability": "within_query_only",
    "order": "ascending",
    "primary_measurement": "maxsim.bidirectional",
    "scope": "resolved_policy_frontier",
    "tie_breakers": [
      {
        "field": "maxsim.bidirectional",
        "order": "ascending"
      }
    ]
  },
  "receipt": {
    "bytes": 2,
    "id": "<string>",
    "sha256": "<string>"
  },
  "request_id": "<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": {}
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

Optional retry identity retained for 24 hours. Reuse the same key for the same request after an ambiguous failure. When omitted, each HTTP request is a distinct billable operation, while equivalent scientific execution may still be reused from cache.

Maximum string length: 255

Rafflesia-API-Version

string

Optional dated contract pin. Omit to use the current 2026-08-08 homology contract; any other value returns api_version_unsupported.

Body

application/json

query

object

required

One typed biological query.

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

Stable scientific evidence representation. The release-owned final ranking measurement is always returned independently.

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

Minimum search guarantee. Approximate permits the release-selected qualified policy or a stronger exhaustive fallback; exhaustive requires the reference policy.

Available options:

approximate,

exhaustive

limit

integer<int64>

default:25

Maximum ranked results. Inline delivery accepts at most 5,000 and remains bounded by the 16 MiB response ceiling; retained delivery accepts at most 10,000 and pages the immutable result set.

Required range: 1 <= x <= 5000

significance

enum<string>

default:if_available

Database-aware significance requirement. if_available never invalidates an otherwise valid alignment.

Available options:

not_requested,

if_available,

required

target_space_id

string

Immutable reusable target space returned as database.target_space_id by a prior filtered homology search. Mutually exclusive with database, database_release_id, and filter.

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

Response

candidates

object[]

required

Ranked retrieval candidates. These are measurements, not asserted homologs.

Show child attributes

database

object

required

Show child attributes

evidence_summary

object

required

Show child attributes

execution

object

required

Show child attributes

is_result_limit_reached

boolean

required

True when additional ranked targets existed beyond limit. False means the returned list exhausted the searched population.

object

enum<string>

required

Always homology_candidate_set.

Available options:

homology_candidate_set

performance

object

required

Show child attributes

query

object

required

Show child attributes

ranking

object

required

Show child attributes

receipt

object

required

Show child attributes

request_id

string

required

result_sha256

string

required

usage

object

required

Show child attributes

warnings

object[]

required

Non-fatal warnings. Always an array.

Show child attributes

Reference

Endpoints

Search for protein homology candidates

Authorizations

Headers

Body

Response