# Enriching with Metadata

> Attach context about users, messages, and sessions for analytics and risk scoring

Metadata enriches your moderation requests with contextual information. This enables powerful features like [Risk Scoring](https://whitecircle.com/docs/2026-04-15/user/radar.md), detailed analytics, and better audit trails.

## Metadata Levels

White Circle supports metadata at two levels:

| Level       | Field                    | Purpose                                                     |
| ----------- | ------------------------ | ----------------------------------------------------------- |
| **Session** | `metadata` (top-level)   | Information about the overall session or environment        |
| **Message** | `metadata` (per message) | Information about specific messages, users, or AI responses |

## Session-Level Metadata

Add context about the session or environment at the request level:

```json
{
  "deployment_id": "your-deployment-id",
  "messages": [...],
  "metadata": {
    "session": {
      "timestamp": "2025-12-01T10:30:00Z"
    },
    "environment": {
      "app_version": "2.1.0",
      "platform": "ios",
      "feature": "customer-support-chat"
    }
  }
}
```

### Session Fields

| Field               | Type   | Description                                 |
| ------------------- | ------ | ------------------------------------------- |
| `session.timestamp` | string | ISO 8601 timestamp when the session started |

### Environment Fields

The `environment` object accepts any key-value pairs for custom context:

```json
{
  "environment": {
    "app_version": "2.1.0",
    "platform": "web",
    "feature": "ai-assistant",
    "region": "us-east-1",
    "ab_test": "new-moderation-v2"
  }
}
```

Values can be strings, numbers, or booleans.

## Message-Level Metadata

Attach metadata to individual messages to provide context about who sent them and when:

```json
{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": "Hello, I need help",
      "metadata": {
        "user": {
          "id": "user-123",
          "email": "user@example.com",
          "name": "John Doe",
          "ip": "192.168.1.1"
        },
        "message": {
          "id": "msg-456",
          "timestamp": "2025-12-01T10:30:00Z"
        }
      }
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you today?",
      "metadata": {
        "assistant": {
          "model_name": "gpt-4o-mini",
          "latency": 1200
        },
        "message": {
          "id": "msg-457",
          "timestamp": "2025-12-01T10:30:01Z"
        }
      }
    }
  ]
}
```

### User Metadata

Attach user information to messages with `role: "user"`:

| Field   | Type   | Description                   |
| ------- | ------ | ----------------------------- |
| `id`    | string | Your internal user identifier |
| `email` | string | User's email or SHA-256 hash of email          |
| `name`  | string | User's display name           |
| `ip`    | string | User's IP address             |

> [!NOTE]
> User metadata powers [Risk Scoring](https://whitecircle.com/docs/2026-04-15/user/radar.md). Include at least one stable identifier in `metadata.user` (`id` or `email`) to track policy violations per user over time, and optionally include `ip` as supplemental context since IP addresses can change.

### Assistant Metadata

Attach AI response details to messages with `role: "assistant"`:

| Field          | Type   | Description                                         |
| -------------- | ------ | --------------------------------------------------- |
| `model_name`   | string | The AI model used (e.g., "gpt-4o-mini", "claude-3") |
| `provider_url` | string | API endpoint URL                                    |
| `latency`      | number | Response time in milliseconds                       |

This data enables performance analytics in the White Circle dashboard.

### Message Metadata

Attach identifiers and timestamps to any message:

| Field       | Type   | Description                                     |
| ----------- | ------ | ----------------------------------------------- |
| `id`        | string | Your unique message identifier                  |
| `timestamp` | string | ISO 8601 timestamp when the message was created |

## Full Example

```bash title="cURL"
curl -X POST https://eu.whitecircle.com/api/session \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "Content-Type: application/json" \
  -H "whitecircle-version: 2026-04-15" \
  -d '{
    "deployment_id": "53e4567-e89b-12d3-a456-426614174000",
    "external_session_id": "support-chat-789",
    "metadata": {
      "session": {
        "timestamp": "2025-12-01T10:00:00Z"
      },
      "environment": {
        "app_version": "3.2.1",
        "platform": "web"
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "I need to cancel my subscription",
        "metadata": {
          "user": {
            "id": "usr_abc123",
            "email": "customer@example.com"
          },
          "message": {
            "id": "msg_001",
            "timestamp": "2025-12-01T10:00:05Z"
          }
        }
      },
      {
        "role": "assistant",
        "content": "I can help you cancel. Let me pull up your account.",
        "metadata": {
          "assistant": {
            "model_name": "gpt-4o-mini",
            "latency": 800
          },
          "message": {
            "id": "msg_002",
            "timestamp": "2025-12-01T10:00:06Z"
          }
        }
      }
    ]
  }'
```

```python title="Python"
import requests

response = requests.post(
    "https://eu.whitecircle.com/api/session",
    headers={
        "Authorization": "Bearer wc-your-api-key",
        "Content-Type": "application/json",
        "whitecircle-version": "2026-04-15"
    },
    json={
        "deployment_id": "53e4567-e89b-12d3-a456-426614174000",
        "external_session_id": "support-chat-789",
        "metadata": {
            "session": {
                "timestamp": "2025-12-01T10:00:00Z"
            },
            "environment": {
                "app_version": "3.2.1",
                "platform": "web"
            }
        },
        "messages": [
            {
                "role": "user",
                "content": "I need to cancel my subscription",
                "metadata": {
                    "user": {
                        "id": "usr_abc123",
                        "email": "customer@example.com"
                    },
                    "message": {
                        "id": "msg_001",
                        "timestamp": "2025-12-01T10:00:05Z"
                    }
                }
            },
            {
                "role": "assistant",
                "content": "I can help you cancel. Let me pull up your account.",
                "metadata": {
                    "assistant": {
                        "model_name": "gpt-4o-mini",
                        "latency": 800
                    },
                    "message": {
                        "id": "msg_002",
                        "timestamp": "2025-12-01T10:00:06Z"
                    }
                }
            }
        ]
    }
)
```

```javascript title="JavaScript"
const response = await fetch('https://eu.whitecircle.com/api/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wc-your-api-key',
    'Content-Type': 'application/json',
    'whitecircle-version': '2026-04-15'
  },
  body: JSON.stringify({
    deployment_id: '53e4567-e89b-12d3-a456-426614174000',
    external_session_id: 'support-chat-789',
    metadata: {
      session: {
        timestamp: '2025-12-01T10:00:00Z'
      },
      environment: {
        app_version: '3.2.1',
        platform: 'web'
      }
    },
    messages: [
      {
        role: 'user',
        content: 'I need to cancel my subscription',
        metadata: {
          user: {
            id: 'usr_abc123',
            email: 'customer@example.com'
          },
          message: {
            id: 'msg_001',
            timestamp: '2025-12-01T10:00:05Z'
          }
        }
      },
      {
        role: 'assistant',
        content: 'I can help you cancel. Let me pull up your account.',
        metadata: {
          assistant: {
            model_name: 'gpt-4o-mini',
            latency: 800
          },
          message: {
            id: 'msg_002',
            timestamp: '2025-12-01T10:00:06Z'
          }
        }
      }
    ]
  })
});
```

## Use Cases

- **[Risk Scoring](https://whitecircle.com/docs/2026-04-15/user/radar.md)**: Include `user.id`, `user.email`, or `user.ip` to enable risk scoring. White Circle aggregates violations per user to detect high-risk accounts.
- **Audit Trails**: Include `message.id` and `message.timestamp` for detailed logging and compliance.
- **Analytics**: Include `environment` data to segment moderation results by app version, platform, or feature.

## Best Practices

### Always include a user identifier for risk scoring

To use [Risk Scoring](https://whitecircle.com/docs/2026-04-15/user/radar.md), include at least one identifier in your message metadata (`user.id`, `user.email`, or `user.ip`):

```json
{
  "metadata": {
    "user": {
      "id": "user-123",
      "email": "user@example.com",
      "ip": "203.0.113.10"
    }
  }
}
```

> [!TIP]
> For best correlation, include both `id` and `email` when available. Add `ip` as supplemental context when you trust the source IP.

### Use consistent identifiers

Always use the same `user.id` and normalized `user.email` for the same user across requests. Use `user.ip` as supplemental context, because IPs can change. Inconsistent identifiers create separate profiles and fragment risk scoring data.

### Track AI model performance

If you use multiple AI models, track their performance:

```json
{
  "metadata": {
    "assistant": {
      "model_name": "gpt-4o",
      "latency": 2500
    }
  }
}
```

This data appears in your White Circle dashboard for analysis.
