> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getusertrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Management

> Optional endpoint for creating user contexts in session-based agents

## 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.

<Note>
  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.
</Note>

## Endpoint

```
POST /users
```

## Request Headers

```http theme={null}
Content-Type: application/json
Authorization: Bearer your-api-key
```

## Request Body

<ParamField body="user_id" type="string" required>
  Unique identifier for the simulated user that will be used in subsequent chat requests
</ParamField>

<ParamField body="metadata" type="object">
  Simulation context and user characteristics

  <Expandable title="Metadata Fields">
    <ParamField body="scenario_id" type="string">
      Identifier for the test scenario
    </ParamField>

    <ParamField body="persona" type="string">
      User persona/character for the simulation
    </ParamField>

    <ParamField body="session_type" type="string">
      Type of session (e.g., "new\_user", "returning\_customer")
    </ParamField>

    <ParamField body="preferences" type="object">
      User preferences or settings
    </ParamField>

    <ParamField body="history" type="object">
      Simulated user history or context
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="profile" type="object">
  User profile information for the simulation

  <Expandable title="Profile Fields">
    <ParamField body="name" type="string">
      Display name for the simulated user
    </ParamField>

    <ParamField body="email" type="string">
      Email address for the simulated user
    </ParamField>

    <ParamField body="tier" type="string">
      Customer tier (e.g., "premium", "standard", "basic")
    </ParamField>

    <ParamField body="location" type="string">
      Geographic location or region
    </ParamField>
  </Expandable>
</ParamField>

## Request Examples

### Basic User Creation

```json theme={null}
{
  "user_id": "sim_user_abc123",
  "metadata": {
    "scenario_id": "customer_support",
    "persona": "frustrated_customer",
    "session_type": "returning_customer"
  }
}
```

### Detailed User Profile

```json theme={null}
{
  "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": "rajesh.k.sim@example.com",
    "tier": "standard",
    "location": "bangalore"
  }
}
```

## Response Format

<ParamField body="user_id" type="string" required>
  Echo of the user ID from the request
</ParamField>

<ParamField body="created_at" type="string" required>
  ISO 8601 timestamp when the user was created
</ParamField>

<ParamField body="status" type="string" required>
  User status. Values: `active`, `inactive`, `pending`
</ParamField>

<ParamField body="session_id" type="string">
  Generated session ID for this user (optional)
</ParamField>

<ParamField body="profile_id" type="string">
  Internal profile identifier (optional)
</ParamField>

<ParamField body="capabilities" type="array">
  List of features available for this user type
</ParamField>

## Response Examples

### Successful Creation

```json theme={null}
{
  "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

```json theme={null}
{
  "user_id": "sim_user_abc123",
  "created_at": "2024-01-21T10:30:00Z", 
  "status": "active"
}
```

## Error Responses

### User Already Exists

```json theme={null}
{
  "error": {
    "message": "User with ID 'sim_user_abc123' already exists",
    "type": "duplicate_user_error",
    "code": "user_exists"
  }
}
```

### Invalid Request

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Note>
  **Optional Feature**: User management is completely optional. Most agents can function effectively using only the chat completions endpoint with metadata.
</Note>