This is the core endpoint for content moderation and analytics. Send content in the OpenAI-like message format and receive a session-level verdict plus artifact-level results for any inline or referenced artifacts you explicitly include. 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 session envelope with the overall session verdict and any explicit artifact results
Request Overview
Response Overview
The endpoint returns a single object with two top-level fields:
The session object includes:
Each policy object in session.policies 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
Each object in artifacts[] uses the same response shape as Check Artifact and Get Artifact Results.
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
Example Response
JSON
{
"session": {
"flagged": true,
"internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
"external_session_id": "user-123-conversation-456",
"policies": {
"70289e06-9111-463e-b121-7247c2b7bfbd": {
"flagged": false,
"flagged_source": [],
"name": "No PII Sharing"
},
"a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
"flagged": true,
"flagged_source": ["text", "image"],
"name": "Drugs"
}
}
},
"artifacts": []
}For a response example with populated artifacts[], see Checking Images.
Authorizations
Headers
Body
application/json
messagesobject[]requiredShow child attributesHide child attributes
messages.role stringrequiredmessages.content null | string | object[]Show child attributesHide child attributes
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"
external_session_idstring | nullinclude_contextboolean | nullmetadataobjectdeployment_idstring | null
Response
Success
sessionobjectrequiredShow child attributesHide child attributes
artifactsobject[]requiredShow child attributesHide child attributes
artifacts.policies objectrequiredartifacts.kind stringrequiredartifacts.status stringrequiredartifacts.internal_artifact_id stringrequiredartifacts.flagged boolean | nullartifacts.updated_at string | nullartifacts.external_artifact_id string | nullartifacts.external_session_id string | nullartifacts.internal_session_id string | nullartifacts.created_at string | nullartifacts.note string | null
Bad Request