Skip to main content
POST
Check artifact content
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

  1. You submit a content artifact (e.g., an image via URL or base64)
  2. White Circle analyzes the content against applicable policies configured in your deployment
  3. You receive a synchronous response with policy violations
Image artifacts are checked synchronously — you receive results immediately in the response.
mime_type is optional for all submission methods. White Circle detects the image format automatically from the content bytes.

Request Overview

Response Overview

Each policy in the policies object includes:
  • name — Human-readable policy name
  • flagged — Whether this specific policy was violated
  • flagged_source — Array of content types that triggered the violation (e.g., ["image"])

Artifact Statuses

Checking image artifacts is always synchronous — the response always has status "completed".

External Artifact ID

Use external_artifact_id to track artifacts with your own identifiers. This is useful for:
If multiple artifacts share the same external_artifact_id, the most recently created one within the deployment is returned on lookup.

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.
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.
The session must already exist before you can attach an artifact to it. If the provided session ID doesn’t match any existing session, the artifact is created without a session link.
Sessions can be on any deployment within the same team — the artifact and session don’t need to share the same deployment.

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.
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

Authorization
string
header
required

API Key required. Format: Bearer wc-your-api-key

Headers

whitecircle-version
string
required

API Version

Body

application/json

Request body for checking a content artifact.

content
object
required

Artifact content payload. See Content Constraints in the docs for supported formats and limits.

Example:
deployment_id
string
required

The deployment ID to check against

external_artifact_id
string | null

Your custom artifact tracking ID

external_session_id
string | null

Attach artifact to an existing session by your external session ID

internal_session_id
string | null

Attach artifact to an existing session by internal UUID

metadata
null | object

Arbitrary key-value metadata

Response

Artifact check completed

Artifact check result.

status
string
required

Check status: "completed"

policies
object
required

Map of policy ID to violation result

internal_artifact_id
string
required

System-generated UUID for this artifact

kind
string
required

Echo of content.kind from request

flagged
boolean | null

true if any policy was violated

external_artifact_id
string | null

Your custom artifact ID (if provided)

internal_session_id
string | null

Internal ID of the linked session (if attached)

external_session_id
string | null

External ID of the linked session (if provided)

created_at
string | null

ISO 8601 creation timestamp

updated_at
string | null

ISO 8601 last update timestamp

note
string | null

Informational note (only present when applicable)