Sessions overview
Run multi-turn AI sessions over HTTP that keep their history, call tools, pause for approval, and roll back to any checkpoint.
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, Message execution, Sync protocol, Checkpoints, Tools registry) each cover one piece of it.
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 to browse and test all sessions endpoints directly from your browser.
Quick Start
Base URL
All sessions endpoints are served by the web app under /api/v1:
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 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 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 — create, list, update, delete sessions
- Message execution — SSE streaming and StreamEvent reference
- Sync protocol — version vectors and conflict resolution
- Checkpoints — snapshot and rollback
- Tools registry — list and inspect available tools
- Authentication — API key and JWT setup
Was this page helpful?