---
title: "Ivy Biosciences Harness API (v1.0.0)"
description: "Session-based agent runtime for multi-turn AI orchestration with tool execution,
checkpointing, and real-time streaming.

## Authentication

All endpoints accept three auth methods (tried in order):

1. **Clerk JWT** — `Authorization: Bearer <clerk_session_token>` or `__session` cookie (browser sessions)
2. **ivy_ API key via Bearer** — `Authorization: Bearer ivy_xxx` (CLI / SDK — primary programmatic method)
3. **ivy_ API key via custom header** — `X-Ivy-Api-Key: ivy_xxx` (useful when Bearer is reserved for other tokens)

The two `ivy_` methods are equivalent. Generate API keys in the .bloom* dashboard under Settings → API Keys.
"
---

Every public endpoint, grouped by lifecycle. Internal routes are not published here.
Pages are regenerated from `content/docs/api/openapi.json` on every build.

> **Total:** 97 operations across 16 groups.

## Sessions

- [`GET /harness/sessions/{sessionId}/assets`](/docs/api/reference/get-harness-sessions-sessionid-assets) — List session assets
- [`GET /harness/sessions`](/docs/api/reference/get-harness-sessions) — List sessions
- [`GET /harness/sessions/{sessionId}`](/docs/api/reference/get-harness-sessions-sessionid) — Get a session
- [`GET /harness/sessions/{sessionId}/workspace`](/docs/api/reference/get-harness-sessions-sessionid-workspace) — Get a session's workspace
- [`GET /harness/sessions/{sessionId}/transcript`](/docs/api/reference/get-harness-sessions-sessionid-transcript) — Export session transcript
- [`POST /harness/sessions`](/docs/api/reference/post-harness-sessions) — Create a session
- [`PUT /harness/sessions/{sessionId}`](/docs/api/reference/put-harness-sessions-sessionid) — Update a session
- [`DELETE /harness/sessions/{sessionId}`](/docs/api/reference/delete-harness-sessions-sessionid) — Delete a session

## Execution

- [`GET /harness/sessions/{sessionId}/events`](/docs/api/reference/get-harness-sessions-sessionid-events) — Stream session events (SSE)
- [`POST /harness/sessions/{sessionId}/messages/sync`](/docs/api/reference/post-harness-sessions-sessionid-messages-sync) — Send a message and wait for the full reply
- [`POST /harness/sessions/{sessionId}/execute`](/docs/api/reference/post-harness-sessions-sessionid-execute) — Execute a turn

## Sync

- [`POST /harness/sessions/{sessionId}/sync`](/docs/api/reference/post-harness-sessions-sessionid-sync) — Sync session state

## Checkpoints

- [`GET /harness/sessions/{sessionId}/checkpoints`](/docs/api/reference/get-harness-sessions-sessionid-checkpoints) — List checkpoints
- [`POST /harness/sessions/{sessionId}/rollback`](/docs/api/reference/post-harness-sessions-sessionid-rollback) — Rollback to checkpoint

## Interrupts

- [`GET /harness/sessions/{sessionId}/interrupts`](/docs/api/reference/get-harness-sessions-sessionid-interrupts) — List pending interrupts
- [`POST /harness/sessions/{sessionId}/interrupt/{interruptId}/resolve`](/docs/api/reference/post-harness-sessions-sessionid-interrupt-interruptid-resolve) — Resolve an interrupt

## Tools

- [`GET /harness/tools`](/docs/api/reference/get-harness-tools) — List available tools
- [`GET /v1/tools`](/docs/api/reference/get-v1-tools) — List tools (public catalogue)
- [`GET /harness/tools/{name}`](/docs/api/reference/get-harness-tools-name) — Get a tool by name

## Jobs

- [`GET /api/v1/jobs`](/docs/api/reference/get-api-v1-jobs) — List your jobs
- [`GET /v1/jobs/{jobId}/artifacts`](/docs/api/reference/get-v1-jobs-jobid-artifacts) — Download a job's output files
- [`GET /v1/jobs/{jobId}/artifacts/list-verifications`](/docs/api/reference/get-v1-jobs-jobid-artifacts-list-verifications) — List a job's file verification records
- [`GET /v1/jobs/{jobId}/candidates`](/docs/api/reference/get-v1-jobs-jobid-candidates) — Read a job's study candidates
- [`GET /v1/jobs/{jobId}/checkpoints`](/docs/api/reference/get-v1-jobs-jobid-checkpoints) — Read a job's checkpoints
- [`GET /v1/jobs/{jobId}/curve-fits`](/docs/api/reference/get-v1-jobs-jobid-curve-fits) — Read a job's stored curve fits
- [`GET /v1/jobs/{jobId}/extractions`](/docs/api/reference/get-v1-jobs-jobid-extractions) — List a job's extracted files
- [`GET /v1/jobs/pricing`](/docs/api/reference/get-v1-jobs-pricing) — List job pricing
- [`GET /v1/jobs/{jobId}/readouts`](/docs/api/reference/get-v1-jobs-jobid-readouts) — Read a job's readouts
- [`GET /v1/jobs/{jobId}/snapshots/list`](/docs/api/reference/get-v1-jobs-jobid-snapshots-list) — List a job's snapshots
- [`GET /v1/jobs/{jobId}/download/{artifactType}`](/docs/api/reference/get-v1-jobs-jobid-download-artifacttype) — Get a download link for one of a job's files by type
- [`GET /v1/jobs/{jobId}/download/plate-map`](/docs/api/reference/get-v1-jobs-jobid-download-plate-map) — Download a job's plate map as CSV
- [`GET /v1/jobs/{jobId}/extract/pdb`](/docs/api/reference/get-v1-jobs-jobid-extract-pdb) — Read a PDB file from a job's ZIP output
- [`GET /v1/jobs/{jobId}/extract/sdf`](/docs/api/reference/get-v1-jobs-jobid-extract-sdf) — Read an SDF file from a job's ZIP output
- [`GET /v1/jobs/{jobId}/artifact-content`](/docs/api/reference/get-v1-jobs-jobid-artifact-content) — Read a job's result content
- [`GET /v1/jobs/{jobId}/context`](/docs/api/reference/get-v1-jobs-jobid-context) — Read a job's context counts
- [`GET /v1/jobs/{jobId}/manifest/latest`](/docs/api/reference/get-v1-jobs-jobid-manifest-latest) — Find a job's latest manifest
- [`GET /v1/jobs/{jobId}/lineage`](/docs/api/reference/get-v1-jobs-jobid-lineage) — Read a job's lineage
- [`GET /v1/jobs/{jobId}/manifest/fetch`](/docs/api/reference/get-v1-jobs-jobid-manifest-fetch) — Read a job's latest manifest
- [`GET /v1/jobs/{jobId}/plate`](/docs/api/reference/get-v1-jobs-jobid-plate) — Read a job's plate layout
- [`GET /v1/jobs/{jobId}/plate-types`](/docs/api/reference/get-v1-jobs-jobid-plate-types) — List plate types and suggestions
- [`GET /v1/jobs/{jobId}/procurement`](/docs/api/reference/get-v1-jobs-jobid-procurement) — Read a job's procurement items
- [`GET /v1/jobs/{jobId}/qc`](/docs/api/reference/get-v1-jobs-jobid-qc) — Read a job's plate QC badge
- [`GET /v1/jobs/{jobId}/qc/metrics`](/docs/api/reference/get-v1-jobs-jobid-qc-metrics) — Read a job's plate QC metrics
- [`GET /v1/jobs/batch`](/docs/api/reference/get-v1-jobs-batch) — Get several jobs by id
- [`GET /api/v1/jobs/{job_id}`](/docs/api/reference/get-api-v1-jobs-job-id) — Get job details
- [`GET /v1/jobs/{jobId}/events`](/docs/api/reference/get-v1-jobs-jobid-events) — Stream job events
- [`POST /v1/jobs/{jobId}/cancel`](/docs/api/reference/post-v1-jobs-jobid-cancel) — Cancel a job
- [`POST /api/v1/jobs`](/docs/api/reference/post-api-v1-jobs) — Submit a computation job
- [`POST /v1/jobs/{jobId}/fit-curves`](/docs/api/reference/post-v1-jobs-jobid-fit-curves) — Fit dose-response curves for a job
- [`POST /v1/jobs/{jobId}/lineage`](/docs/api/reference/post-v1-jobs-jobid-lineage) — Record a job's lineage
- [`POST /v1/jobs/{jobId}/resubmit`](/docs/api/reference/post-v1-jobs-jobid-resubmit) — Resubmit a job
- [`POST /v1/jobs/{jobId}/plate-config`](/docs/api/reference/post-v1-jobs-jobid-plate-config) — Save a job's plate type
- [`POST /v1/jobs/{jobId}/readouts`](/docs/api/reference/post-v1-jobs-jobid-readouts) — Save readouts for a job
- [`POST /v1/jobs/batch`](/docs/api/reference/post-v1-jobs-batch) — Submit a batch of jobs
- [`POST /v1/jobs/{jobId}/undo`](/docs/api/reference/post-v1-jobs-jobid-undo) — Undo a job's last plate update
- [`POST /v1/jobs/{jobId}/plate`](/docs/api/reference/post-v1-jobs-jobid-plate) — Save wells on a job's plate
- [`POST /v1/jobs/{jobId}/readouts/upload`](/docs/api/reference/post-v1-jobs-jobid-readouts-upload) — Upload a readout file to a job
- [`POST /v1/jobs/{jobId}/candidates`](/docs/api/reference/post-v1-jobs-jobid-candidates) — Record study candidates for a job
- [`POST /v1/jobs/{jobId}/artifacts/verify`](/docs/api/reference/post-v1-jobs-jobid-artifacts-verify) — Check output files against their SHA-256
- [`PATCH /v1/jobs/{jobId}/plate`](/docs/api/reference/patch-v1-jobs-jobid-plate) — Save wells on a job's plate (PATCH)
- [`PATCH /v1/jobs/{jobId}/fit-curves`](/docs/api/reference/patch-v1-jobs-jobid-fit-curves) — Refit curves with exclusions and decisions
- [`DELETE /v1/jobs/{jobId}/candidates`](/docs/api/reference/delete-v1-jobs-jobid-candidates) — Remove study candidates from a job

## Agent

- [`GET /agent/runs/{id}`](/docs/api/reference/get-agent-runs-id) — Fetch a previous run's execution trace
- [`GET /agent/health`](/docs/api/reference/get-agent-health) — Operational health for agent retry/backoff decisions
- [`GET /agent/whoami`](/docs/api/reference/get-agent-whoami) — Identify the caller, tier, and quota
- [`GET /orchestrate/{sessionId}`](/docs/api/reference/get-orchestrate-sessionid) — Read a session's background-job follow-up
- [`POST /agent/estimate`](/docs/api/reference/post-agent-estimate) — Preview cost + tool plan without executing
- [`POST /agent/feedback`](/docs/api/reference/post-agent-feedback) — Report the outcome of a previous run
- [`POST /orchestrate`](/docs/api/reference/post-orchestrate) — Execute the biomedical agent

## Benchmarking

- [`POST /bench`](/docs/api/reference/post-bench) — Benchmark the orchestrator (stateless)

## Lookup

- [`GET /v1/lookup/molecule/enhanced`](/docs/api/reference/get-v1-lookup-molecule-enhanced) — Analyze one molecule
- [`GET /v1/lookup/pubchem`](/docs/api/reference/get-v1-lookup-pubchem) — Search PubChem by compound name
- [`GET /v1/lookup/uniprot`](/docs/api/reference/get-v1-lookup-uniprot) — Search UniProt by protein name

## API Keys

- [`GET /user/api-keys`](/docs/api/reference/get-user-api-keys) — List your API keys, or read one key's usage
- [`POST /user/api-keys`](/docs/api/reference/post-user-api-keys) — Create an API key
- [`PUT /user/api-keys`](/docs/api/reference/put-user-api-keys) — Update an API key
- [`PATCH /user/api-keys`](/docs/api/reference/patch-user-api-keys) — Revoke, archive or move several API keys
- [`DELETE /user/api-keys`](/docs/api/reference/delete-user-api-keys) — Revoke an API key

## Audit

- [`GET /audit/chat-chain`](/docs/api/reference/get-audit-chat-chain) — List your chats for record verification
- [`GET /audit/manifest-feed`](/docs/api/reference/get-audit-manifest-feed) — List a project's manifest events
- [`GET /audit/chat-chain/{chatId}`](/docs/api/reference/get-audit-chat-chain-chatid) — Verify a chat's record chain
- [`GET /audit/session-chain/{sessionId}`](/docs/api/reference/get-audit-session-chain-sessionid) — Verify a session's record chain
- [`POST /audit/feed`](/docs/api/reference/post-audit-feed) — Query the audit activity feed

## Chat Completions

- [`POST /v1/chat/completions`](/docs/api/reference/post-v1-chat-completions) — Create a chat completion

## Compute

- [`POST /v1/sync/admet-quick`](/docs/api/reference/post-v1-sync-admet-quick) — Quick ADMET estimate
- [`POST /v1/sync/molecular-properties`](/docs/api/reference/post-v1-sync-molecular-properties) — Calculate molecular properties
- [`POST /v1/sync/similarity`](/docs/api/reference/post-v1-sync-similarity) — Compare two molecules
- [`POST /v1/sync/validate-smiles`](/docs/api/reference/post-v1-sync-validate-smiles) — Validate SMILES strings

## Payments

- [`GET /x402/ping`](/docs/api/reference/get-x402-ping) — Paid x402 service probe

## Sandbox

- [`GET /harness/sandbox/list`](/docs/api/reference/get-harness-sandbox-list) — List your sandboxes
- [`GET /harness/sandbox/{chatId}/export/{assetId}/download`](/docs/api/reference/get-harness-sandbox-chatid-export-assetid-download) — Get a download link for an exported file
- [`GET /harness/sandbox/{chatId}/manifest`](/docs/api/reference/get-harness-sandbox-chatid-manifest) — Get the sandbox file manifest
- [`GET /harness/sandbox/{chatId}/status`](/docs/api/reference/get-harness-sandbox-chatid-status) — Get sandbox status
- [`POST /harness/sandbox/create`](/docs/api/reference/post-harness-sandbox-create) — Create a sandbox for a chat
- [`POST /harness/sandbox/{chatId}/exec`](/docs/api/reference/post-harness-sandbox-chatid-exec) — Run a shell command
- [`POST /harness/sandbox/{chatId}/tool/{toolName}`](/docs/api/reference/post-harness-sandbox-chatid-tool-toolname) — Run a sandbox tool
- [`POST /harness/sandbox/{chatId}/terminate`](/docs/api/reference/post-harness-sandbox-chatid-terminate) — Terminate the sandbox