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
