# Artifact Events

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

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

| 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](https://whitecircle.com/docs/latest/artifact/check-artifact.md) 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`.

```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](https://whitecircle.com/docs/latest/artifact/check-artifact.md):

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

> [!NOTE]
> 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.

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

See [Conditions](https://whitecircle.com/docs/latest/condition/overview.md) 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
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](https://whitecircle.com/docs/latest/artifact/check-artifact.md)**: 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..."
    }
  }
}
```

> [!NOTE]
> `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.
