​
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