Search for protein homology candidates

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": 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",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 123,
    "search_execution_ms": 123,
    "server_total_ms": 123
  },
  "query": {
    "kind": "protein_sequence",
    "normalization_id": "<string>",
    "normalized_length": 123,
    "sha256": "<string>"
  },
  "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>"
  },
  "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>",
    "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

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": 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",
  "performance": {
    "is_cache_hit": true,
    "queue_wait_ms": 123,
    "search_execution_ms": 123,
    "server_total_ms": 123
  },
  "query": {
    "kind": "protein_sequence",
    "normalization_id": "<string>",
    "normalized_length": 123,
    "sha256": "<string>"
  },
  "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>"
  },
  "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>",
    "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. 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.

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

include_attributes

enum<string>[] | null

Optional release-backed target attributes to include.

Maximum array length: 1

Available options:

record_id

limit

integer<int64>

default:25

Maximum ranked results to return.

Required range: 1 <= x <= 1000

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 by homology.target_spaces.create. 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[] | null

required

Show child attributes

Errors

Search for protein homology candidates in a batch

Reference

Endpoints

Search for protein homology candidates

Authorizations

Headers

Body

Response