This is the core endpoint for content moderation and analytics — send your content using the OpenAI-like message format and receive instant feedback on policy violations. Metrics are computed for each request in the background.
How It Works
- You submit content as one or more messages
- White Circle analyzes the content against all policies in your deployment
- You receive a response indicating which (if any) policies got flagged
Request Overview
Response Overview
Each policy in the policies object includes:
name— Human-readable policy nameflagged— Whether this specific policy was violatedflagged_source— Array of content types that triggered the violation:["text"],["image"], or["text", "image"]when both text and image violated
Message Roles
The API uses OpenAI-compatible message format. Each message must have a role field:
The last message’s role determines which policies are evaluated:
Role strings with postfixes (e.g., "user-12345", "assistant-v2") are normalized to their base role.
Content Types
White Circle supports different content formats within a message:
Plain text content in string format
Images inline or by reference via artifact content parts
Standalone content checks for images, with pre-check and reference support
Advanced Features
Send only new messages and let White Circle automatically merge them with the previous session context
Attach user information, timestamps, and custom data to enable risk scoring and analytics
Session Tracking
Use external_session_id to track content using your own identifiers. This can be any string that makes sense for your application:
JSON
{
"deployment_id": "your-deployment-id",
"external_session_id": "user-123-conversation-456",
"messages": [...]
}Using external_session_id allows you to:
- Retrieve results later via Retrieving Results
- Use context merging to send incremental updates
- Enable Risk Scoring by associating sessions with users
Authorizations
Headers
Body
application/json
messagesobject[]requiredArray of chat messages to analyze for policy violations
Show child attributesHide child attributes
messages.role stringrequiredmessages.content null | string | object[]Show child attributesHide child attributes
messages.content. type enum<string>requiredAvailable options:
artifactmessages.content. internal_artifact_id string | nullmessages.content. content null | objectArtifact content payload.
Show child attributesHide child attributes
messages.content. content. kind stringrequiredArtifact kind. Currently supported: "image"
messages.content. content. data string | nullBase64-encoded content (with or without data: URI prefix). Exactly one of url or data required
messages.content. content. mime_type string | nullMIME type (e.g., "image/png"). Optional — automatically detected from image bytes
messages.content. content. name string | nullDisplay name (e.g., "photo.png")
messages.content. content. url string | nullURL to fetch content from. Exactly one of url or data required
messages.content. external_artifact_id string | null
messages.metadata null | objectShow child attributesHide child attributes
messages.metadata. assistant null | objectmessages.metadata. message null | objectmessages.metadata. user null | objectShow child attributesHide child attributes
messages.metadata. user. city string | nullCity name
Example:
"San Francisco"messages.metadata. user. country string | nullFull country name
Example:
"United States"messages.metadata. user. country_code string | nullISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')
Example:
"US"messages.metadata. user. email string | nullmessages.metadata. user. id string | nullmessages.metadata. user. ip string | nullUser's IP address for geolocation lookup
Example:
"8.8.8.8"messages.metadata. user. latitude number<double> | nullLatitude coordinate
Example:
37.7749messages.metadata. user. longitude number<double> | nullLongitude coordinate
Example:
-122.4194messages.metadata. user. name string | nullmessages.metadata. user. state string | nullState/province name or code
Example:
"California"
deployment_idstringrequiredThe deployment ID to check against
external_session_idstring | nullOptional external identifier for tracking this session
include_contextboolean | nullInclude previous conversation context. Defaults to true if external_session_id is provided
metadataobjectOptional session-level metadata
policiesstring[] | nullOptional list of specific policy IDs to check against. If omitted, all deployment policies are used
Response
Success
Bad Request