# Check Artifact

> Check a single content artifact against deployment policies. Currently supports image artifacts.

`POST /api/artifact/check`

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

OpenAPI: [2025-12-01/openapi.json](https://whitecircle.com/docs/2025-12-01/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 | ✓        | The deployment ID to check against                                                                                                                |
| `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/2025-12-01/artifact/get-artifact.md)
* Referencing the artifact in [session checks](https://whitecircle.com/docs/2025-12-01/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`, the most recently created one within the deployment is returned 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/2025-12-01/session/images.md) request referencing it by ID. The artifact won't be re-checked — White Circle will use the existing result.

> [!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: `"2025-12-01"`.

## Body

`application/json`

Request body for checking a content artifact.

- `content` (`object`, required): Artifact content payload. See Content Constraints in the docs for supported formats and limits.
- `content.kind` (`string`, required): Artifact kind. Currently supported: "image".
- `content.data` (`string | null`, optional): Base64-encoded content (with or without data: URI prefix). Exactly one of url or data required.
- `content.mime_type` (`string | null`, optional): MIME type (e.g., "image/png"). Optional — automatically detected from image bytes.
- `content.name` (`string | null`, optional): Display name (e.g., "photo.png").
- `content.url` (`string | null`, optional): URL to fetch content from. Exactly one of url or data required.
- `deployment_id` (`string`, required): The deployment ID to check against.
- `external_artifact_id` (`string | null`, optional): Your custom artifact tracking ID.
- `external_session_id` (`string | null`, optional): Attach artifact to an existing session by your external session ID.
- `internal_session_id` (`string | null`, optional): Attach artifact to an existing session by internal UUID.
- `metadata` (`null | object`, optional): Arbitrary key-value metadata.
- `metadata.{key}` (`object`, optional)
- `metadata.{key}.{key}` (`string | number<double> | boolean`, optional)

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/artifact/check' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2025-12-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/uploads/avatar-42.jpg"
  },
  "deployment_id": "your-deployment-id",
  "external_artifact_id": "user-avatar-42",
  "external_session_id": "user-session-123"
}'
```

## Response

### 200

Artifact check completed

`application/json`

Artifact check result.

- `status` (`string`, required): Check status: "completed".
- `policies` (`object`, required): Map of policy ID to violation result.
- `policies.{key}` (`object`, optional): Policy violation result for an artifact check.
- `policies.{key}.flagged` (`boolean`, required): Whether this policy was violated.
- `policies.{key}.flagged_source` (`string[]`, required): Content types that triggered the violation (e.g., ["image"]).
- `policies.{key}.name` (`string`, required): Policy display name.
- `internal_artifact_id` (`string`, required): System-generated UUID for this artifact.
- `kind` (`string`, required): Echo of content.kind from request.
- `flagged` (`boolean | null`, optional): true if any policy was violated.
- `external_artifact_id` (`string | null`, optional): Your custom artifact ID (if provided).
- `internal_session_id` (`string | null`, optional): Internal ID of the linked session (if attached).
- `external_session_id` (`string | null`, optional): External ID of the linked session (if provided).
- `created_at` (`string | null`, optional): ISO 8601 creation timestamp.
- `updated_at` (`string | null`, optional): ISO 8601 last update timestamp.
- `note` (`string | null`, optional): Informational note (only present when applicable).

**Example**

```json
{
  "flagged": true,
  "policies": {
    "7eb45909-35a3-4bcb-81b9-049fc7413dba": {
      "name": "No Explicit Content",
      "flagged": true,
      "flagged_source": [
        "image"
      ]
    },
    "ad1f958e-e167-4e06-befc-434fd42563c9": {
      "name": "No Violence",
      "flagged": false,
      "flagged_source": []
    }
  },
  "kind": "image",
  "status": "completed",
  "created_at": "2025-12-01T10:30:00Z",
  "updated_at": "2025-12-01T10:30:00Z",
  "internal_artifact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_artifact_id": "user-avatar-42",
  "internal_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "external_session_id": "user-session-123"
}
```

### 400

Bad Request
