Enriching with Metadata

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:

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:

{
  "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:

{
  "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:

{
  "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

User metadata powers Risk Scoring. 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

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"
          }
        }
      }
    ]
  }'

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"
                    }
                }
            }
        ]
    }
)

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

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):

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

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:

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

This data appears in your White Circle dashboard for analysis.

First Steps

Use Cases

Integrations

Sessions

Artifacts

Policy

Metric

User

Enriching with Metadata

Metadata Levels

Session-Level Metadata

Session Fields

Environment Fields

Message-Level Metadata

User Metadata

Assistant Metadata

Message Metadata

Full Example

Use Cases

Risk Scoring

Audit Trails

Analytics

Best Practices

​Metadata Levels

​Session-Level Metadata

​Session Fields

​Environment Fields

​Message-Level Metadata

​User Metadata

​Assistant Metadata

​Message Metadata

​Full Example

​Use Cases

Risk Scoring

Audit Trails

Analytics

​Best Practices

Metadata Levels

Session-Level Metadata

Session Fields

Environment Fields

Message-Level Metadata

User Metadata

Assistant Metadata

Message Metadata

Full Example

Use Cases

Best Practices