Checking Text

The simplest way to send content for moderation is as plain text strings. This works for any text-based content — AI responses, user messages, documents, and more.

Basic Text Format

Pass the content directly as a string in the content field:

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": "Hello, can you help me with my order?"
    },
    {
      "role": "assistant",
      "content": "Of course! I'd be happy to help. What's your order number?"
    }
  ]
}

This is the most common format and works for the majority of use cases.

Multi-turn Content

For multi-turn interactions, include all relevant messages to give White Circle the full context:

{
  "deployment_id": "your-deployment-id",
  "messages": [
    { "role": "user", "content": "What's your refund policy?" },
    { "role": "assistant", "content": "We offer full refunds within 30 days of purchase." },
    { "role": "user", "content": "Great, I'd like a refund for order #12345" },
    { "role": "assistant", "content": "I've initiated the refund. You'll receive it in 3-5 business days." }
  ]
}

Only the last message in the array is evaluated for policy violations and metrics. Earlier messages provide context but are not themselves checked.

Don’t want to send the entire history every time? Use Context Merging to send only new messages and let White Circle automatically combine them with the previous content.

Structured Text Format

You can also use the explicit structured format with type: "input_text". This is equivalent to the string format but allows you to mix text with images in the same message:

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What do you think about this?"
        }
      ]
    }
  ]
}

This format becomes necessary when you need to combine text and images in a single message. See Image Content for details.

Group Conversations

When moderating content from multiple users (e.g., group chats, forums, collaborative documents), include the user.id in each message’s metadata to identify who sent what:

{
  "deployment_id": "your-deployment-id",
  "external_session_id": "group-chat-room-42",
  "messages": [
    {
      "role": "user",
      "content": "Hey everyone, what do you think about this idea?",
      "metadata": {
        "user": { "id": "alice-123" }
      }
    },
    {
      "role": "user",
      "content": "I think it's great!",
      "metadata": {
        "user": { "id": "bob-456" }
      }
    },
    {
      "role": "user",
      "content": "Let me share something relevant...",
      "metadata": {
        "user": { "id": "charlie-789" }
      }
    }
  ]
}

Including user.id in metadata enables Risk Scoring. You can also include user.email and user.ip for stronger cross-session correlation.

Why User IDs Matter in Group Content

Without user IDs, White Circle only knows that someone in the group sent violating content. With user IDs:

Pinpoint the source — know exactly which user triggered the violation
Track repeat offenders — build risk profiles per user across all their sessions
Enable targeted actions — take action against specific users, not the whole group

Best Practices

Include system prompts

If your AI has a system prompt, include it in the check. This helps White Circle understand the intended behavior and detect violations that involve circumventing instructions.

{
  "deployment_id": "your-deployment-id",
  "messages": [
    {
      "role": "system",
      "content": "You are a medical information assistant. Never provide specific medical diagnoses."
    },
    { "role": "user", "content": "What disease do I have based on these symptoms?" },
    { "role": "assistant", "content": "Based on your symptoms, you likely have..." }
  ]
}

Check both user and assistant messages

Moderate both sides of the interaction:

User messages may contain harmful requests, attempts to jailbreak the AI, or policy-violating content
Assistant messages may contain inappropriate responses, leaked information, or harmful advice

Use session tracking

For ongoing interactions, use external_session_id to:

Track all checks for a session
Enable context merging
Link sessions to users for Risk Scoring

{
  "deployment_id": "your-deployment-id",
  "external_session_id": "user-123-session-456",
  "messages": [...]
}

Response

For text-only requests, the response still uses the session envelope. In that case, artifacts is typically empty:

{
  "session": {
    "flagged": true,
    "internal_session_id": "a3e733b5-d6c4-473d-82d4-669c1e757256",
    "policies": {
      "fed85161-e929-4c6c-a3bc-3d10428fafbe": {
        "name": "No Harmful Content",
        "flagged": true,
        "flagged_source": ["text"]
      }
    }
  },
  "artifacts": []
}

For the full session envelope shape, see Check Content.

First Steps

Use Cases

Integrations

Sessions

Artifacts

Policy

Metric

User

Basic Text Format

Multi-turn Content

Structured Text Format

Group Conversations

Why User IDs Matter in Group Content

Best Practices

Response

​Basic Text Format

​Multi-turn Content

​Structured Text Format

​Group Conversations

​Why User IDs Matter in Group Content

​Best Practices

​Response

Basic Text Format

Multi-turn Content

Structured Text Format

Group Conversations

Why User IDs Matter in Group Content

Best Practices

Response