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, detailed analytics, and better audit trails.
Metadata Levels
White Circle supports metadata at two levels:
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
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": "[email protected]",
"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":
Assistant Metadata
Attach AI response details to messages with role: "assistant":
This data enables performance analytics in the White Circle dashboard.
Message Metadata
Attach identifiers and timestamps to any message:
Full Example
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": "[email protected]"
},
"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"
}
}
}
]
}'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": "[email protected]"
},
"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"
}
}
}
]
}
)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: '[email protected]'
},
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
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, include at least one identifier in your message metadata (user.id, user.email, or user.ip):
JSON
{
"metadata": {
"user": {
"id": "user-123",
"email": "[email protected]",
"ip": "203.0.113.10"
}
}
}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.