# Check Artifact

`POST /api/artifact`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [latest/openapi.json](https://whitecircle.com/docs/latest/openapi.json)

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.

> [!NOTE]
> Image Artifacts are checked synchronously — you receive results immediately in the response.

> [!NOTE]
> `mime_type` is optional for all submission methods. White Circle detects the image format automatically from the content bytes.

## Artifact Statuses

| Status       | Description                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `completed`  | Check finished. `flagged` contains the result.                                                  |
| `processing` | Async check in progress, reserved for future content types (website, video, audio). `flagged` is `null`.                           |
| `failed`     | Check could not complete (e.g., image fetch timed out). `flagged` is `null`. See `note` field.  |

> [!NOTE]
> Checking image Artifacts is always synchronous — the response always has status `"completed"`.

## 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](https://whitecircle.com/docs/latest/artifact/get-artifact.md)
* Tracking standalone artifact checks with your own ID

> [!NOTE]
> If multiple artifacts share the same `external_artifact_id`, White Circle returns the latest artifact version within the same Environment on lookup.

## 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](https://whitecircle.com/docs/latest/events/artifacts.md) 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"
  }
}
```

> [!TIP]
> For new Events integrations, prefer Artifact Events when the image belongs to the same interaction as messages, tool calls, agent state, or reasoning.

## 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` value                              | Policies applied          |
| ----------------------------------------- | ------------------------- |
| `"user"`, `"system"`, `"developer"`, `"tool"` | `input` + `any` policies  |
| `"assistant"`                              | `output` + `any` policies |
| omitted / `null`                          | `any` 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

| Constraint | Value |
|-----------|-------|
| Supported formats | JPEG, PNG, WebP, GIF, SVG, BMP, ICO, HEIC |
| Max file size | 20 MB |
| Max dimension | 8,192 px (width or height) |
| Max total pixels | 50,000,000 |
| URL fetch timeout | 5,000 ms |
| Max URL redirects | 5 |

> [!WARNING]
> When you submit an image by URL, ensure the server's `Content-Type` response header matches the image's actual format.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-06-01"`.

## Body

`application/json`

- `content` (`object`, required)
- `content.kind` (`string`, required)
- `content.data` (`string | null`, optional)
- `content.mime_type` (`string | null`, optional)
- `content.name` (`string | null`, optional)
- `content.url` (`string | null`, optional)
- `deployment_id` (`string | null`, optional)
- `external_artifact_id` (`string | null`, optional)
- `external_session_id` (`string | null`, optional)
- `internal_session_id` (`string | null`, optional)
- `metadata` (`null | object`, optional)
- `metadata.{key}` (`object`, optional)
- `metadata.{key}.{key}` (`string | number<double> | boolean`, optional)
- `role` (`string | null`, optional)
- `span_id` (`string | null`, optional)
- `trace_id` (`string | null`, optional)

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/artifact' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2026-06-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "content": {
    "kind": "<string>",
    "data": "<string>",
    "mime_type": "<string>",
    "name": "<string>",
    "url": "<string>"
  },
  "deployment_id": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "metadata": {
    "<key>": {
      "<key>": "<string>"
    }
  },
  "role": "<string>",
  "span_id": "<string>",
  "trace_id": "<string>"
}'
```

## Response

### 200

Success

`application/json`

- `policies` (`object`, required)
- `policies.{key}` (`object`, optional)
- `policies.{key}.flagged` (`boolean`, required)
- `policies.{key}.flagged_source` (`string[]`, required)
- `policies.{key}.name` (`string`, required)
- `kind` (`string`, required)
- `status` (`string`, required)
- `internal_artifact_id` (`string`, required)
- `flagged` (`boolean | null`, optional)
- `updated_at` (`string | null`, optional)
- `external_artifact_id` (`string | null`, optional)
- `external_session_id` (`string | null`, optional)
- `internal_session_id` (`string | null`, optional)
- `created_at` (`string | null`, optional)
- `note` (`string | null`, optional)

**Example**

```json
{
  "policies": {
    "<key>": {
      "flagged": true,
      "flagged_source": [
        "<string>"
      ],
      "name": "<string>"
    }
  },
  "kind": "<string>",
  "status": "<string>",
  "internal_artifact_id": "<string>",
  "flagged": true,
  "updated_at": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "created_at": "<string>",
  "note": "<string>"
}
```

### 400

Bad Request
