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

This is the core endpoint for content moderation and analytics — send your content using the OpenAI-like message format and receive instant feedback on policy violations. [Metrics](/2025-12-01/first-steps/metrics) are computed for each request in the background.

## How It Works

1. You submit content as one or more messages
2. White Circle analyzes the content against all policies in your deployment
3. You receive a response indicating which (if any) policies got flagged

<Info>Each check is associated with a **session**. Sessions help you track content over time and enable features like [context merging](/2025-12-01/session/context).</Info>

<Info>
  Policies and metrics are evaluated against **only the last message** in the `messages` array. All preceding messages provide context for the evaluation but are not themselves checked for violations.
</Info>

## Request Overview

| Field                 | Type    | Required | Description                                                                                                                                           |
| --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`            | array   | ✓        | Array of messages to analyze                                                                                                                          |
| `deployment_id`       | string  | ✓        | The deployment ID to check against                                                                                                                    |
| `external_session_id` | string  |          | Your custom tracking ID                                                                                                                               |
| `include_context`     | boolean |          | Automatically include previous messages. Defaults to `true` if `external_session_id` is provided. See [Context Merging](/2025-12-01/session/context). |
| `metadata`            | object  |          | Session-level metadata. See [Metadata](/2025-12-01/session/metadata)                                                                                  |

## Response Overview

| Field                 | Description                                   |
| --------------------- | --------------------------------------------- |
| `flagged`             | `true` if any policy was violated             |
| `internal_session_id` | System-generated UUID for this session        |
| `external_session_id` | Your custom tracking ID (if provided)         |
| `policies`            | Map of policy IDs to their violation statuses |

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: `["text"]`, `["image"]`, or `["text", "image"]` when both text and image violated

## Message Roles

The API uses OpenAI-compatible message format. Each message must have a `role` field:

| Role        | Description                    |
| ----------- | ------------------------------ |
| `system`    | System prompts or instructions |
| `user`      | User-created content           |
| `assistant` | AI-generated content           |
| `tool`      | Tool/function call outputs     |
| `developer` | Developer-level instructions   |

The **last message's role** determines which policies are evaluated:

| Last message role                     | Policies applied          |
| ------------------------------------- | ------------------------- |
| `user`, `system`, `developer`, `tool` | `input` + `any` policies  |
| `assistant`                           | `output` + `any` policies |

Role strings with postfixes (e.g., `"user-12345"`, `"assistant-v2"`) are normalized to their base role.

<Tip>Send both user and assistant messages to detect violations in either direction, whether they're harmful requests from users or problematic responses from your AI.</Tip>

## Content Types

White Circle supports different content formats within a message:

<Warning>`image_url` and `input_image` content parts are not supported. To include images in a session, use `artifact` content parts.</Warning>

<CardGroup cols={3}>
  <Card title="Text" icon="font" href="/2025-12-01/session/text">
    Plain text content in string format
  </Card>

  <Card title="Images" icon="image" href="/2025-12-01/session/images">
    Images inline or by reference via artifact content parts
  </Card>

  <Card title="Artifacts" icon="cube" href="/2025-12-01/artifact/check-artifact">
    Standalone content checks for images, with pre-check and reference support
  </Card>
</CardGroup>

## Advanced Features

<CardGroup cols={2}>
  <Card title="Context Merging" icon="layer-group" href="/2025-12-01/session/context">
    Send only new messages and let White Circle automatically merge them with the previous session context
  </Card>

  <Card title="Metadata" icon="tag" href="/2025-12-01/session/metadata">
    Attach user information, timestamps, and custom data to enable risk scoring and analytics
  </Card>
</CardGroup>

## Session Tracking

Use `external_session_id` to track content using your own identifiers. This can be any string that makes sense for your application:

<Frame>
  <img
    src="https://mintcdn.com/whitecircle/qmSGRNF95Ca4SZT_/images/session/external_id.png?fit=max&auto=format&n=qmSGRNF95Ca4SZT_&q=85&s=18009c2db0dbf9b29f2cbffb449f6df5"
    alt="Example external_session_id usage for session tracking"
    style={{
height: '150px',
}}
    width="734"
    height="322"
    data-path="images/session/external_id.png"
  />
</Frame>

| Use Case          | Example `external_session_id`         |
| ----------------- | ------------------------------------- |
| Chat conversation | `"conversation-a1b2c3d4"`             |
| User session      | `"user-123-session-456"`              |
| Support ticket    | `"ticket-2024-001234"`                |
| Document review   | `"doc-review-draft-v2"`               |
| Thread/channel    | `"slack-channel-C04ABCD-thread-1234"` |

```json theme={null}
{
  "deployment_id": "your-deployment-id",
  "external_session_id": "user-123-conversation-456",
  "messages": [...]
}
```

Using `external_session_id` allows you to:

* Retrieve results later via [Retrieving Results](/2025-12-01/session/get-session)
* Use [context merging](/2025-12-01/session/context) to send incremental updates
* Enable [Risk Scoring](/2025-12-01/user/radar) by associating sessions with users


## OpenAPI

````yaml POST /api/session/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/session/check:
    post:
      tags:
        - Session
      operationId: check_v3
      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/CheckRequestV3'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResponseV3'
        '400':
          description: Bad Request
      security:
        - bearerAuth: []
components:
  schemas:
    CheckRequestV3:
      type: object
      required:
        - messages
        - deployment_id
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RequestChatMessageV3'
          description: Array of chat messages to analyze for policy violations
        deployment_id:
          type: string
          description: The deployment ID to check against
        external_session_id:
          type:
            - string
            - 'null'
          description: Optional external identifier for tracking this session
        include_context:
          type:
            - boolean
            - 'null'
          description: >-
            Include previous conversation context. Defaults to true if
            external_session_id is provided
        metadata:
          type: object
          description: Optional session-level metadata
          additionalProperties:
            type: object
            additionalProperties: {}
            propertyNames:
              type: string
          propertyNames:
            type: string
        policies:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Optional list of specific policy IDs to check against. If omitted,
            all deployment policies are used
      example:
        deployment_id: your-deployment-id
        external_session_id: user-session-123
        include_context: true
        messages:
          - content: Hello, can you help me with something?
            metadata:
              message:
                id: msg-123
              user:
                email: user@example.com
                id: user-456
            role: user
          - content:
              - text: Of course! I'd be happy to help you.
                type: text
            metadata:
              assistant:
                latency: 1.2
                model_name: gpt-4o-mini
            role: assistant
        metadata:
          session:
            timestamp: '2025-12-01T10:00:00Z'
    CheckResponseV3:
      type: object
      required:
        - flagged
        - internal_session_id
        - policies
      properties:
        external_session_id:
          type:
            - string
            - 'null'
        flagged:
          type: boolean
        internal_session_id:
          type: string
        note:
          type:
            - string
            - 'null'
        policies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PolicyStatusV3'
          propertyNames:
            type: string
      example:
        flagged: true
        internal_session_id: 123e4567-e89b-12d3-a456-426614174000
        external_session_id: user-session-001
        policies:
          70289e06-9111-463e-b121-7247c2b7bfbd:
            flagged: false
            flagged_source: []
            name: No PII Sharing
          a4a91875-1e54-42d7-b9b0-a75dfebeb057:
            flagged: true
            flagged_source:
              - text
            name: Drugs
    RequestChatMessageV3:
      type: object
      required:
        - role
      properties:
        content:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RequestChatContent'
        metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MessageMetadataV3'
        role:
          type: string
    PolicyStatusV3:
      type: object
      required:
        - flagged
        - flagged_source
        - name
      properties:
        flagged:
          type: boolean
        flagged_source:
          type: array
          items:
            $ref: '#/components/schemas/ViolationSource'
        name:
          type: string
    RequestChatContent:
      oneOf:
        - type: string
        - type: array
          items:
            $ref: '#/components/schemas/RequestContentPart'
    MessageMetadataV3:
      type: object
      properties:
        assistant:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AssistantInfoV3'
        message:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MessageInfoV3'
        user:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UserInfoV3'
    ViolationSource:
      type: string
      enum:
        - text
        - image
    RequestContentPart:
      oneOf:
        - type: object
          required:
            - text
            - type
          properties:
            text:
              type: string
            type:
              type: string
              enum:
                - text
        - type: object
          required:
            - text
            - type
          properties:
            text:
              type: string
            type:
              type: string
              enum:
                - input_text
        - type: object
          required:
            - type
          properties:
            internal_artifact_id:
              type:
                - string
                - 'null'
            content:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ArtifactContent'
            external_artifact_id:
              type:
                - string
                - 'null'
            type:
              type: string
              enum:
                - artifact
    AssistantInfoV3:
      type: object
      properties:
        latency:
          type:
            - number
            - 'null'
          format: double
        model_name:
          type:
            - string
            - 'null'
        provider_url:
          type:
            - string
            - 'null'
    MessageInfoV3:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
        timestamp:
          type:
            - string
            - 'null'
    UserInfoV3:
      type: object
      properties:
        city:
          type:
            - string
            - 'null'
          description: City name
          example: San Francisco
        country:
          type:
            - string
            - 'null'
          description: Full country name
          example: United States
        country_code:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')
          example: US
        email:
          type:
            - string
            - 'null'
        id:
          type:
            - string
            - 'null'
        ip:
          type:
            - string
            - 'null'
          description: User's IP address for geolocation lookup
          example: 8.8.8.8
        latitude:
          type:
            - number
            - 'null'
          format: double
          description: Latitude coordinate
          example: 37.7749
        longitude:
          type:
            - number
            - 'null'
          format: double
          description: Longitude coordinate
          example: -122.4194
        name:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
          description: State/province name or code
          example: California
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````