---
title: Manage sessions
description: >-
  Create, list, get, update, and delete sessions with full SessionState
  schema
tags:
  - sessions
  - sessions
  - crud
---
These endpoints let you create, list, retrieve, update, and delete the sessions that hold a conversation and its full history — messages, tool calls, jobs, checkpoints, and version metadata — so a chat can outlive a single request and be resumed later. Start here to open a session before you run any turns against it in [Message execution](/docs/api/sessions-execute), and to inspect or tear one down afterward.

  intermediate
  15 min
  [Sessions overview](/docs/api/sessions-overview), [authentication](/docs/api/authentication)

## Sessions CRUD

A session stores a multi-turn conversation with its tool calls, jobs, artifacts and version metadata. Each write increments its `version`.

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

---

## List Sessions

`GET /api/v1/sessions` returns the caller's sessions, most recently active first ([reference](/docs/api/reference/get-v1-sessions)).

| Query | Default | Meaning |
|-------|---------|---------|
| `limit` | `50` | Page size, capped at 100 |
| `cursor` | none | The `nextCursor` from the previous page |
| `organizationId` | none | Only sessions in this organization |

The response is `{ sessions, hasMore, nextCursor? }`; each summary carries `id`, `title`, `messageCount`, `createdAt`, `updatedAt` and `lastActiveAt`.

---

## Create Session

`POST /api/v1/sessions` creates an empty session and returns `201` with `{ id, createdAt, chatId? }` ([reference](/docs/api/reference/post-v1-sessions)).

| Body field | Meaning |
|-----------|---------|
| `title` | Optional display title |
| `clientId` | Seeds the version vector; defaults to `web_<timestamp>` |
| `chatId` | Optional chat to bind the session to; echoed back only if the bind succeeds |
| `config.provider`, `config.model`, `config.tools` | Optional runtime settings stored in the session state |

```bash
curl -X POST "https://www.ivybiosciences.com/api/v1/sessions" \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "EGFR resistance scan"}'
```

---

## Get Session

`GET /api/v1/sessions/:sessionId` returns `{ id, title, version, schemaVersion, state, messageCount, createdAt, updatedAt, lastActiveAt }`, where `state` is the full `SessionState` below ([reference](/docs/api/reference/get-v1-sessions-sessionid)).

---

## Update Session

`PUT /api/v1/sessions/:sessionId` merges `state` and replaces `title`, then increments `version` ([reference](/docs/api/reference/put-v1-sessions-sessionid)). The write is conditioned on the version it read, so a concurrent writer gets `409` and should re-read before retrying.

---

## Delete Session

`DELETE /api/v1/sessions/:sessionId` deletes the session and returns `{ "success": true }` ([reference](/docs/api/reference/delete-v1-sessions-sessionid)).

---

## SessionState Schema

The main fields of the session state (the full type is `SessionState` in `@pleach/core`):

```ts
interface SessionState {
  id: string                          // UUIDv7
  version: number                     // Increments on every write
  schemaVersion: number
  userId: string
  organizationId?: string
  messages: Message[]                 // Conversation history
  pendingToolCalls: ToolCall[]
  completedToolCalls: ToolCall[]
  pendingJobs: PendingJob[]           // Jobs still running
  completedJobs: CompletedJob[]       // Finished jobs with results
  artifacts: ArtifactRef[]            // Generated files (PDB, SDF, etc.)
  provider: ProviderConfig            // Defaults to { type: "anthropic" }
  model: ModelConfig
  tools: ToolConfig                   // Defaults to { enabled: [] }
  versionVector: VersionVector        // Sync metadata
  createdAt: string                   // ISO 8601
  updatedAt: string                   // ISO 8601
  lastActiveAt: string                // ISO 8601
  extensions?: Record<string, unknown>
}
```

> Session state dates (`createdAt`, `updatedAt`, `lastActiveAt`) arrive as ISO 8601 strings, not `Date` objects, because the state is stored as JSONB in PostgreSQL.

## Read next

- [Sessions Overview](/docs/api/sessions-overview) — architecture and quick start
- [Message execution](/docs/api/sessions-execute) — SSE streaming
- [Sync protocol](/docs/api/sessions-sync) — version vectors
- [Checkpoints](/docs/api/sessions-checkpoints) — snapshot and rollback
