Artifacts

Check Artifact

Check a single content artifact against deployment policies. Currently supports image artifacts.

POST
/api/artifact/check

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_idstring✓The deployment ID to check against
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: "2025-12-01"

Body

application/json

Request body for checking a content artifact.

  • contentobjectrequired

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

    Show child attributes
    • content.kindstringrequired

      Artifact kind. Currently supported: "image"

    • content.datastring | null

      Base64-encoded content (with or without data: URI prefix). Exactly one of url or data required

    • content.mime_typestring | null

      MIME type (e.g., "image/png"). Optional — automatically detected from image bytes

    • content.namestring | null

      Display name (e.g., "photo.png")

    • content.urlstring | null

      URL to fetch content from. Exactly one of url or data required

  • deployment_idstringrequired

    The deployment ID to check against

  • external_artifact_idstring | null

    Your custom artifact tracking ID

  • external_session_idstring | null

    Attach artifact to an existing session by your external session ID

  • internal_session_idstring | null

    Attach artifact to an existing session by internal UUID

  • metadatanull | object

    Arbitrary key-value metadata

    Show child attributes
    • metadata.{key}object

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

Response

application/json

Artifact check completed

Artifact check result.

  • statusstringrequired

    Check status: "completed"

  • policiesobjectrequired

    Map of policy ID to violation result

    Show child attributes
    • policies.{key}object

      Policy violation result for an artifact check.

      Show child attributes
      • policies.{key}.flaggedbooleanrequired

        Whether this policy was violated

      • policies.{key}.flagged_sourcestring[]required

        Content types that triggered the violation (e.g., ["image"])

      • policies.{key}.namestringrequired

        Policy display name

  • internal_artifact_idstringrequired

    System-generated UUID for this artifact

  • kindstringrequired

    Echo of content.kind from request

  • flaggedboolean | null

    true if any policy was violated

  • external_artifact_idstring | null

    Your custom artifact ID (if provided)

  • internal_session_idstring | null

    Internal ID of the linked session (if attached)

  • external_session_idstring | null

    External ID of the linked session (if provided)

  • created_atstring | null

    ISO 8601 creation timestamp

  • updated_atstring | null

    ISO 8601 last update timestamp

  • notestring | null

    Informational note (only present when applicable)