> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifact Events

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

White Circle supports checking images through both the [Events API](/latest/events/overview) and the standalone [Artifact API](/latest/artifact/check-artifact).

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

<Tip>Use [Check Artifact](/latest/artifact/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.</Tip>

## Artifact Event Format

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

```json theme={null}
{
  "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 theme={null}
{
  "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](/latest/artifact/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.                                                                                                         |

<Info>Artifact Events currently support inline image checks only. If White Circle cannot fetch or validate the image, the Event result has <code>status: "failed"</code>; the URL is not evaluated as text.</Info>

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

<Warning>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.</Warning>

See [Conditions](/latest/condition/overview) 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.

```bash theme={null}
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"
  }'
```

<Card title="Check Artifact" icon="cube" href="/latest/artifact/check-artifact">
  See the full standalone artifact request and response shape.
</Card>

## 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 theme={null}
{
  "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..."
    }
  }
}
```

<Info>`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.</Info>