# Check Content

`POST /api/session`

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

OpenAPI: [2026-04-15/openapi.json](https://whitecircle.com/docs/2026-04-15/openapi.json)

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](https://whitecircle.com/docs/2026-04-15/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 session envelope with the overall session verdict and any explicit artifact results

> [!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/2026-04-15/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  |          | 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](https://whitecircle.com/docs/2026-04-15/session/context.md). |
| `metadata`            | object  |          | Session-level metadata. See [Metadata](https://whitecircle.com/docs/2026-04-15/session/metadata.md)                                                                                  |

## 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](https://whitecircle.com/docs/2026-04-15/artifact/check-artifact.md) and [Get Artifact Results](https://whitecircle.com/docs/2026-04-15/artifact/get-artifact.md).

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

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

## Advanced Features

- **[Context Merging](https://whitecircle.com/docs/2026-04-15/session/context.md)**: Send only new messages and let White Circle automatically merge them with the previous session context
- **[Metadata](https://whitecircle.com/docs/2026-04-15/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/2026-04-15/session/get-session.md)
* Use [context merging](https://whitecircle.com/docs/2026-04-15/session/context.md) to send incremental updates
* Enable [Risk Scoring](https://whitecircle.com/docs/2026-04-15/user/radar.md) by associating sessions with users

## Example Response

```json
{
  "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](https://whitecircle.com/docs/2026-04-15/session/images.md).

## Authorizations

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

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-04-15"`.

## Body

`application/json`

- `messages` (`object[]`, required)
- `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`, image_url (`object`)
    - `messages.content.image_url` (`object`, required)
    - `messages.content.image_url.url` (`string`, required)
    - `messages.content.image_url.detail` (`string | null`, optional)
    - `messages.content.type` (`enum<string>`, required): Available options: `image_url`.
  - `messages.content`, input_text (`object`)
    - `messages.content.text` (`string`, required)
    - `messages.content.type` (`enum<string>`, required): Available options: `input_text`.
  - `messages.content`, input_image (`object`)
    - `messages.content.image_url` (`string`, required)
    - `messages.content.type` (`enum<string>`, required): Available options: `input_image`.
  - `messages.content`, artifact (`object`)
    - `messages.content.type` (`enum<string>`, required): Available options: `artifact`.
    - `messages.content.content` (`null | object`, optional)
    - `messages.content.content.kind` (`string`, required)
    - `messages.content.content.data` (`string | null`, optional)
    - `messages.content.content.mime_type` (`string | null`, optional)
    - `messages.content.content.name` (`string | null`, optional)
    - `messages.content.content.url` (`string | null`, optional)
    - `messages.content.external_artifact_id` (`string | null`, optional)
    - `messages.content.internal_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"`.
- `external_session_id` (`string | null`, optional)
- `include_context` (`boolean | null`, optional)
- `metadata` (`object`, optional)
- `metadata.{key}` (`object`, optional)
- `metadata.{key}.{key}` (`any`, optional)
- `deployment_id` (`string | null`, optional)

## Request example

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

## Response

### 200

Success

`application/json`

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

**Example**

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

### 400

Bad Request
