Check a single content artifact against deployment policies. Currently supports image artifacts.
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
Request body for checking a content artifact.
contentobjectrequiredArtifact content payload. See Content Constraints in the docs for supported formats and limits.
Show child attributesHide child attributes
content.kind stringrequiredArtifact kind. Currently supported: "image"
content.data string | nullBase64-encoded content (with or without data: URI prefix). Exactly one of url or data required
content.mime_type string | nullMIME type (e.g., "image/png"). Optional — automatically detected from image bytes
content.name string | nullDisplay name (e.g., "photo.png")
content.url string | nullURL to fetch content from. Exactly one of url or data required
deployment_idstringrequiredThe deployment ID to check against
external_artifact_idstring | nullYour custom artifact tracking ID
external_session_idstring | nullAttach artifact to an existing session by your external session ID
internal_session_idstring | nullAttach artifact to an existing session by internal UUID
metadatanull | objectArbitrary key-value metadata
Response
Artifact check completed
Artifact check result.
statusstringrequiredCheck status: "completed"
policiesobjectrequiredMap of policy ID to violation result
Show child attributesHide child attributes
internal_artifact_idstringrequiredSystem-generated UUID for this artifact
kindstringrequiredEcho of content.kind from request
flaggedboolean | nulltrue if any policy was violated
external_artifact_idstring | nullYour custom artifact ID (if provided)
internal_session_idstring | nullInternal ID of the linked session (if attached)
external_session_idstring | nullExternal ID of the linked session (if provided)
created_atstring | nullISO 8601 creation timestamp
updated_atstring | nullISO 8601 last update timestamp
notestring | nullInformational note (only present when applicable)
Bad Request