Artifacts

Check Artifact

POST
/api/artifact

Check a standalone content Artifact against your Environment’s Policies. Use this endpoint to evaluate 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. Conditions select the applicable Policies and Metrics for this Artifact
  3. White Circle evaluates Policies synchronously and queues Metrics asynchronously
  4. You receive synchronous Policy results, and selected Metrics continue asynchronously.

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:

  • Deduplicating checks for the same content
  • Looking up results later via Get Artifact Results
  • Tracking standalone artifact checks with your own ID

Use Images with Events

Use the standalone artifact endpoint when you want to check and retrieve an image as its own object. Use Artifact Events when you want to check an image as part of an Events workflow with run_id, event_id, and internal_event_id.

JSON

{
  "run_id": "run_image_review_123",
  "event": {
    "type": "artifact",
    "content": {
      "kind": "image",
      "url": "https://storage.example.com/uploads/photo.jpg"
    },
    "event_id": "evt_inline_image_1"
  }
}

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.

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, SVG, BMP, ICO, HEIC
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-06-01"

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