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

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

<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](/2026-04-15/artifact/get-artifact)
* Referencing the artifact in [session checks](/2026-04-15/session/images) by your own ID

```json theme={null}
{
  "deployment_id": "your-deployment-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 deployment on lookup.</Info>

## 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 theme={null}
{
  "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](/2026-04-15/session/images) request referencing it by ID. The artifact won't be re-checked — White Circle will use the existing result.

<Info>The object returned here is also the object you receive inside `artifacts[]` on the [Check Content](/2026-04-15/session/check-session) response.</Info>

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

<Info>Sessions can be on any deployment within the same team — the artifact and session don't need to share the same deployment.</Info>

## 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}
{
  "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                          |


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

````