createIvyClient factory, IvyClientConfig, authentication providers, and the IvyClient class

The IvyClient is the root object you construct once and reuse for everything else in the SDK — it holds your authentication (API key or JWT), handles HTTP requests and retries, and exposes the domain managers (jobs, artifacts, websocket) that the sibling reference pages document. Reach for this page when you're setting up the client, choosing an auth mode, or configuring timeouts and retries; once you have an instance, the Jobs reference covers the calls you'll make most.

SDK Client Reference

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, the ivybloom CLI, or the MCP server.

The IvyClient is the primary entry point for the SDK. It orchestrates authentication, HTTP communication, WebSocket connections, and provides access to domain-specific managers.

`createIvyClient(config)`

The recommended way to create an IvyClient instance. Validates that exactly one auth method is provided.

function createIvyClient(config: IvyClientConfig): IvyClient

Parameters:

Parameter	Type	Required	Description
`config`	`IvyClientConfig`	Yes	Client configuration (see below)

Throws: Error if neither apiKey nor getToken is provided.

Returns: A fully configured IvyClient instance.

Examples

// API Key (server-side)
const ivy = createIvyClient({ apiKey: "ivy_your_key_here" })

// JWT (browser with Clerk)
const ivy = createIvyClient({
  getToken: () => clerk.session!.getToken({ template: "ivy_api" }),
  timeout: 60_000,
})

// Custom endpoint
const ivy = createIvyClient({
  apiKey: "ivy_test_key",
  baseUrl: "http://localhost:8000/api/v1",
  retries: 5,
})

`IvyClientConfig`

Configuration interface for creating an IvyClient.

Field	Type	Default	Description
`baseUrl`	`string`	`DEFAULT_BASE_URL` (`https://www.ivybiosciences.com/api/v1`)	API base URL including `/api/v1` path prefix
`apiKey`	`string`	—	API key with `ivy_` prefix. Mutually exclusive with `getToken`
`getToken`	`() => Promise<string \| null>`	—	Async JWT provider. Mutually exclusive with `apiKey`
`timeout`	`number`	`30000`	HTTP request timeout in milliseconds
`retries`	`number`	`3`	Max retry attempts for transient failures (429, 5xx)
`onError`	`(error: Error) => void`	—	Global error callback for unhandled SDK errors

`IvyClient`

Properties

Property	Type	Description
`jobs`	`JobManager`	Job submission, status polling, and lifecycle management
`artifacts`	`ArtifactManager`	Artifact download from presigned S3 URLs
`websocket`	`IvyWebSocket`	Raw WebSocket access for custom real-time subscriptions

Constructor

new IvyClient(config: IvyClientConfig)

Prefer using createIvyClient() which adds validation.

Calling without a key

Every client on this page needs an API key or a Clerk JWT. To try the platform without a key, skip the SDK and send the keyless orchestrate request in Guest curl; its limits are stated there.

Authentication Flow

Both auth types feed the AuthProvider, whose getHeaders() runs in the HTTP middleware before every request to the IvyAI API.

The auth provider's getHeaders() is called before every request, ensuring tokens are always fresh.

SDK client