Skip to main content
The Rafflesia API is JSON over HTTPS. Every endpoint returns the same envelope, and every endpoint documented here is generated from the curated OpenAPI contract — the same contract the SDKs are generated from.

Base URL

https://api.rafflesia.ai

​
The published surface

The REST surface is deliberately small and grows one route at a time. A route is public only when it is declared in the API’s public-route manifest; everything else the engine serves is internal and is not part of this reference, the SDKs, or the generated CLI. Today that surface is homology search. The endpoint pages in this section are the complete published API — if a capability is documented in a guide but has no endpoint page here, it is not yet exposed as a public route.
The rafflesia CLI covers a much wider set of primitives than the published REST surface. Those commands are the supported way to reach them; the REST contract is what carries a stability promise.

​
Authentication

Send an API key as a bearer token. Create keys in the dashboard.
Requests are scoped to the organization that owns the key. A well-formed key on a resource outside its scope is refused as an authorization failure, not a bad credential.

​
Shape of a request

Most primitives are POST with a JSON body, including read-only ones. That is deliberate: the inputs are structured (multiple identifiers, budgets, release pins, source declarations), and a canonical JSON body is what makes provenance.input_hash reproducible.

​
Response headers

​
Idempotency

Every POST accepts an Idempotency-Key. Retrying with the same key returns the original result instead of creating a second job or object — which matters because a timeout tells you nothing about whether the work happened.

​
Errors

Failures use the envelope with ok: false and a typed error whose code is stable. The categories and their HTTP statuses are in Errors. Error bodies for transport-level problems follow application/problem+json; primitive-level failures come back in the standard envelope.

​
Pagination

List endpoints return an opaque next_cursor. Pass it back as cursor to continue. Do not construct or parse cursors — they encode server-side position and are not stable input.

​
Durable jobs

Long operations — structure prediction, background searches, exports — are submitted as jobs. The submit call returns a job id; poll the job endpoint until it reaches a terminal state, then read the content-addressed objects it produced.

​
Rate limits

Rate-limited requests return 429 with type: rate_limit_error. Back off and retry; the same request will succeed later.