Skip to main content
    Ivy Biosciences Docs/Call the platform/API/Sessions API/Sessions overview

    Sessions overview

    Run multi-turn AI sessions over HTTP that keep their history, call tools, pause for approval, and roll back to any checkpoint.

    sessionssessionsstreaming

    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.

    Difficulty

    intermediate

    Time

    10 min

    Prerequisites

    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

    # 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'

    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 lists both.

    Endpoints

    MethodPathDescription
    GET/api/v1/sessionsList sessions
    POST/api/v1/sessionsCreate session
    GET/api/v1/sessions/:idGet session state
    PUT/api/v1/sessions/:idUpdate session
    DELETE/api/v1/sessions/:idDelete session
    POST/api/v1/sessions/:id/executeExecute message (SSE). Deprecated: answers 410
    POST/api/v1/sessions/:id/messages/syncExecute message, one JSON response. Deprecated: answers 410
    POST/api/v1/sessions/:id/syncSync version vectors
    GET/api/v1/sessions/:id/checkpointsList checkpoints
    POST/api/v1/sessions/:id/rollbackRoll back to a checkpoint
    POST/api/v1/sessions/:id/interrupt/:interruptId/resolveAnswer an approval interrupt
    GET/api/v1/toolsList available tools
    GET/api/v1/tools/:nameGet 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

    AdapterEnvironmentUse Case
    MemoryAdapterTestingEphemeral sessions
    IndexedDBAdapterBrowserOffline-first client storage
    SupabaseAdapterServerPersistent PostgreSQL storage

    Was this page helpful?

    On this page

    On this page

    Loading...