Artifact Events

White Circle supports checking images through both the Events API and the standalone Artifact API.

Endpoint	Use when
`POST /api/event` or `POST /api/events` with `type: "artifact"`	Image is part of a conversation, tool call, or other Event.
`POST /api/artifact`	Image is a standalone artifact that you want to retrieve through the artifact API.

Use Check Artifact for standalone images such as profile pictures, user uploads, and AI-generated images that do not need to be grouped with other Events.

Artifact Event Format

Artifact Events use type: "artifact" and include the image payload in content.

{
  "event": {
    "type": "artifact",
    "content": {
      "kind": "image",
      "url": "https://cdn.example.com/uploads/user-upload-42.png"
    },
    "metadata": {
      "source": "support_chat_attachment"
    },
    "event_id": "evt_uploaded_image_1",
    "run_id": "run_image_review_123",
    "environment_id": "environment_123",
    "external_artifact_id": "user-upload-42"
  }
}

Response Example

{
  "flagged": false,
  "policies": {},
  "event": {
    "type": "artifact",
    "status": "completed",
    "event_id": "evt_uploaded_image_1",
    "internal_event_id": "123e4567-e89b-42d3-a456-426614174000"
  },
  "run_id": "run_image_review_123"
}

Content Overview

Artifact Event content uses the same image payload shape as Check Artifact:

Field	Type	Required	Description
`content.kind`	string	✓	Must be `"image"`.
`content.url`	string		URL to fetch the image. Provide either `url` or `data`, not both.
`content.data`	string		Base64-encoded image data or a data URI. Provide either `url` or `data`, not both.
`content.mime_type`	string		Optional MIME type. For raw base64 JPEG, PNG, WebP, and GIF data, White Circle detects it from the decoded bytes when omitted.
`content.name`	string		Optional display name.

Artifact Events currently support inline image checks only. If White Circle cannot fetch or validate the image, the Event result has status: “failed”; the URL is not evaluated as text.

Use Conditions with Artifact Events

Conditions evaluate the Artifact Event’s metadata to select the applicable Policies and Metrics. Event selectors then filter them to Artifact Events. Attach image Policies or Metrics to an active Condition and include matching metadata on the Event.

If no active Condition matches, no Policies are evaluated and no Metrics are queued for the Artifact Event. Conditions apply to Artifact Events, not to the standalone artifact endpoint.

See Conditions for metadata expressions and Policy attachments.

Standalone Artifact Endpoint

Use POST /api/artifact when the image does not need to be grouped with messages, tool calls, or other Events.

curl -X POST "https://eu.whitecircle.com/api/artifact" \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "Content-Type: application/json" \
  -H "whitecircle-version: 2026-06-01" \
  -d '{
    "content": {
      "kind": "image",
      "url": "https://cdn.example.com/uploads/avatar-42.jpg"
    },
    "external_artifact_id": "user-avatar-42",
    "role": "user"
  }'

Check Artifact

See the full standalone artifact request and response shape.

Which Endpoint Should You Use?

Choose Artifact Events when you want to:

Check the image alongside messages, tool calls, agent state, or reasoning
Receive a result with event_id and internal_event_id
Target artifact policies with Event selectors such as artifact + image

Choose Check Artifact when you want to:

Submit an image as a standalone object
Retrieve the artifact later by internal_artifact_id or external_artifact_id
Check and retrieve the image as a standalone artifact

Base64 Image Example

{
  "environment_id": "environment_123",
  "run_id": "run_image_review_123",
  "event": {
    "type": "artifact",
    "event_id": "evt_inline_image_1",
    "content": {
      "kind": "image",
      "mime_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }
}

mime_type is optional for raw base64 JPEG, PNG, WebP, and GIF data. White Circle detects the image type from the decoded bytes when you omit it.

First Steps

Use Cases

Integrations

Events

Conditions

Artifacts

Policy

Metric

User

Artifact Event Format

Response Example

Content Overview

Use Conditions with Artifact Events

Standalone Artifact Endpoint

Check Artifact

Which Endpoint Should You Use?

Base64 Image Example

​Artifact Event Format

​Response Example

​Content Overview

​Use Conditions with Artifact Events

​Standalone Artifact Endpoint

Check Artifact

​Which Endpoint Should You Use?

​Base64 Image Example

Artifact Event Format

Response Example

Content Overview

Use Conditions with Artifact Events

Standalone Artifact Endpoint

Which Endpoint Should You Use?

Base64 Image Example