---
title: SDK Overview
description: 'Nothing to install: @ivybiosciences/sdk is a specification, not a released package. Call the platform today over REST, the ivybloom CLI or MCP.'
---

`@ivybiosciences/sdk` is a planned TypeScript client for the platform. It is a specification, not a released package: the pages in this section describe the interface it is planned to have, so you can see how it will wrap job submission, progress, and result downloads in typed methods. Today the only scheduled releases are the `@pleach/*` packages and the [ivybloom CLI](/docs/cli). To call the platform today, use the [REST API](/docs/api/rest-jobs), the [ivybloom CLI](/docs/cli), or the [MCP server](/docs/cli/mcp). The per-module specifications are linked under [Related Docs](#related-docs): the [Client](/docs/api/sdk-client), [Jobs](/docs/api/sdk-jobs), [Artifacts](/docs/api/sdk-artifacts), [real-time updates](/docs/api/sdk-websocket), [React Hooks](/docs/api/sdk-react), [Types & Constants](/docs/api/sdk-types), and [Errors](/docs/api/sdk-errors).

## @ivybiosciences/sdk

Planned TypeScript SDK for the IvyAI Computational Biology Platform.

> The planned SDK wraps the [REST API](/docs/api/rest-jobs) and the [SSE job event stream](/docs/api/realtime-sse#job-event-proxy-sse). For session-based AI orchestration, see the [Harness API](/docs/api/sessions-overview). For direct HTTP access, see the [REST API](/docs/api/rest-jobs).

## SDK vs REST vs Harness

| Feature | SDK (planned) | REST API | Harness |
|---------|-----|----------|---------|
| Language | TypeScript/JS | Any (HTTP) | Any (HTTP/SSE) |
| Auth | API key or JWT | API key or JWT; [orchestrate](/docs/api#guest-curl) also takes no key | API key or JWT |
| Job submission | `ivy.jobs.submit()` | `POST /api/v1/jobs` | Via tool execution in sessions |
| Real-time | Planned progress subscriptions | SSE job stream | SSE event stream |
| React hooks | Yes (`/react` subpath) | No | Yes (`@pleach/core/react`) |
| Session persistence | No | No | Yes (checkpoints, sync) |
| Use case | Client apps, scripts | Server integrations, CI/CD | AI-powered workflows |

## Status

> **Planned specification.** `@ivybiosciences/sdk` is not released, and there is no package to install. This page describes the SDK's planned interface. To call the platform today, use the [REST API](/docs/api/rest-jobs), the [ivybloom CLI](/docs/cli), or the [MCP server](/docs/cli/mcp).

There is no install command, because nothing is published. Code samples on these pages that import `@ivybiosciences/sdk` show the planned interface and will not run.

| You want to | Use today |
|-------------|-----------|
| Submit and follow jobs from any language | [REST API](/docs/api/rest-jobs) and the [SSE job event stream](/docs/api/realtime-sse#job-event-proxy-sse) |
| Work from a terminal or script | [ivybloom CLI](/docs/cli) |
| Give an AI agent access to the platform | [MCP server](/docs/cli/mcp) (`ivybloom mcp`) |
| Build AI-powered workflows | [Harness API](/docs/api/sessions-overview) |

## Quick Start (planned interface)

**TypeScript**

```ts
import { createIvyClient } from "@ivybiosciences/sdk"

const ivy = createIvyClient({ apiKey: "ivy_your_key_here" })

const result = await ivy.jobs.submitAndWait({
  toolName: "esmfold",
  parameters: { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
  analysisLevel: "comprehensive",
})

console.log(result.status)       // "COMPLETED"
console.log(result.result)       // { plddt_mean: 0.87, num_residues: 342 }
console.log(result.presignedUrl) // S3 download URL for the PDB file
```

**Python**

```python
import requests

BASE_URL = "https://www.ivybiosciences.com"
headers = {"Authorization": "Bearer ivy_your_key_here"}

# Submit a structure prediction job
job = requests.post(f"{BASE_URL}/api/v1/jobs", json={
    "tool_name": "esmfold",
    "tool_input_parameters": {"protein_sequence": "MKFLILLFNILCLFPVLAADNH"},
    "analysis_level": "comprehensive",
}, headers=headers).json()

import time
while True:
    status = requests.get(
        f"{BASE_URL}/api/v1/jobs/{job['id']}", headers=headers
    ).json()
    if status["status"] in ("completed", "success", "failure", "failed", "cancelled"):
        break
    time.sleep(3)

results = requests.get(
    f"{BASE_URL}/api/v1/jobs/{job['id']}", headers=headers
).json()
```

**React**

```tsx
import { IvyProvider, useIvyJob } from "@ivybiosciences/sdk/react"

function StructurePredictor() {
  const { submit, status, isLoading } = useIvyJob()

  const predict = () => {
    submit(
      "esmfold",
      { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
      { analysisLevel: "comprehensive" },
    )
  }

  return (
    <div>
      <button onClick={predict} disabled={isLoading}>
        Predict Structure
      </button>
      {status?.status === "COMPLETED" && (
        <p>pLDDT: {String(status.result?.plddt_mean)}</p>
      )}
    </div>
  )
}

// Wrap your app with the provider
function App() {
  return (
    `<IvyProvider getToken={() => clerk.session!.getToken({ template: "ivy_api" })}> <StructurePredictor /> </IvyProvider>`
  )
}
```

## Authentication Modes

| Mode | Use Case | Auth Header |
|------|----------|-------------|
| API Key (`apiKey`) | Server-side, CLI, scripts | `Authorization: Bearer ivy_...` |
| JWT (`getToken`) | Browser, mobile (Clerk) | `Authorization: Bearer eyJ...` |

The SDK always sends a credential. To try the platform without one, use the keyless request in [Guest curl](/docs/api#guest-curl).

## Package Exports

```ts
// Core SDK
import { createIvyClient, IvyClient } from "@ivybiosciences/sdk"

// Domain managers
import { JobManager, ArtifactManager, IvyWebSocket } from "@ivybiosciences/sdk"

// Error classes
import { IvyApiError, IvyTimeoutError, IvyWebSocketError } from "@ivybiosciences/sdk"

// Types
import type { IvyClientConfig, JobProgress, SubmitJobParams } from "@ivybiosciences/sdk"

// Constants
import { JOB_TYPES, DEFAULT_BASE_URL } from "@ivybiosciences/sdk"
import type { JobType } from "@ivybiosciences/sdk"

// React hooks (subpath export)
import { IvyProvider, useIvyClient, useIvyJob, useIvyWebSocket } from "@ivybiosciences/sdk/react"
```

## Architecture

```
IvyClient
├── jobs: JobManager         — Submit, poll, wait, list, delete
├── artifacts: ArtifactManager — Download presigned S3 URLs
└── websocket: IvyWebSocket  — Real-time progress subscriptions
```

## Supported Tools

See [Types & Constants](/docs/api/sdk-types#job_types-registry) for the complete registry of the computational tools the SDK supports, including:

- **Structure Prediction**: ESMFold, ESM3
- **Molecular Docking**: DiffDock, REINVENT
- **Property Prediction**: ADMET AI, GraphSol, DeepSol, ProTox-3
- **Database Screening**: RDKit, ZINC, PubChem
- **Sequence Analysis**: BLAST, AiZynthFinder
- **Literature Mining**: BioBERT

## Related Docs

- [Client Reference](/docs/api/sdk-client)
- [Jobs Reference](/docs/api/sdk-jobs)
- [WebSocket Reference](/docs/api/sdk-websocket)
- [Guest curl](/docs/api#guest-curl) — the keyless first call, no SDK needed
- [Artifacts Reference](/docs/api/sdk-artifacts)
- [React Hooks](/docs/api/sdk-react)
- [Types & Constants](/docs/api/sdk-types)
- [Errors Reference](/docs/api/sdk-errors)
- [Integration Examples](/docs/api/sdk-integration-examples)