Ivy Biosciences API

The API is the programmatic way into the platform. Start with a public curl request when you want to try one natural-language run without an account; use authenticated REST, Harness, SDK, or real-time surfaces when you need persistence, higher quota, or an agent integration. This page helps you choose the surface, then points to the per-operation Reference.

Guest curl

The public orchestrator accepts a prompt without an API key. Guest calls are limited to 18 calls or $1.00 of compute per IP per UTC day, whichever runs out first, allowlisted to the guest catalog, and return named SSE events by default. This is the same request shown on the public homepage.

Reading the output

The default response is a stream of named SSE events — event: text_delta with a data: JSON line per token. That is what a program wants. If you are a person watching the terminal, add ?format=text and the same events arrive rendered as labelled text instead:

─── session ────────────────────────────────────────
  0192f0c4-1111-7000-8000-abcdef012345

─── tool ▸ clinpgx_variant_annotation ──────────────
  args: {"gene":"DPYD","variant":"rs3918290"}

✓ tool ◂ clinpgx_variant_annotation  [done] · 1.4s
  Annotations 25  ·  Drugs 1  ·  Gene DPYD

DPYD *2A is a no-function allele. For a heterozygous carrier, CPIC
recommends starting fluoropyrimidines at 50% of the standard dose.
─── sources ────────────────────────────────────────
  [1] CPIC Guideline for DPYD Genotype and Fluoropyrimidine Dosing — PMID:29152729

─── done ───────────────────────────────────────────
  session 0192f0c4-1111-7000…  ·  1 step  ·  tools 1 ok  ·  1 source

Two details make this match what the web app shows you. Tool results print the same named metrics the canvas card prints — Annotations 25 · Drugs 1 · Gene DPYD comes from the card's own extractor, not a second summary — and each call carries the chat transcript's status tag: [done], [reused] (a duplicate call that reused an earlier result), [blocked] (a guard refused it) or [failed]. A result that was offloaded to S3 is named as a pointer (⋯ 14 rows, offloaded — read it with get_data) rather than printed as though the envelope were the finding.

The glyphs are a legend: ▸ a tool call starting, ✓ / ↺ / ! / ✗ a result (done / reused / blocked / failed), ◷ an async job dispatched, ⋯ provider thinking and offload pointers. Colour is emitted only when stdout is a terminal and NO_COLOR is unset, so a pipe or a redirect into a log file always gets plain bytes. ?format=sse pins the default, and a caller that cannot set a query string can send {"outputFormat":"text"} in the body instead — the content, events and billing are identical either way.

For signed-in callers (API key or session), the JSON response and the stream's done event also carry usage: the credits this response's model calls debited (usage.llm.credits), how many calls were billed (calls, with settled as succeeded of attempted) and how they were priced (basis). GPU job credits settle when each job finishes and are not included. Guest calls have no usage. Every field is described in the orchestrate reference.

Quickstart

# Submit a protein structure prediction job
curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "esmfold",
    "tool_input_parameters": {"protein_sequence": "MKFLILLFNILCLFPVLAADNH"}
  }'

API surfaces

Auto-generated reference

Every endpoint has its own page with request and response schemas and ready-to-paste curl, JavaScript, and Python samples. The reference is generated from the OpenAPI spec, so it matches what is deployed. The reference lists every public operation and nothing else. Agents can read the machine-readable specs directly: GET /api/v1/openapi.json for the /api/v1 contract and GET /api/v1/openapi-harness.json for the session, job, sandbox and audit operations.

Browse by section

Taken together, these surfaces cover the full arc of working with the platform: try a guest prompt over curl, submit and manage authenticated compute jobs over REST, run stateful multi-turn AI sessions through the Harness, and watch either unfold live over SSE. Most integrations start with the guest request, then add credentials when the run needs persistence or more quota.