Sessions API

This document outlines the API endpoints for managing user sessions in PySpur. Sessions are used to maintain conversation history in agent spurs. Each session is tied to a user and a spur. For quick testing purposes, use the create test user endpoint. It also creates a default test user if doesn’t exist.

Create Session

Description: Creates a new session. If a session with the given external ID already exists, returns the existing session. URL: /session/ Method: POST Request Payload:

class SessionCreate:
    user_id: str  # User ID
    workflow_id: str  # Workflow ID
    external_id: Optional[str] = None  # External identifier for the session

Response Schema:

class SessionResponse:
    id: str  # Session ID
    user_id: str  # User ID
    workflow_id: str  # Workflow ID
    external_id: Optional[str]  # External identifier for the session
    created_at: datetime  # When the session was created
    updated_at: datetime  # When the session was last updated
    messages: List[MessageResponse]  # List of messages in the session

List Sessions

Description: Lists sessions with pagination and optional user filtering. URL: /session/ Method: GET Query Parameters:

skip: int = 0  # Number of sessions to skip (min: 0)
limit: int = 10  # Number of sessions to return (min: 1, max: 100)
user_id: Optional[str] = None  # Filter sessions by user ID

Response Schema:

class SessionListResponse:
    sessions: List[SessionResponse]  # List of sessions
    total: int  # Total number of sessions

Get Session

Description: Gets a specific session by ID, including all messages. URL: /session/{session_id}/ Method: GET Parameters:

session_id: str  # Session ID

Response Schema:

class SessionResponse:
    id: str  # Session ID
    user_id: str  # User ID
    workflow_id: str  # Workflow ID
    external_id: Optional[str]  # External identifier for the session
    created_at: datetime  # When the session was created
    updated_at: datetime  # When the session was last updated
    messages: List[MessageResponse]  # List of messages in the session

Delete Session

Description: Deletes a session. URL: /session/{session_id}/ Method: DELETE Parameters:

session_id: str  # Session ID

Response: 204 No Content

Create Test Session

Description: Creates or reuses a test user and session. If a test user exists, it will be reused. If an empty test session exists for the same workflow, it will be reused. Otherwise, a new session will be created. URL: /session/test/ Method: POST Query Parameters:

workflow_id: str  # Workflow ID

Response Schema:

class SessionResponse:
    id: str  # Session ID
    user_id: str  # User ID
    workflow_id: str  # Workflow ID
    external_id: Optional[str]  # External identifier for the session
    created_at: datetime  # When the session was created
    updated_at: datetime  # When the session was last updated
    messages: List[MessageResponse]  # List of messages in the session

Get Started

Chatbots

Tools

RAG

Evals

API Reference

Sessions

Sessions API

Create Session

List Sessions

Get Session

Delete Session

Create Test Session

​Sessions API

​Create Session

​List Sessions

​Get Session

​Delete Session

​Create Test Session

Sessions API

Create Session

List Sessions

Get Session

Delete Session

Create Test Session