Sessions

Checking Text

Send text content for policy analysis

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:

JSON

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

JSON

{
  "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." }
  ]
}

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:

JSON

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

JSON

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

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.

JSON

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

JSON

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

Response

When a text policy violation is detected, the flagged_source array will include "text":

JSON

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