# Check Artifact

`POST /api/artifact`

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

OpenAPI: [2026-04-15/openapi.json](https://whitecircle.com/docs/2026-04-15/openapi.json)

Check a single content artifact against your deployment’s policies. Use this endpoint to moderate standalone content such as 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. White Circle analyzes the content against applicable policies configured in your deployment
3. You receive a synchronous response with policy violations

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

## Request Overview

| Field                   | Type   | Required | Description                                                                                                                                       |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`               | object | ✓        | Artifact content payload. See [Content Constraints](#content-constraints) below.                                                                  |
| `content.kind`          | string | ✓        | Content type: `"image"`                                                                                                                           |
| `content.url`           | string |          | URL to fetch the image from. Provide either `url` or `data`, not both.                                                                            |
| `content.data`          | string |          | Base64-encoded image data. Provide either `url` or `data`, not both.                                                                              |
| `content.mime_type`     | string |          | MIME type (e.g., `image/jpeg`). Auto-detected if omitted.                                                                                         |
| `deployment_id`         | string |          | Optional deployment override. If omitted, White Circle uses the deployment associated with your API key.                                          |
| `role`                  | string |          | The role that produced this artifact. Controls which policies apply. See [Role-Based Filtering](#role-based-filtering) below.                      |
| `external_artifact_id`  | string |          | Your custom artifact tracking ID. See [External Artifact ID](#external-artifact-id) below.                                                        |
| `internal_session_id`   | string |          | Attach artifact to an existing session by its system-generated UUID.                                                                              |
| `external_session_id`   | string |          | Attach artifact to an existing session by your custom session ID.                                                                                 |
| `metadata`              | object |          | Arbitrary key-value metadata.                                                                                                                     |

## Response Overview

| Field                   | Type            | Description                                                                                 |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------- |
| `flagged`               | boolean \| null | `true` if any policy was violated. `null` while processing or on failure.                   |
| `policies`              | object          | Map of policy IDs to their violation statuses                                                |
| `kind`                  | string          | Echo of `content.kind` from request (e.g., `"image"`)                                        |
| `status`                | string          | Check status: `"completed"`, `"processing"`, or `"failed"`. Images are always `"completed"`. |
| `updated_at`            | string          | ISO 8601 last update timestamp                                                               |
| `internal_artifact_id`  | string          | System-generated UUID for this artifact                                                      |
| `external_artifact_id`  | string          | Your custom artifact tracking ID (if provided)                                               |
| `external_session_id`   | string          | External ID of the linked session (if attached)                                              |
| `internal_session_id`   | string          | System-generated UUID of the linked session (if attached)                                    |
| `created_at`            | string          | ISO 8601 creation timestamp                                                                  |
| `note`                  | string          | Informational message when applicable (e.g., why an image fetch failed)                      |

Each policy in the `policies` object includes:

* `name` — Human-readable policy name
* `flagged` — Whether this specific policy was violated
* `flagged_source` — Array of content types that triggered the violation (e.g., `["image"]`)

## 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/2026-04-15/artifact/get-artifact.md)
* Referencing the artifact in [session checks](https://whitecircle.com/docs/2026-04-15/session/images.md) by your own ID

```json
{
  "deployment_id": "your-deployment-id",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/uploads/avatar-42.jpg"
  },
  "external_artifact_id": "user-avatar-42"
}
```

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

## Attach to a Session

You can optionally attach an artifact to an existing session by providing `internal_session_id` or `external_session_id`. This connects the artifact to the session for tracking and analytics.

```json
{
  "deployment_id": "your-deployment-id",
  "content": {
    "kind": "image",
    "url": "https://storage.example.com/uploads/photo.jpg"
  },
  "external_session_id": "user-session-123"
}
```

To directly attach this artifact to a session, send a [session check](https://whitecircle.com/docs/2026-04-15/session/images.md) request referencing it by ID. The artifact won't be re-checked — White Circle will use the existing result.

> [!NOTE]
> The object returned here is also the object you receive inside `artifacts[]` on the [Check Content](https://whitecircle.com/docs/2026-04-15/session/check-session.md) response.

> [!WARNING]
> The session must already exist before you can attach an artifact to it. If the provided session ID doesn't match any existing session, the artifact is created without a session link.

> [!NOTE]
> Sessions can be on any deployment within the same team — the artifact and session don't need to share the same deployment.

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

```json
{
  "deployment_id": "your-deployment-id",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/ai-generated-image.png"
  },
  "role": "assistant"
}
```

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

## Authorizations

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

## Headers

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

## 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-04-15' \
  --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
