---
title: Migration Guide
description: 'How each API surface is versioned, what every deprecation replaces, and the upgrade steps for the Harness Sessions API, proxy endpoints and SSE job events.'
tags:
  - guides
  - migration
  - versioning
---
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](/docs/api/sessions-overview). It covers how each API surface is versioned, a dated changelog, deprecation timelines, and step-by-step upgrade paths.

  intermediate
  10 min
  [authentication](/docs/api/authentication)

## Migration Guide

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

---

## API Versioning

The platform has three API surfaces with independent versioning:

| Surface | Base Path | Current Version | Strategy |
|---------|-----------|:---:|----------|
| REST API | `/api/v1/` | v1 | URL-based versioning |
| Harness Sessions | `/api/harness/` | v1 | Unversioned (feature-flagged) |
| Job events (SSE) | `/api/v1/jobs/{jobId}/events` | v1 | Versioned with the REST API |

> The REST API uses URL-based versioning (`/api/v1/`). A breaking change introduces a new version prefix while the old version remains available for a deprecation period.

---

## Changelog

### 2026-03 (Current)

- Added [Harness Sessions API](/docs/api/sessions-overview) with 26 StreamEvent types
- Added [SSE Streaming](/docs/api/realtime-sse) for harness execution and job event proxy
- Added [Batch API](/docs/api/rest-batch) 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](/docs/api/rest-artifacts) 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

| Feature | Deprecated | Removal | Replacement |
|---------|:---:|:---:|-------------|
| Direct Modal URL in client-side code | 2026-02 | 2026-06 | [Proxy Endpoints](/docs/api/rest-artifacts) (always on) |
| Wikipedia `clinical_regulatory` tool | 2026-03 | 2026-06 | `drugcentral_regulatory`, `chembl_drug_warnings`, `pubchem_regulatory` |
| `ivy_sk_` API key prefix in docs | 2026-03 | — | Correct prefix is `ivy_` |

### Handling Deprecated Tools

Deprecated tools return a deprecation notice in the response:

```json
{
  "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

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

**Step 2**: Run database migrations

```bash
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

```bash
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

```bash
# 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

```bash
# 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:

```ts
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](/docs/api/realtime-sse) 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](/docs/api/authentication) — auth methods
- [Rate Limits](/docs/api/rate-limits) — current rate limits