Sessions

Check Content

POST
/api/session

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

Request Overview

FieldTypeRequiredDescription
messagesarray✓Array of messages to analyze
deployment_idstringOptional deployment override. If omitted, White Circle uses the deployment associated with your API key.
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

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

FieldDescription
sessionSession-level verdict, IDs, and policy results
artifactsResults for every inline or referenced artifact you explicitly included in this request

The session object includes:

FieldDescription
flaggedtrue if any session-level 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
noteInformational 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 and Get Artifact Results.

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:

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.

Authorizations

  • Authorizationstringheaderrequired

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

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-04-15"

Body

application/json

  • messagesobject[]required

    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"

  • external_session_idstring | null

  • include_contextboolean | null

  • metadataobject

    Show child attributes
    • metadata.{key}object

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

  • deployment_idstring | null

Response

application/json

Success

  • sessionobjectrequired

    Show child attributes
    • session.flaggedbooleanrequired

    • session.internal_session_idstringrequired

    • session.policiesobjectrequired

      Show child attributes
      • session.policies.{key}object

        Show child attributes
        • session.policies.{key}.flaggedbooleanrequired

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

          Available options: text, image

        • session.policies.{key}.namestringrequired

    • session.external_session_idstring | null

    • session.notestring | null

  • artifactsobject[]required

    Show child attributes
    • artifacts.policiesobjectrequired

      Show child attributes
      • artifacts.policies.{key}object

        Show child attributes
        • artifacts.policies.{key}.flaggedbooleanrequired

        • artifacts.policies.{key}.flagged_sourcestring[]required

        • artifacts.policies.{key}.namestringrequired

    • artifacts.kindstringrequired

    • artifacts.statusstringrequired

    • artifacts.internal_artifact_idstringrequired

    • artifacts.flaggedboolean | null

    • artifacts.updated_atstring | null

    • artifacts.external_artifact_idstring | null

    • artifacts.external_session_idstring | null

    • artifacts.internal_session_idstring | null

    • artifacts.created_atstring | null

    • artifacts.notestring | null