Migration Guide

This page tells you what changed, what's going away, and how to move to the current API without breaking your integration. Reach for it when you're upgrading, chasing down a deprecation notice, or turning on a newer surface like the Harness Sessions API. It covers how each API surface is versioned, a dated changelog, deprecation timelines, and step-by-step upgrade paths.

Migration Guide

API versioning, changelog, and upgrade paths for the Ivy Biosciences platform.

API Versioning

The platform has three API surfaces with independent versioning:

Changelog

2026-03 (Current)

• Added Harness Sessions API with 26 StreamEvent types
• Added SSE Streaming for harness execution and job event proxy
• Added Batch API with fan-out model (single tool, multiple items)
• Added API key management endpoints (create, list, revoke)
• Added 3 regulatory science tools: drugcentral_regulatory, chembl_drug_warnings, pubchem_regulatory
• Added ENCODE and STRING database tools
• Corrected WebSocket close code semantics (4001=too many connections, 4003=auth failed)
• Fixed API key prefix documentation (ivy_ not ivy_sk_)

2026-02

• Added Proxy Endpoints for SSE and asset serving
• Added SAFE fragment ingestion for generative chemistry tools
• Added pipeline integrity (job hash verification)
• Added external data rollups with freshness system

2026-01

• Added passport system (Compound, Target, Safety, Literature, Therapeutic Area)
• Added canvas card system with custom renderers
• Added slug-based URL routing for projects, chats, and jobs
• Added UUID-to-slug migration with middleware resolver

2025-12

• Initial REST API v1 release
• WebSocket protocol for real-time job updates
• Guest access with rate-limited trial tools
• TypeScript SDK source (@ivybiosciences/sdk 0.1.0) with React hooks; not published to npm

Deprecation Notices

Handling Deprecated Tools

Deprecated tools return a deprecation notice in the response:

{
  "status": "COMPLETED",
  "result": {
    "deprecated": true,
    "replacedBy": ["drugcentral_regulatory", "chembl_drug_warnings"],
    "message": "This tool is deprecated. Please use the replacement tools."
  }
}

Upgrade Paths

Enabling the Harness Sessions API

The Harness API is on by default. FEATURE_HARNESS_V2_RUNTIME defaults to true; check that your deployment does not set it to false:

Step 1: Confirm the feature flag

# .env.local (the default; omit the line to get the same result)
FEATURE_HARNESS_V2_RUNTIME=true

Step 2: Run database migrations

supabase db push

This creates the harness_sessions, harness_checkpoints, and harness_errors tables.

Step 3: Job callbacks

No extra configuration is needed: the deployment delivers compute-backend job status to harness sessions itself.

Step 4: Verify

curl https://your-domain.com/api/harness/tools \
  -H "Authorization: Bearer ivy_your_key"

Enabling Proxy Endpoints

Proxy endpoints route storage and event traffic through your Next.js server, so clients never connect to Modal or S3 directly. They are always on; no flag enables them.

Step 1: Verify job reads

# Should return the job record
curl https://your-domain.com/api/v1/jobs/job_abc123 \
  -H "Authorization: Bearer ivy_your_key"

Step 2: Verify SSE proxy

# Should stream job events as SSE (needs a signed-in session, not an API key)
curl -N https://your-domain.com/api/v1/jobs/job_abc123/events \
  -H "Authorization: Bearer <clerk_session_token>"

Migrating from Direct WebSocket to SSE

External clients cannot open a job WebSocket; the wss:// URL on the old API host does not serve external traffic. Follow jobs with the SSE job event proxy instead:

const source = new EventSource(`/api/v1/jobs/${jobId}/events`) // same-origin session cookie

The stream needs a signed-in session (the cookie, or a Clerk session token as Authorization: Bearer); an ivy_ API key alone is refused. From a server with only an API key, poll GET /api/v1/jobs/{jobId} instead.

See SSE Streaming for the full client implementation.

Breaking Change Policy

• Additive changes (new endpoints, new response fields, new tools) are shipped without version bumps
• Breaking changes (removed fields, changed semantics, removed endpoints) trigger a new API version
• Deprecation period: minimum 3 months before removal
• Communication: deprecation notices in response headers and the changelog above

Read next

• Authentication — auth methods
• Rate Limits — current rate limits