Artifacts

Check Artifact

POST
/api/artifact

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

Request Overview

FieldTypeRequiredDescription
contentobject✓Artifact content payload. See Content Constraints below.
content.kindstring✓Content type: "image"
content.urlstringURL to fetch the image from. Provide either url or data, not both.
content.datastringBase64-encoded image data. Provide either url or data, not both.
content.mime_typestringMIME type (e.g., image/jpeg). Auto-detected if omitted.
deployment_idstringOptional deployment override. If omitted, White Circle uses the deployment associated with your API key.
rolestringThe role that produced this artifact. Controls which policies apply. See Role-Based Filtering below.
external_artifact_idstringYour custom artifact tracking ID. See External Artifact ID below.
internal_session_idstringAttach artifact to an existing session by its system-generated UUID.
external_session_idstringAttach artifact to an existing session by your custom session ID.
metadataobjectArbitrary key-value metadata.

Response Overview

FieldTypeDescription
flaggedboolean | nulltrue if any policy was violated. null while processing or on failure.
policiesobjectMap of policy IDs to their violation statuses
kindstringEcho of content.kind from request (e.g., "image")
statusstringCheck status: "completed", "processing", or "failed". Images are always "completed".
updated_atstringISO 8601 last update timestamp
internal_artifact_idstringSystem-generated UUID for this artifact
external_artifact_idstringYour custom artifact tracking ID (if provided)
external_session_idstringExternal ID of the linked session (if attached)
internal_session_idstringSystem-generated UUID of the linked session (if attached)
created_atstringISO 8601 creation timestamp
notestringInformational message when applicable (e.g., why an image fetch failed)

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

StatusDescription
completedCheck finished. flagged contains the result.
processingAsync check in progress, reserved for future content types (website, video, audio). flagged is null.
failedCheck could not complete (e.g., image fetch timed out). flagged is null. See note field.

External Artifact ID

Use external_artifact_id to track artifacts with your own identifiers. This is useful for:

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

role valuePolicies applied
"user", "system", "developer", "tool"input + any policies
"assistant"output + any policies
omitted / nullany policies only

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

ConstraintValue
Supported formatsJPEG, PNG, WebP, GIF
Max file size20 MB
Max dimension8,192 px (width or height)
Max total pixels50,000,000
URL fetch timeout5,000 ms
Max URL redirects5

Authorizations

  • Authorizationstringheaderrequired

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

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-04-15"

Body

application/json

  • contentobjectrequired

    Show child attributes
    • content.kindstringrequired

    • content.datastring | null

    • content.mime_typestring | null

    • content.namestring | null

    • content.urlstring | null

  • deployment_idstring | null

  • external_artifact_idstring | null

  • external_session_idstring | null

  • internal_session_idstring | null

  • metadatanull | object

    Show child attributes
    • metadata.{key}object

      Show child attributes
      • metadata.{key}.{key}string | number<double> | boolean

  • rolestring | null

  • span_idstring | null

  • trace_idstring | null

Response

application/json

Success

  • policiesobjectrequired

    Show child attributes
    • policies.{key}object

      Show child attributes
      • policies.{key}.flaggedbooleanrequired

      • policies.{key}.flagged_sourcestring[]required

      • policies.{key}.namestringrequired

  • kindstringrequired

  • statusstringrequired

  • internal_artifact_idstringrequired

  • flaggedboolean | null

  • updated_atstring | null

  • external_artifact_idstring | null

  • external_session_idstring | null

  • internal_session_idstring | null

  • created_atstring | null

  • notestring | null