​
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