# Check Session

`POST /api/protect/check`

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

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

> [!WARNING]
> `image_url` and `input_image` content parts are not supported. To submit images, use the artifact API or a newer session API version with `artifact` content parts.

## Authorizations

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

## Headers

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

## Body

`application/json`

- `messages` (`object[]`, required): Array of chat messages to analyze for policy violations. Required.
- `messages.role` (`enum<string>`, required): Available options: `system`, `assistant`, `user`.
- `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`.
- `external_id` (`string | null`, optional): Optional external identifier for tracking this session. Useful for correlating results with your own systems.
- `include_context` (`boolean | null`, optional): Include previous conversation context associated with the same external_id. Default: false.
- `include_policy_names` (`boolean | null`, optional): Include human-readable policy names in the response. Default: false.
- `metadata` (`object`, optional): Optional metadata object for additional info about session.
- `metadata.{key}` (`object`, optional)
- `metadata.{key}.{key}` (`any`, optional)
- `policies` (`string[] | null`, optional): Optional list of specific policy IDs to check. If omitted, all deployment policies are used.

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/protect/check' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2025-06-15' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_id": "user-session-123",
  "include_context": true,
  "include_policy_names": true,
  "messages": [
    {
      "content": "Hello, can you help me with something?",
      "role": "user"
    },
    {
      "content": [
        {
          "text": "Of course! I'\''d be happy to help you.",
          "type": "text"
        }
      ],
      "role": "assistant"
    }
  ],
  "metadata": {
    "model": {
      "name": "gpt-4.1",
      "price_per_1m_tokens": 0.1
    },
    "user": {
      "id": "abcd-1234"
    }
  }
}'
```

## Response

### 200

Success

`application/json`

- `internal_id` (`string`, required): Unique internal identifier for this check.
- `violation` (`boolean`, required): Whether any policy violations were detected.
- `violations` (`object`, required): Map of policy IDs to policy status objects containing violation and optional name.
- `violations.{key}` (`object`, optional)
- `violations.{key}.violation` (`boolean`, required): Whether a violation was detected for this policy.
- `violations.{key}.violation_source` (`enum<string>[]`, required): Sources where violations were detected (includes only triggered violations). Available options: `text`, `image`.
- `violations.{key}.name` (`string | null`, optional): Human-readable policy name (only present if include_policy_names=true).
- `external_id` (`string | null`, optional): Optional external identifier provided by client.

**Example**

```json
{
  "external_id": "user-session-001",
  "internal_id": "123e4567-e89b-12d3-a456-426614174000",
  "violation": true,
  "violations": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "name": "NSFW",
      "violation": true,
      "violation_source": [
        "image"
      ]
    },
    "70289e06-9111-463e-b121-7247c2b7bfbd": {
      "name": "No PII Sharing",
      "violation": false,
      "violation_source": []
    },
    "a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
      "name": "Drugs",
      "violation": true,
      "violation_source": [
        "text"
      ]
    }
  }
}
```

### 400

Bad Request
