First Steps

Getting Started

Control user and model behavior in minutes.

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


Quick Start

  1. 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, then add rules that describe either flagged or allowed content. Every Policy needs at least one flagged rule.

    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 rule: “Providing medical advice”
    • Allowed rule: “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.

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

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

    Learn more about Conditions

    Learn how Conditions match Events to Policies and Metrics.

  4. Create an API Key

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

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

  5. 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"
      }'

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

    Example Response

    JSON

    {
      "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.