# Check Content

`POST /api/session/check`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [2025-12-01/openapi.json](https://whitecircle.com/docs/2025-12-01/openapi.json)

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](https://whitecircle.com/docs/2025-12-01/first-steps/metrics.md) 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

> [!NOTE]
> Each check is associated with a **session**. Sessions help you track content over time and enable features like [context merging](https://whitecircle.com/docs/2025-12-01/session/context.md).

> [!NOTE]
> 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.

## 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](https://whitecircle.com/docs/2025-12-01/session/context.md). |
| `metadata`            | object  |          | Session-level metadata. See [Metadata](https://whitecircle.com/docs/2025-12-01/session/metadata.md)                                                                                  |

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

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

- **[Text](https://whitecircle.com/docs/2025-12-01/session/text.md)**: Plain text content in string format
- **[Images](https://whitecircle.com/docs/2025-12-01/session/images.md)**: Images inline or by reference via artifact content parts
- **[Artifacts](https://whitecircle.com/docs/2025-12-01/artifact/check-artifact.md)**: Standalone content checks for images, with pre-check and reference support

## Advanced Features

- **[Context Merging](https://whitecircle.com/docs/2025-12-01/session/context.md)**: Send only new messages and let White Circle automatically merge them with the previous session context
- **[Metadata](https://whitecircle.com/docs/2025-12-01/session/metadata.md)**: Attach user information, timestamps, and custom data to enable risk scoring and analytics

## Session Tracking

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

![Example external_session_id usage for session tracking](https://whitecircle.com/docs/assets/images/session/external_id.png?ref=5031e8d4c735c71c7cc31f68386616035c0bc013)

| 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
{
  "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](https://whitecircle.com/docs/2025-12-01/session/get-session.md)
* Use [context merging](https://whitecircle.com/docs/2025-12-01/session/context.md) to send incremental updates
* Enable [Risk Scoring](https://whitecircle.com/docs/2025-12-01/user/radar.md) by associating sessions with users

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2025-12-01"`.

## Body

`application/json`

- `messages` (`object[]`, required): Array of chat messages to analyze for policy violations.
- `messages.role` (`string`, required)
- `messages.content` (`null | string | object[]`, optional)
- `messages.content`, string (`string`)
- `messages.content`, object[] (`object[]`)
  - `messages.content`, text (`object`)
    - `messages.content.text` (`string`, required)
    - `messages.content.type` (`enum<string>`, required): Available options: `text`.
  - `messages.content`, input_text (`object`)
    - `messages.content.text` (`string`, required)
    - `messages.content.type` (`enum<string>`, required): Available options: `input_text`.
  - `messages.content`, artifact (`object`)
    - `messages.content.type` (`enum<string>`, required): Available options: `artifact`.
    - `messages.content.internal_artifact_id` (`string | null`, optional)
    - `messages.content.content` (`null | object`, optional): Artifact content payload.
    - `messages.content.content.kind` (`string`, required): Artifact kind. Currently supported: "image".
    - `messages.content.content.data` (`string | null`, optional): Base64-encoded content (with or without data: URI prefix). Exactly one of url or data required.
    - `messages.content.content.mime_type` (`string | null`, optional): MIME type (e.g., "image/png"). Optional — automatically detected from image bytes.
    - `messages.content.content.name` (`string | null`, optional): Display name (e.g., "photo.png").
    - `messages.content.content.url` (`string | null`, optional): URL to fetch content from. Exactly one of url or data required.
    - `messages.content.external_artifact_id` (`string | null`, optional)
- `messages.metadata` (`null | object`, optional)
- `messages.metadata.assistant` (`null | object`, optional)
- `messages.metadata.assistant.latency` (`number<double> | null`, optional)
- `messages.metadata.assistant.model_name` (`string | null`, optional)
- `messages.metadata.assistant.provider_url` (`string | null`, optional)
- `messages.metadata.message` (`null | object`, optional)
- `messages.metadata.message.id` (`string | null`, optional)
- `messages.metadata.message.timestamp` (`string | null`, optional)
- `messages.metadata.user` (`null | object`, optional)
- `messages.metadata.user.city` (`string | null`, optional): City name. Example: `"San Francisco"`.
- `messages.metadata.user.country` (`string | null`, optional): Full country name. Example: `"United States"`.
- `messages.metadata.user.country_code` (`string | null`, optional): ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB'). Example: `"US"`.
- `messages.metadata.user.email` (`string | null`, optional)
- `messages.metadata.user.id` (`string | null`, optional)
- `messages.metadata.user.ip` (`string | null`, optional): User's IP address for geolocation lookup. Example: `"8.8.8.8"`.
- `messages.metadata.user.latitude` (`number<double> | null`, optional): Latitude coordinate. Example: `37.7749`.
- `messages.metadata.user.longitude` (`number<double> | null`, optional): Longitude coordinate. Example: `-122.4194`.
- `messages.metadata.user.name` (`string | null`, optional)
- `messages.metadata.user.state` (`string | null`, optional): State/province name or code. Example: `"California"`.
- `deployment_id` (`string`, required): The deployment ID to check against.
- `external_session_id` (`string | null`, optional): Optional external identifier for tracking this session.
- `include_context` (`boolean | null`, optional): Include previous conversation context. Defaults to true if external_session_id is provided.
- `metadata` (`object`, optional): Optional session-level metadata.
- `metadata.{key}` (`object`, optional)
- `metadata.{key}.{key}` (`any`, optional)
- `policies` (`string[] | null`, optional): Optional list of specific policy IDs to check against. If omitted, all deployment policies are used.

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/session/check' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2025-12-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
    }
  }
}'
```

## Response

### 200

Success

`application/json`

- `flagged` (`boolean`, required)
- `internal_session_id` (`string`, required)
- `policies` (`object`, required)
- `policies.{key}` (`object`, optional)
- `policies.{key}.flagged` (`boolean`, required)
- `policies.{key}.flagged_source` (`enum<string>[]`, required): Available options: `text`, `image`.
- `policies.{key}.name` (`string`, required)
- `external_session_id` (`string | null`, optional)
- `note` (`string | null`, optional)

**Example**

```json
{
  "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"
    }
  }
}
```

### 400

Bad Request
