Sessions

Check Content

POST
/api/session/check

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

Request Overview

FieldTypeRequiredDescription
messagesarray✓Array of messages to analyze
deployment_idstring✓The deployment ID to check against
external_session_idstringYour custom tracking ID
include_contextbooleanAutomatically include previous messages. Defaults to true if external_session_id is provided. See Context Merging.
metadataobjectSession-level metadata. See Metadata

Response Overview

FieldDescription
flaggedtrue if any policy was violated
internal_session_idSystem-generated UUID for this session
external_session_idYour custom tracking ID (if provided)
policiesMap 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:

RoleDescription
systemSystem prompts or instructions
userUser-created content
assistantAI-generated content
toolTool/function call outputs
developerDeveloper-level instructions

The last message’s role determines which policies are evaluated:

Last message rolePolicies applied
user, system, developer, toolinput + any policies
assistantoutput + any policies

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

Content Types

White Circle supports different content formats within a message:

Text

Plain text content in string format

Images

Images inline or by reference via artifact content parts

Artifacts

Standalone content checks for images, with pre-check and reference support

Advanced Features

Context Merging

Send only new messages and let White Circle automatically merge them with the previous session context

Metadata

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:

Use CaseExample 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:

Authorizations

  • Authorizationstringheaderrequired

    API Key required. Format: Bearer wc-your-api-key

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2025-12-01"

Body

application/json

  • messagesobject[]required

    Array of chat messages to analyze for policy violations

    Show child attributes
    • messages.rolestringrequired

    • messages.contentnull | string | object[]

    • messages.metadatanull | object

      Show child attributes
      • messages.metadata.assistantnull | object

        Show child attributes
        • messages.metadata.assistant.latencynumber<double> | null

        • messages.metadata.assistant.model_namestring | null

        • messages.metadata.assistant.provider_urlstring | null

      • messages.metadata.messagenull | object

        Show child attributes
        • messages.metadata.message.idstring | null

        • messages.metadata.message.timestampstring | null

      • messages.metadata.usernull | object

        Show child attributes
        • messages.metadata.user.citystring | null

          City name

          Example: "San Francisco"

        • messages.metadata.user.countrystring | null

          Full country name

          Example: "United States"

        • messages.metadata.user.country_codestring | null

          ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')

          Example: "US"

        • messages.metadata.user.emailstring | null

        • messages.metadata.user.idstring | null

        • messages.metadata.user.ipstring | null

          User's IP address for geolocation lookup

          Example: "8.8.8.8"

        • messages.metadata.user.latitudenumber<double> | null

          Latitude coordinate

          Example: 37.7749

        • messages.metadata.user.longitudenumber<double> | null

          Longitude coordinate

          Example: -122.4194

        • messages.metadata.user.namestring | null

        • messages.metadata.user.statestring | null

          State/province name or code

          Example: "California"

  • deployment_idstringrequired

    The deployment ID to check against

  • external_session_idstring | null

    Optional external identifier for tracking this session

  • include_contextboolean | null

    Include previous conversation context. Defaults to true if external_session_id is provided

  • metadataobject

    Optional session-level metadata

    Show child attributes
    • metadata.{key}object

      Show child attributes
      • metadata.{key}.{key}any

  • policiesstring[] | null

    Optional list of specific policy IDs to check against. If omitted, all deployment policies are used

Response

application/json

Success

  • flaggedbooleanrequired

  • internal_session_idstringrequired

  • policiesobjectrequired

    Show child attributes
    • policies.{key}object

      Show child attributes
      • policies.{key}.flaggedbooleanrequired

      • policies.{key}.flagged_sourceenum<string>[]required

        Available options: text, image

      • policies.{key}.namestringrequired

  • external_session_idstring | null

  • notestring | null