Conditions

Conditions determine which Policies and Metrics evaluate each Event by matching its metadata. Use them when different users, regions, products, models, or workflow stages require different Policies and Metrics.

Conditions and Events are available in API version 2026-06-01. Send the whitecircle-version: 2026-06-01 header on every request.

How Conditions Work

For every Event with content, White Circle:

Finds the active Conditions attached to the Event’s Environment
Evaluates each Condition against the Event’s metadata
Selects the Policies and Metrics attached to matching Conditions
Applies each Policy or Metric’s Event selector, such as message.content or tool.output
Evaluates Policies synchronously and queues Metrics asynchronously

If no active Condition matches an Event, no Policies or Metrics are evaluated for that Event.

Results for active Policies appear synchronously in the Event response’s Policies map. Metrics run asynchronously and appear in dashboard analytics after processing.

Use an empty object {} when a Condition should match every Event in its attached Environments. Conditions are evaluated independently for each Event, including Events in the same batch. Reference-only Events do not evaluate Conditions because they do not run a new check.

Example

Create a Condition that enables selected Policies for EU users:

curl -X POST "https://eu.whitecircle.com/api/condition/create" \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "Content-Type: application/json" \
  -H "whitecircle-version: 2026-06-01" \
  -d '{
    "name": "EU users",
    "description": "Apply EU-specific Policies",
    "conditions": {
      "type": "group",
      "conditions": [
        {
          "type": "condition",
          "field": "user.region",
          "operator": "eq",
          "value": "eu"
        }
      ]
    },
    "environment_ids": ["your-environment-id"],
    "policy_ids": ["policy_pii"],
    "metric_ids": ["metric_quality"],
    "state": "Active"
  }'

Then include matching metadata on an Event:

{
  "event": {
    "type": "message",
    "role": "user",
    "content": "My account number is 123-45-6789.",
    "metadata": {
      "user": {
        "region": "eu"
      }
    },
    "event_id": "evt_user_001",
    "run_id": "run_refund_123",
    "environment_id": "your-environment-id"
  }
}

A selected Policy result identifies the matching Conditions:

{
  "flagged": true,
  "name": "No PII Sharing",
  "enabled_by_conditions": [
    {
      "id": "019f0000-0000-7000-8000-000000000001",
      "name": "EU users"
    }
  ]
}

Condition Expressions

A Condition is a group of leaf conditions. Every leaf must match for the Condition to select its Policies and Metrics.

Leaf

{
  "type": "condition",
  "field": "user.age",
  "operator": "gte",
  "value": 18
}

Use dot-separated fields such as user.region to read nested Event metadata.

Operator	Meaning
`eq`, `neq`	Equal or not equal
`gt`, `gte`, `lt`, `lte`	Numeric comparison
`in`, `not_in`	Membership in an array supplied as `value`
`contains`	String substring, array item, or object-key match
`starts_with`, `ends_with`	String prefix or suffix
`exists`, `not_exists`	Field is present or absent; `value` is not required
`regex`	Rust-compatible regular expression match

Group

{
  "type": "group",
  "conditions": [
    {
      "type": "condition",
      "field": "user.region",
      "operator": "eq",
      "value": "eu"
    },
    {
      "type": "condition",
      "field": "user.age",
      "operator": "gte",
      "value": 18
    }
  ]
}

A group holds leaf conditions and combines them with and. This Condition selects its Policies only for EU users aged 18 or over.

Conditions you create through the API in this shape stay editable in the White Circle dashboard.

Malformed expressions, unknown operators, missing fields, and invalid regular expressions do not match.

Revisions and Attachments

Every create or update operation produces an immutable Condition revision. The current revision defines the Condition’s expression, state, attached Environments, and attached Policies and Metrics. Attach Policies with policy_ids and Metrics with metric_ids. Omitting policy_ids, metric_ids, or environment_ids during an update preserves their current values; providing an empty array clears that attachment type.

Create Condition

Create a Condition and attach Environments, Policies, and Metrics.

Update Condition

Create a new revision with selected fields changed.

Check an Event

Send metadata that Conditions evaluate per Event.

Event Selectors

Configure which Event types and fields each Policy evaluates.

First Steps

Use Cases

Integrations

Events

Artifacts

Policy

Metric

User

Conditions

How Conditions Work

Example

Condition Expressions

Leaf

Group

Revisions and Attachments

Create Condition

Update Condition

Check an Event

Event Selectors

​How Conditions Work

​Example

​Condition Expressions

​Leaf

​Group

​Revisions and Attachments

Create Condition

Update Condition

Check an Event

Event Selectors

How Conditions Work

Example

Condition Expressions

Leaf

Group

Revisions and Attachments