Check a single content artifact against your deployment’s policies. Use this endpoint to moderate standalone content such as profile pictures, user uploads, AI-generated images, and more.
How It Works
- You submit a content artifact (e.g., an image via URL or base64)
- White Circle analyzes the content against applicable policies configured in your deployment
- You receive a synchronous response with policy violations
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 (e.g.,["image"])
Artifact Statuses
External Artifact ID
Use external_artifact_id to track artifacts with your own identifiers. This is useful for:
- Deduplicating checks for the same content
- Looking up results later via Get Artifact Results
- Referencing the artifact in session checks by your own ID
JSON
{
"deployment_id": "your-deployment-id",
"content": {
"kind": "image",
"url": "https://cdn.example.com/uploads/avatar-42.jpg"
},
"external_artifact_id": "user-avatar-42"
}Attach to a Session
You can optionally attach an artifact to an existing session by providing internal_session_id or external_session_id. This connects the artifact to the session for tracking and analytics.
JSON
{
"deployment_id": "your-deployment-id",
"content": {
"kind": "image",
"url": "https://storage.example.com/uploads/photo.jpg"
},
"external_session_id": "user-session-123"
}To directly attach this artifact to a session, send a session check request referencing it by ID. The artifact won’t be re-checked — White Circle will use the existing result.
Role-Based Filtering
The role field controls which policies are evaluated against the artifact based on each policy’s Applies To setting (input, output, or any).
Use this to apply the right set of policies depending on who produced the content. For example, pass "user" for user-uploaded images and "assistant" for AI-generated images.
JSON
{
"deployment_id": "your-deployment-id",
"content": {
"kind": "image",
"url": "https://cdn.example.com/ai-generated-image.png"
},
"role": "assistant"
}Role strings with postfixes (e.g., "user-12345", "assistant-v2") are normalized to their base role. Invalid role values are treated the same as omitting the field.
Content Constraints
Authorizations
Headers
Body
application/json
Response
Success
Bad Request