Skip to main content

​
Overview

The User Management endpoint is optional and used for agents that require user-specific contexts or session management. UserTrace can create simulated users at the start of each simulation session if your agent needs to track user state.
This endpoint is only required if your agent needs to manage user sessions, preferences, or historical context. Many agents can operate without user management by using the metadata in chat requests.

​
Endpoint

POST /users

​
Request Headers

Content-Type: application/json
Authorization: Bearer your-api-key

​
Request Body

​
user_id
string
required
Unique identifier for the simulated user that will be used in subsequent chat requests
​
metadata
object
Simulation context and user characteristics
​
profile
object
User profile information for the simulation

​
Request Examples

​
Basic User Creation

{
  "user_id": "sim_user_abc123",
  "metadata": {
    "scenario_id": "customer_support",
    "persona": "frustrated_customer",
    "session_type": "returning_customer"
  }
}

​
Detailed User Profile

{
  "user_id": "sim_user_xyz789",
  "metadata": {
    "scenario_id": "financial_stress_delivery",
    "persona": "delivery_worker_bengaluru",
    "session_type": "new_user",
    "preferences": {
      "language": "en-IN",
      "communication_style": "direct",
      "urgency_level": "high"
    },
    "history": {
      "previous_orders": 3,
      "last_interaction": "2024-01-15T08:00:00Z",
      "satisfaction_score": 7
    }
  },
  "profile": {
    "name": "Rajesh Kumar",
    "email": "[email protected]",
    "tier": "standard",
    "location": "bangalore"
  }
}

​
Response Format

​
user_id
string
required
Echo of the user ID from the request
​
created_at
string
required
ISO 8601 timestamp when the user was created
​
status
string
required
User status. Values: active, inactive, pending
​
session_id
string
Generated session ID for this user (optional)
​
profile_id
string
Internal profile identifier (optional)
​
capabilities
array
List of features available for this user type

​
Response Examples

​
Successful Creation

{
  "user_id": "sim_user_abc123", 
  "created_at": "2024-01-21T10:30:00Z",
  "status": "active",
  "session_id": "session_def456",
  "profile_id": "profile_789xyz",
  "capabilities": [
    "chat",
    "order_history",
    "preferences"
  ]
}

​
Minimal Response

{
  "user_id": "sim_user_abc123",
  "created_at": "2024-01-21T10:30:00Z", 
  "status": "active"
}

​
Error Responses

​
User Already Exists

{
  "error": {
    "message": "User with ID 'sim_user_abc123' already exists",
    "type": "duplicate_user_error",
    "code": "user_exists"
  }
}

​
Invalid Request

{
  "error": {
    "message": "Invalid user_id format. Must be alphanumeric with underscores.",
    "type": "invalid_request_error",
    "code": "bad_request"
  }
}

​
User Deletion (Optional)

If your agent supports user cleanup, you can implement user deletion:

​
Endpoint

DELETE /users/{user_id}

​
Response

{
  "user_id": "sim_user_abc123",
  "deleted_at": "2024-01-21T11:00:00Z",
  "status": "deleted"
}

​
Implementation Guidelines

​
When to Use User Management

Use user management if your agent requires:
  • User-specific conversation history
  • Personalized preferences or settings
  • Session state across multiple interactions
  • User authentication or authorization
  • Custom user profiles or data
Skip user management if your agent:
  • Is stateless and doesn’t need user context
  • Can derive all needed information from chat metadata
  • Operates as a simple request-response system
  • Doesn’t personalize responses based on user data

​
User ID Format

  • Use consistent, unique identifiers
  • UserTrace generates IDs in format: sim_user_{random}
  • Support alphanumeric characters and underscores
  • Maximum length: 64 characters

​
Lifecycle Management

  1. Creation: User created before first chat interaction
  2. Usage: User ID included in all subsequent chat requests
  3. Session: Optional session management within user context
  4. Cleanup: Optional deletion after simulation completes

​
Best Practices

  1. Validate Input: Check user_id format and required fields
  2. Handle Duplicates: Return appropriate errors for existing users
  3. Store Context: Persist user data for the session duration
  4. Clean Up: Remove users after simulation completes
  5. Security: Don’t store sensitive data in simulated user profiles
Optional Feature: User management is completely optional. Most agents can function effectively using only the chat completions endpoint with metadata.