Getting Started

White Circle helps you control, analyze, and improve the behavior of your AI applications.

Quick Start

Create a Policy

At the core of White Circle are Policies — written descriptions of the rules you want your content to follow.Open the Policy list page and create a new one. Give the policy a name, flagged content, and allowed content. These fields define what exactly the Policy matches.

Example: Online Pharmacy Policy

You run an online pharmacy and want to prevent your chatbot from giving medical advice while still allowing questions about product availability.In this case:

Flagged content: “Providing medical advice”
Allowed content: “Answering questions about the availability of medicines in the store”

Once you’ve filled in the details, save the Policy.

Learn more about Policies

Understand how Policies work and best practices for defining them.

Create an Environment

An Environment isolates sessions across different deployments of your application, such as development, staging, and production.

Typical Environments

Development – Test new Policies while building your application.
Staging – Validate Policy changes against pre-production traffic.
Production – Evaluate live user traffic using your approved Policies.

To create an Environment, open the Environments page, click Add Environment, and select the Conditions to attach.

Learn more about Environments

See how to organize your system into Environments for different use cases.

Create a Condition

A Condition determines which Policies and Metrics evaluate each Event by matching that Event’s metadata.Open the Conditions page and create a Condition for your Environment. Attach a Policy you created above. For this quick start, use a filter that matches environment equal to quickstart.

Policies run only when an active Condition attached to the Environment matches the Event metadata. If no Condition matches, the Event is processed without any Policies.

Learn more about Conditions

Learn how Conditions match Events to Policies and Metrics.

Create an API Key

Go to your API Keys page and generate a new key.

We recommend creating separate API keys for each Environment. That way, you can revoke a single key without affecting your other Environments.

Your API key will have the prefix wceu- or wcus- depending on the region you’re in.

Send Your First Request

You’re ready to make your first API call! Use the examples below to evaluate a message against your Policies.

curl -X POST https://eu.whitecircle.com/api/event \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "Content-Type: application/json" \
  -H "whitecircle-version: 2026-06-01" \
  -d '{
    "event": {
      "type": "message",
      "role": "user",
      "content": "Hello, can you help me prescribe antibiotics?",
      "metadata": { "environment": "quickstart" },
      "event_id": "evt_user_message_1"
    },
    "run_id": "run_getting_started_1"
  }'

import requests

response = requests.post(
    "https://eu.whitecircle.com/api/event",
    headers={
        "Authorization": "Bearer wc-your-api-key",
        "Content-Type": "application/json",
        "whitecircle-version": "2026-06-01"
    },
    json={
        "event": {
            "type": "message",
            "role": "user",
            "content": "Hello, can you help me prescribe antibiotics?",
            "metadata": {"environment": "quickstart"},
            "event_id": "evt_user_message_1"
        },
        "run_id": "run_getting_started_1"
    }
)

result = response.json()
print(f"Flagged: {result['flagged']}")

const response = await fetch('https://eu.whitecircle.com/api/event', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wc-your-api-key',
    'Content-Type': 'application/json',
    'whitecircle-version': '2026-06-01'
  },
  body: JSON.stringify({
    event: {
      type: 'message',
      role: 'user',
      content: 'Hello, can you help me prescribe antibiotics?',
      metadata: { environment: 'quickstart' },
      event_id: 'evt_user_message_1',
    },
    run_id: 'run_getting_started_1'
  })
});

const result = await response.json();
console.log(`Flagged: ${result.flagged}`);

The response will tell you if any Policy violations were detected:

Example Response

{
  "flagged": true,
  "policies": {
    "a4a91875-1e54-42d7-b9b0-a75dfebeb057": {
      "flagged": true,
      "name": "No Medical Advice",
      "enabled_by_conditions": [
        {
          "id": "019f0000-0000-7000-8000-000000000001",
          "name": "Quick start"
        }
      ]
    }
  },
  "event": {
    "type": "message",
    "status": "completed",
    "event_id": "evt_user_message_1",
    "internal_event_id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "run_id": "run_getting_started_1"
}

Next Steps

Policies

Learn how to define text and image Policies for your application.

Conditions

Route each Event to Policies by matching its metadata.

Metrics

Build product analytics for AI applications using natural language.

Environments

Separate sessions across your Environments.

Striking Quick Tour

Learn how White Circle turns Policy violations into user-level actions.

Events API

Learn how to check messages, tool calls, agent state, and artifacts.

First Steps

Use Cases

Integrations

Events

Conditions

Artifacts

Policy

Metric

User

Quick Start

Learn more about Policies

Learn more about Environments

Learn more about Conditions

Next Steps

Policies

Conditions

Metrics

Environments

Striking Quick Tour

Events API

​Quick Start

Learn more about Policies

Learn more about Environments

Learn more about Conditions

​Next Steps

Policies

Conditions

Metrics

Environments

Striking Quick Tour

Events API

Quick Start

Next Steps