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

# Check Artifact

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.

<Info>Image Artifacts are checked synchronously — you receive results immediately in the response.</Info>

<Info>`mime_type` is optional for all submission methods. White Circle detects the image format automatically from the content bytes.</Info>

## 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.                                                                     |
| `environment_id`       | string |          | Optional Environment override. If omitted, White Circle uses the Environment associated with your API key.                    |
| `deployment_id`        | string |          | **Deprecated** — predecessor of `environment_id`, still accepted for backwards compatibility. Prefer `environment_id`.        |
| `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.                    |
| `status`               | string          | Check status: `"completed"`, `"processing"`, or `"failed"`. Images are always `"completed"`. |
| `policies`             | object          | Map of Policy IDs to their violation statuses                                                |
| `kind`                 | string          | Echo of `content.kind` from request (e.g., `"image"`)                                        |
| `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)                                    |
| `updated_at`           | string          | ISO 8601 last update timestamp                                                               |
| `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:

* `flagged` — Whether this specific Policy was violated
* `name` — Human-readable Policy name
* `enabled_by_conditions` — The Conditions that selected this Policy, which is why it was evaluated. Absent when no Condition was involved.

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

<Info>Checking image Artifacts is always synchronous — the response always has status `"completed"`.</Info>

## 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](/latest/artifact/get-artifact)
* Tracking standalone artifact checks with your own ID

```json theme={null}
{
  "environment_id": "your-environment-id",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/uploads/avatar-42.jpg"
  },
  "external_artifact_id": "user-avatar-42"
}
```

<Info>If multiple artifacts share the same `external_artifact_id`, White Circle returns the latest artifact version within the same Environment on lookup.</Info>

## 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](/latest/events/artifacts) when you want to check an image as part of an Events workflow with `run_id`, `event_id`, and `internal_event_id`.

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

## 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 theme={null}
{
  "role": "assistant",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/ai-generated-image.png"
  },
  "environment_id": "your-environment-id"
}
```

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


## OpenAPI

````yaml POST /api/artifact
openapi: 3.1.0
info:
  title: WhiteCircle API Backend
  description: 'Authentication: Bearer API Key Required'
  license:
    name: ''
  version: '2026-04-15'
servers:
  - url: https://eu.whitecircle.com
  - url: https://us.whitecircle.com
security: []
tags:
  - name: Session
    description: Session-based content checking and moderation
  - name: User
    description: User risk assessment and scoring
  - name: Policy
    description: Policy management CRUD
  - name: Metric
    description: Metric management CRUD
  - name: Artifact
    description: Standalone artifact moderation
paths:
  /api/artifact:
    post:
      tags:
        - Artifact
      operationId: artifact_check_v4
      parameters:
        - name: whitecircle-version
          in: header
          description: API Version
          required: true
          schema:
            type: string
          example: '2026-04-15'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactCheckRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactCheckResponse'
        '400':
          description: Bad Request
      security:
        - bearerAuth: []
components:
  schemas:
    ArtifactCheckRequest:
      type: object
      required:
        - content
      properties:
        content:
          $ref: '#/components/schemas/ArtifactContent'
        deployment_id:
          type:
            - string
            - 'null'
        external_artifact_id:
          type:
            - string
            - 'null'
        external_session_id:
          type:
            - string
            - 'null'
        internal_session_id:
          type:
            - string
            - 'null'
        metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/IndexMap'
        role:
          type:
            - string
            - 'null'
        span_id:
          type:
            - string
            - 'null'
        trace_id:
          type:
            - string
            - 'null'
    ArtifactCheckResponse:
      type: object
      required:
        - status
        - kind
        - internal_artifact_id
        - policies
      properties:
        flagged:
          type:
            - boolean
            - 'null'
        policies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ArtifactPolicyStatus'
          propertyNames:
            type: string
        kind:
          type: string
        status:
          type: string
        updated_at:
          type:
            - string
            - 'null'
        internal_artifact_id:
          type: string
        external_artifact_id:
          type:
            - string
            - 'null'
        external_session_id:
          type:
            - string
            - 'null'
        internal_session_id:
          type:
            - string
            - 'null'
        created_at:
          type:
            - string
            - 'null'
        note:
          type:
            - string
            - 'null'
    ArtifactContent:
      type: object
      required:
        - kind
      properties:
        data:
          type:
            - string
            - 'null'
        kind:
          type: string
        mime_type:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
    IndexMap:
      type: object
      additionalProperties:
        type: object
        additionalProperties:
          oneOf:
            - type: string
            - type: number
              format: double
            - type: boolean
        propertyNames:
          type: string
      propertyNames:
        type: string
    ArtifactPolicyStatus:
      type: object
      required:
        - flagged
        - flagged_source
        - name
      properties:
        flagged:
          type: boolean
        flagged_source:
          type: array
          items:
            type: string
        name:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````