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

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