> ## 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 deployment policies. Currently supports image artifacts.
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
Image artifacts are checked synchronously — you receive results immediately in the response.
`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. |
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](/2025-12-01/artifact/get-artifact)
* Referencing the artifact in [session checks](/2025-12-01/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"
}
```
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 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](/2025-12-01/session/images) request referencing it by ID. The artifact won't be re-checked — White Circle will use the existing result.
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.
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 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/check
openapi: 3.1.0
info:
title: WhiteCircle API Backend
description: 'Authentication: Bearer API Key Required'
license:
name: ''
version: '2025-12-01'
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/check:
post:
tags:
- Artifact
summary: Check artifact content
description: >-
Check a single content artifact against deployment policies. Currently
supports image artifacts.
operationId: artifact_check
parameters:
- name: whitecircle-version
in: header
description: API Version
required: true
schema:
type: string
example: '2025-12-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactCheckRequest'
required: true
responses:
'200':
description: Artifact check completed
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactCheckResponse'
'400':
description: Bad Request
security:
- bearerAuth: []
components:
schemas:
ArtifactCheckRequest:
type: object
required:
- content
- deployment_id
properties:
content:
$ref: '#/components/schemas/ArtifactContent'
description: >-
Artifact content payload. See Content Constraints in the docs for
supported formats and limits.
deployment_id:
type: string
description: The deployment ID to check against
external_artifact_id:
type:
- string
- 'null'
description: Your custom artifact tracking ID
external_session_id:
type:
- string
- 'null'
description: Attach artifact to an existing session by your external session ID
internal_session_id:
type:
- string
- 'null'
description: Attach artifact to an existing session by internal UUID
metadata:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/IndexMap'
description: Arbitrary key-value metadata
description: Request body for checking a content artifact.
example:
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
ArtifactCheckResponse:
type: object
required:
- status
- kind
- internal_artifact_id
- policies
properties:
status:
type: string
description: 'Check status: "completed"'
flagged:
type:
- boolean
- 'null'
description: true if any policy was violated
policies:
type: object
additionalProperties:
$ref: '#/components/schemas/ArtifactPolicyStatus'
propertyNames:
type: string
description: Map of policy ID to violation result
internal_artifact_id:
type: string
description: System-generated UUID for this artifact
external_artifact_id:
type:
- string
- 'null'
description: Your custom artifact ID (if provided)
internal_session_id:
type:
- string
- 'null'
description: Internal ID of the linked session (if attached)
external_session_id:
type:
- string
- 'null'
description: External ID of the linked session (if provided)
created_at:
type:
- string
- 'null'
description: ISO 8601 creation timestamp
updated_at:
type:
- string
- 'null'
description: ISO 8601 last update timestamp
kind:
type: string
description: Echo of content.kind from request
note:
type:
- string
- 'null'
description: Informational note (only present when applicable)
description: Artifact check result.
example:
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
ArtifactContent:
type: object
required:
- kind
properties:
data:
type:
- string
- 'null'
description: >-
Base64-encoded content (with or without data: URI prefix). Exactly
one of url or data required
kind:
type: string
description: 'Artifact kind. Currently supported: "image"'
mime_type:
type:
- string
- 'null'
description: >-
MIME type (e.g., "image/png"). Optional — automatically detected
from image bytes
name:
type:
- string
- 'null'
description: Display name (e.g., "photo.png")
url:
type:
- string
- 'null'
description: URL to fetch content from. Exactly one of url or data required
description: Artifact content payload.
example:
kind: image
url: https://cdn.example.com/uploads/avatar-42.jpg
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
description: Whether this policy was violated
flagged_source:
type: array
items:
type: string
description: Content types that triggered the violation (e.g., ["image"])
name:
type: string
description: Policy display name
description: Policy violation result for an artifact check.
example:
flagged: true
flagged_source:
- image
name: No Explicit Content
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'API Key required. Format: Bearer wc-your-api-key'
````