Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

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

Headers

Idempotency-Key
string
required

Retry identity for this semantic request, retained for 24 hours. Reuse it after ambiguous failures.

Maximum string length: 255
Rafflesia-API-Version
string

Optional dated contract pin. Omit to use the current 2026-08-08 homology contract.

Prefer
string

Transport wait policy: respond-async, wait=N (0–60 seconds), or wait=N with respond-async fallback.

Body

application/json
query
object
required

One typed biological query.

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.

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 <= 10000
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

Created

ok
boolean
required

Whether the operation succeeded.

provenance
object
required

Execution provenance.

warnings
object[] | null
required

Non-fatal warnings.

$schema
string<uri>
read-only

A URL to the JSON Schema for this object.

Example:

"https://example.com/schemas/EnvelopeHomologySearch.json"

data
object

Operation result data. Absent when the operation did not succeed.

error
object

Structured error information.

evidence
object

Mechanical evidence summary for agent inspection and chaining.