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:
- Track all checks for a session
- Enable context merging
- Link sessions to users for Risk Scoring
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"]
}
}
}