> ## 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 content in the OpenAI-like message format and receive a session-level verdict plus artifact-level results for any inline or referenced artifacts you explicitly include. [Metrics](/2026-04-15/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 session envelope with the overall session verdict and any explicit artifact results

<Info>Each check is associated with a **session**. Sessions help you track content over time and enable features like [context merging](/2026-04-15/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  |          | Optional deployment override. If omitted, White Circle uses the deployment associated with your API key.                                              |
| `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](/2026-04-15/session/context). |
| `metadata`            | object  |          | Session-level metadata. See [Metadata](/2026-04-15/session/metadata)                                                                                  |

## Response Overview

The endpoint returns a single object with two top-level fields:

| Field       | Description                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| `session`   | Session-level verdict, IDs, and policy results                                          |
| `artifacts` | Results for every inline or referenced artifact you explicitly included in this request |

The `session` object includes:

| Field                 | Description                                     |
| --------------------- | ----------------------------------------------- |
| `flagged`             | `true` if any session-level 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   |
| `note`                | Informational note when applicable              |

Each policy object in `session.policies` 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

Each object in `artifacts[]` uses the same response shape as [Check Artifact](/2026-04-15/artifact/check-artifact) and [Get Artifact Results](/2026-04-15/artifact/get-artifact).

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

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

  <Card title="Images" icon="image" href="/2026-04-15/session/images">
    Images inline or by reference via artifact content parts
  </Card>

  <Card title="Artifacts" icon="cube" href="/2026-04-15/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="/2026-04-15/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="/2026-04-15/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](/2026-04-15/session/get-session)
* Use [context merging](/2026-04-15/session/context) to send incremental updates
* Enable [Risk Scoring](/2026-04-15/user/radar) by associating sessions with users

## Example Response

```json theme={null}
{
  "session": {
    "flagged": true,
    "internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "external_session_id": "user-123-conversation-456",
    "policies": {
      "70289e06-9111-463e-b121-7247c2b7bfbd": {
        "flagged": false,
        "flagged_source": [],
        "name": "No PII Sharing"
      },
      "a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
        "flagged": true,
        "flagged_source": ["text", "image"],
        "name": "Drugs"
      }
    }
  },
  "artifacts": []
}
```

For a response example with populated `artifacts[]`, see [Checking Images](/2026-04-15/session/images).


## OpenAPI

````yaml POST /api/session
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/session:
    post:
      tags:
        - Session
      operationId: 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/CheckRequestV4'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionEnvelopeV4'
        '400':
          description: Bad Request
      security:
        - bearerAuth: []
components:
  schemas:
    CheckRequestV4:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RequestChatMessageV3'
        external_session_id:
          type:
            - string
            - 'null'
        include_context:
          type:
            - boolean
            - 'null'
        metadata:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
            propertyNames:
              type: string
          propertyNames:
            type: string
        deployment_id:
          type:
            - string
            - 'null'
      example:
        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
        external_session_id: user-session-123
        include_context: true
        metadata:
          session:
            timestamp: '2026-04-15T10:00:00Z'
        deployment_id: your-deployment-id
    SessionEnvelopeV4:
      type: object
      required:
        - session
        - artifacts
      properties:
        session:
          $ref: '#/components/schemas/CheckResponseV4'
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactCheckResponse'
      example:
        session:
          flagged: true
          internal_session_id: 123e4567-e89b-12d3-a456-426614174000
          external_session_id: user-session-001
          policies:
            70289e06-9111-463e-b121-7247c2b7bfbd:
              flagged: true
              flagged_source:
                - text
              name: No PII Sharing
        artifacts:
          - flagged: true
            policies:
              70289e06-9111-463e-b121-7247c2b7bfbd:
                flagged: true
                flagged_source:
                  - image
                name: No PII Sharing
            kind: image
            status: completed
            updated_at: '2026-04-15T12:00:00Z'
            internal_artifact_id: 223e4567-e89b-12d3-a456-426614174000
            external_artifact_id: artifact-001
            external_session_id: user-session-001
            internal_session_id: 123e4567-e89b-12d3-a456-426614174000
            created_at: '2026-04-15T12:00:00Z'
    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
    CheckResponseV4:
      type: object
      required:
        - flagged
        - internal_session_id
        - policies
      properties:
        flagged:
          type: boolean
        internal_session_id:
          type: string
        external_session_id:
          type:
            - string
            - 'null'
        policies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PolicyStatusV3'
          propertyNames:
            type: string
        note:
          type:
            - string
            - 'null'
      example:
        flagged: true
        internal_session_id: 123e4567-e89b-12d3-a456-426614174000
        external_session_id: user-session-001
        policies:
          70289e06-9111-463e-b121-7247c2b7bfbd:
            flagged: true
            flagged_source:
              - text
            name: No PII Sharing
    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'
    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'
    PolicyStatusV3:
      type: object
      required:
        - flagged
        - flagged_source
        - name
      properties:
        flagged:
          type: boolean
        flagged_source:
          type: array
          items:
            $ref: '#/components/schemas/ViolationSource'
        name:
          type: string
    ArtifactPolicyStatus:
      type: object
      required:
        - flagged
        - flagged_source
        - name
      properties:
        flagged:
          type: boolean
        flagged_source:
          type: array
          items:
            type: string
        name:
          type: string
    RequestContentPart:
      oneOf:
        - type: object
          required:
            - text
            - type
          properties:
            text:
              type: string
            type:
              type: string
              enum:
                - text
        - type: object
          required:
            - image_url
            - type
          properties:
            image_url:
              $ref: '#/components/schemas/RequestImageUrl'
            type:
              type: string
              enum:
                - image_url
        - type: object
          required:
            - text
            - type
          properties:
            text:
              type: string
            type:
              type: string
              enum:
                - input_text
        - type: object
          required:
            - image_url
            - type
          properties:
            image_url:
              type: string
            type:
              type: string
              enum:
                - input_image
        - type: object
          required:
            - type
          properties:
            content:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ArtifactContent'
            external_artifact_id:
              type:
                - string
                - 'null'
            internal_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
    ViolationSource:
      type: string
      enum:
        - text
        - image
    RequestImageUrl:
      type: object
      required:
        - url
      properties:
        detail:
          type:
            - string
            - 'null'
        url:
          type: string
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````