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

# 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](/2026-04-15/user/radar), 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 highlight={6, 9-11} theme={null}
{
  "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 highlight={3-7} theme={null}
{
  "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 highlight={7-18, 23-32} theme={null}
{
  "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                     |

<Info>
  User metadata powers <a href="/2026-04-15/user/radar">Risk Scoring</a>. Include at least one stable identifier in <code>metadata.user</code> (<code>id</code> or <code>email</code>) to track policy violations per user over time, and optionally include <code>ip</code> as supplemental context since IP addresses can change.
</Info>

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

<CodeGroup>
  ```bash cURL theme={null}
  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 Python theme={null}
  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 JavaScript theme={null}
  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'
            }
          }
        }
      ]
    })
  });
  ```
</CodeGroup>

## Use Cases

<CardGroup cols={1}>
  <Card title="Risk Scoring" icon="chart-line" href="/2026-04-15/user/radar">
    Include `user.id`, `user.email`, or `user.ip` to enable risk scoring. White Circle aggregates violations per user to detect high-risk accounts.
  </Card>

  <Card title="Audit Trails" icon="clock-rotate-left">
    Include `message.id` and `message.timestamp` for detailed logging and compliance.
  </Card>

  <Card title="Analytics" icon="chart-bar">
    Include `environment` data to segment moderation results by app version, platform, or feature.
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Always include a user identifier for risk scoring">
    To use [Risk Scoring](/2026-04-15/user/radar), include at least one identifier in your message metadata (`user.id`, `user.email`, or `user.ip`):

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

    <Tip>For best correlation, include both <code>id</code> and <code>email</code> when available. Add <code>ip</code> as supplemental context when you trust the source IP.</Tip>
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Track AI model performance">
    If you use multiple AI models, track their performance:

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

    This data appears in your White Circle dashboard for analysis.
  </Accordion>
</AccordionGroup>