​
Users API

This document outlines the API endpoints for managing users in PySpur. Users and sessions are required for deploying agents and chatbots that maintain message history.

​
Create User

Description: Creates a new user. If a user with the given external ID already exists, returns the existing user. URL: /user/ Method: POST Request Payload: 
class UserCreate:
    external_id: str  # External identifier for the user
    user_metadata: Optional[Dict[str, Any]] = None  # Additional metadata about the user
Response Schema: 
class UserResponse:
    id: str  # User ID (prefixed with 'U')
    external_id: str  # External identifier for the user
    user_metadata: Optional[Dict[str, Any]]  # Additional metadata about the user
    created_at: datetime  # When the user was created
    updated_at: datetime  # When the user was last updated

​
List Users

Description: Lists users with pagination. URL: /user/ Method: GET Query Parameters: 
skip: int = 0  # Number of users to skip (min: 0)
limit: int = 10  # Number of users to return (min: 1, max: 100)
Response Schema: 
class UserListResponse:
    users: List[UserResponse]  # List of users
    total: int  # Total number of users

​
Get User

Description: Gets a specific user by ID. URL: /user/{user_id}/ Method: GET Parameters: 
user_id: str  # User ID (prefixed with 'U')
Response Schema: 
class UserResponse:
    id: str  # User ID (prefixed with 'U')
    external_id: str  # External identifier for the user
    user_metadata: Optional[Dict[str, Any]]  # Additional metadata about the user
    created_at: datetime  # When the user was created
    updated_at: datetime  # When the user was last updated

​
Update User

Description: Updates a user. URL: /user/{user_id}/ Method: PATCH Parameters: 
user_id: str  # User ID (prefixed with 'U')
Request Payload: 
class UserUpdate:
    external_id: Optional[str] = None  # External identifier for the user
    user_metadata: Optional[Dict[str, Any]] = None  # Additional metadata about the user
Response Schema: 
class UserResponse:
    id: str  # User ID (prefixed with 'U')
    external_id: str  # External identifier for the user
    user_metadata: Optional[Dict[str, Any]]  # Additional metadata about the user
    created_at: datetime  # When the user was created
    updated_at: datetime  # When the user was last updated

​
Delete User

Description: Deletes a user. URL: /user/{user_id}/ Method: DELETE Parameters: 
user_id: str  # User ID (prefixed with 'U')
Response: 204 No Content