Events

Artifact Events

Check inline image artifacts as Events or use the standalone artifact endpoint

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

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

Artifact Event Format

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

JSON

{
  "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

JSON

{
  "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:

FieldTypeRequiredDescription
content.kindstring✓Must be "image".
content.urlstringURL to fetch the image. Provide either url or data, not both.
content.datastringBase64-encoded image data or a data URI. Provide either url or data, not both.
content.mime_typestringOptional MIME type. For raw base64 JPEG, PNG, WebP, and GIF data, White Circle detects it from the decoded bytes when omitted.
content.namestringOptional display name.

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.

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

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

JSON

{
  "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..."
    }
  }
}