Endpoint reference

Summary of the v1 surface. Full machine-readable spec at tools.ranomics.com/api/v1/openapi.json and interactive Swagger docs at /api/v1/docs.

Authentication

Bearer tokens, org-scoped

Every request other than openapi.json requires a Bearer token in the Authorization header. Tokens are issued from the account page on tools.ranomics.com and scoped to your organization. Two roles: Member (read + write) and Viewer (read only).

Authorization: Bearer rk_live_...

Base URL: https://tools.ranomics.com/api/v1

Endpoints

Surface summary

Method	Path	Purpose
GET	/targets	List calibrated targets (filterable). Empty at launch.
POST	/experiments	Create an experiment from spec + sequences. Returns experiment_id and Draft status.
POST	/experiments/cost-estimate	Non-binding ballpark from spec only. Returns concrete USD for calibrated targets, range + scoping_url for custom.
GET	/experiments/{id}	Cheap status snapshot. Returns status, results_status, last_transition_at, status_log.
GET	/experiments/{id}/quote	Scoped quote with line items, total_usd, and valid_until.
POST	/quotes/{id}/confirm	Accept the quote and advance to WaitingForMaterials. Triggers library construction.
GET	/experiments/{id}/results	Full result payload. Meaningful only when results_status is partial or all.
GET	/openapi.json	Machine-readable OpenAPI spec. Unauthenticated.

Experiment lifecycle

Status FSM

Each experiment transitions through nine states. Conventions mirror Adaptyv's Foundry API where they fit; the wet-lab stages diverge to reflect yeast display reality (LibraryConstruction, Sorting, NGS, DataAnalysis).

Draft
  ↓ POST /experiments/{id}/submit  (or auto-submit on /experiments POST)
WaitingForConfirmation
  ↓ scoping (Leo for custom, auto for calibrated)
QuoteSent
  ↓ POST /quotes/{id}/confirm
WaitingForMaterials
  ↓
LibraryConstruction
  ↓
Sorting
  ↓
NGS
  ↓
DataAnalysis
  ↓
InReview
  ↓
Done

(Canceled is reachable from any pre-Done state.)

results_status

Cheap results-readiness signal

An orthogonal field on the status response. Lets agents avoid fetching the full result payload just to check whether anything is available yet.

none

No results yet. Continue polling status; do not call /results.

partial

At least one sort round has results. The sequences array is populated but may grow.

all

All planned rounds and analyses complete. The result payload is final.

Webhook delivery

Signed POSTs on status transitions

Pass webhook_url at experiment creation. We POST to it on every status change. Signature header lets you verify authenticity and protects against replay (timestamp is in the signed payload).

POST <your webhook_url>
Content-Type: application/json
X-Ranomics-Signature: t=1748983212,v1=<hmac-sha256 hex>

{
  "experiment_id": "exp_01HZ...",
  "prev_status": "Sorting",
  "new_status": "NGS",
  "timestamp": "2026-06-04T14:13:32Z"
}

Delivery is async with exponential backoff and a 5-attempt cap over 24 hours. Failures never block experiment status transitions. Verify the signature with HMAC-SHA256(secret, "{t}.{body}") using the webhook secret from your account page.

Operational

Rate limits, idempotency, versioning

Rate limit

60 requests per minute per token. 429 on exceed, with Retry-After header.

Idempotency

Pass Idempotency-Key header on POSTs. Retries within 24h dedupe to the same experiment_id. Safe to wrap in tool-call retry loops.

Versioning

Path-prefixed (/api/v1/). Breaking changes bump the prefix. Deprecation announced via Sunset header and email to active token holders with a minimum 90-day window.

Errors

JSON envelope: {"error": {"code": "...", "message": "...", "field": "..."}}. Standard HTTP status codes; 4xx for client error, 5xx for server error.