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

    Manage sessions

    Create, list, get, update, and delete sessions with full SessionState schema

    sessionssessionscrud

    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, and to inspect or tear one down afterward.

    Difficulty

    intermediate

    Time

    15 min

    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 to browse and test all sessions endpoints.


    List Sessions

    GET /api/v1/sessions returns the caller's sessions, most recently active first (reference).

    QueryDefaultMeaning
    limit50Page size, capped at 100
    cursornoneThe nextCursor from the previous page
    organizationIdnoneOnly 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).

    Body fieldMeaning
    titleOptional display title
    clientIdSeeds the version vector; defaults to web_<timestamp>
    chatIdOptional chat to bind the session to; echoed back only if the bind succeeds
    config.provider, config.model, config.toolsOptional runtime settings stored in the session state
    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).


    Update Session

    PUT /api/v1/sessions/:sessionId merges state and replaces title, then increments version (reference). 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).


    SessionState Schema

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

    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.

    Was this page helpful?

    On this page

    On this page

    Loading...