---
title: Sessions overview
description: >-
  Run multi-turn AI sessions over HTTP that keep their history, call tools,
  pause for approval, and roll back to any checkpoint.
tags:
  - sessions
  - sessions
  - streaming
---
The sessions API lets you run multi-turn AI conversations that remember their own history, execute tools, pause for your approval, and roll back to any earlier moment. Reach for it when a single request/response call isn't enough — when you need a durable, resumable session you can stream, sync across devices, and debug after the fact. This page is the map for that surface; the sibling pages ([Manage sessions](/docs/api/sessions-manage), [Message execution](/docs/api/sessions-execute), [Sync protocol](/docs/api/sessions-sync), [Checkpoints](/docs/api/sessions-checkpoints), [Tools registry](/docs/api/sessions-tools)) each cover one piece of it.

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

## How it works

Each session is persistent: it keeps its message history, checkpoints, and version vectors, and streams each turn over SSE. That is what makes tool execution, approval interrupts, and rollback possible across turns.

> **Try it live:** Open the [Interactive API Reference](/docs/api/reference) to browse and test all sessions endpoints directly from your browser.

## Quick Start

**cURL**

```bash
# 1. Create a session
SESSION=$(curl -s -X POST https://www.ivybiosciences.com/api/v1/sessions \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "BRCA1 structure"}' | jq -r '.id')

# 2. Execute a message (SSE stream)
curl -N -X POST "https://www.ivybiosciences.com/api/v1/sessions/$SESSION/execute" \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Predict the structure of BRCA1"}'

# 3. List checkpoints
curl -s "https://www.ivybiosciences.com/api/v1/sessions/$SESSION/checkpoints" \
  -H "Authorization: Bearer ivy_your_key" | jq'
```

**TypeScript**

```ts
const BASE = "https://www.ivybiosciences.com/api/v1"
const headers = {
  Authorization: "Bearer ivy_your_key",
  "Content-Type": "application/json",
}

// 1. Create a session
const { id } = await (
  await fetch(`${BASE}/sessions`, {
    method: "POST",
    headers,
    body: JSON.stringify({ title: "BRCA1 structure" }),
  })
).json()

// 2. Execute a message and read the SSE stream (deprecated: this endpoint answers 410 Gone)
const res = await fetch(`${BASE}/sessions/${id}/execute`, {
  method: "POST",
  headers,
  body: JSON.stringify({ content: "Predict the structure of BRCA1" }),
})
const reader = res.body!.getReader()
const decoder = new TextDecoder()
for (let r = await reader.read(); !r.done; r = await reader.read()) {
  process.stdout.write(decoder.decode(r.value))
}

// 3. List checkpoints
const checkpoints = await (await fetch(`${BASE}/sessions/${id}/checkpoints`, { headers })).json()
```

## Base URL

All sessions endpoints are served by the web app under `/api/v1`:

```
https://www.ivybiosciences.com/api/v1/sessions
```

> The sessions API is part of the web app, not the compute backend. If you self-host, it deploys with the web app.

## Authentication

Every sessions endpoint requires a signed-in session token or an `ivy_` API key in the `Authorization: Bearer` header. Session CRUD and the tools routes use the `standard` burst limit; execute and sync use `light`. [Rate Limits](/docs/api/rate-limits) lists both.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/sessions` | List sessions |
| `POST` | `/api/v1/sessions` | Create session |
| `GET` | `/api/v1/sessions/:id` | Get session state |
| `PUT` | `/api/v1/sessions/:id` | Update session |
| `DELETE` | `/api/v1/sessions/:id` | Delete session |
| `POST` | `/api/v1/sessions/:id/execute` | Execute message (SSE). Deprecated: answers 410 |
| `POST` | `/api/v1/sessions/:id/messages/sync` | Execute message, one JSON response. Deprecated: answers 410 |
| `POST` | `/api/v1/sessions/:id/sync` | Sync version vectors |
| `GET` | `/api/v1/sessions/:id/checkpoints` | List checkpoints |
| `POST` | `/api/v1/sessions/:id/rollback` | Roll back to a checkpoint |
| `POST` | `/api/v1/sessions/:id/interrupt/:interruptId/resolve` | Answer an approval interrupt |
| `GET` | `/api/v1/tools` | List available tools |
| `GET` | `/api/v1/tools/:name` | Get tool schema |

## Key Concepts

### Sessions

A session is a persistent container for a multi-turn AI conversation. It stores messages, tool calls, pending jobs, and version metadata. Sessions use UUIDv7 identifiers for time-ordered sorting.

### StreamEvents

The execute endpoint streams typed Server-Sent Events for text generation, tool calls, jobs, sub-agents, citations, interrupts and sync. The [event reference](/docs/api/sessions-execute#streamevent-types) lists them.

### Version Vectors

Each session carries a version vector (hybrid logical clock per client) enabling offline-first editing with last-writer-wins conflict resolution at the message level.

### Sub-Agents

The LLM can delegate complex subtasks to independent child agents via the `spawn_agent` tool. Sub-agents are short-lived agents that execute a task with their own tool access, returning results to the parent conversation. Sub-agent lifecycle is tracked via 4 dedicated StreamEvent types (`subagent.spawned`, `subagent.progress`, `subagent.completed`, `subagent.failed`).

### Checkpoints

Automatic snapshots are taken at key moments (message completion, tool execution, job completion, sub-agent completion, sync). You can roll back to any checkpoint for time-travel debugging.

## Storage Backends

| Adapter | Environment | Use Case |
|---------|-------------|----------|
| `MemoryAdapter` | Testing | Ephemeral sessions |
| `IndexedDBAdapter` | Browser | Offline-first client storage |
| `SupabaseAdapter` | Server | Persistent PostgreSQL storage |

## Read next

- [Manage sessions](/docs/api/sessions-manage) — create, list, update, delete sessions
- [Message execution](/docs/api/sessions-execute) — SSE streaming and StreamEvent reference
- [Sync protocol](/docs/api/sessions-sync) — version vectors and conflict resolution
- [Checkpoints](/docs/api/sessions-checkpoints) — snapshot and rollback
- [Tools registry](/docs/api/sessions-tools) — list and inspect available tools
- [Authentication](/docs/api/authentication) — API key and JWT setup
