> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conditions

> Select Policies and Metrics for each Event by matching its metadata

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.

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

## How Conditions Work

For every Event with content, White Circle:

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

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

<Info>Results for active Policies appear synchronously in the Event response's <code>Policies</code> map. Metrics run asynchronously and appear in dashboard analytics after processing.</Info>

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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

<Info>Conditions you create through the API in this shape stay editable in the White Circle dashboard.</Info>

<Warning>Malformed expressions, unknown operators, missing fields, and invalid regular expressions do not match.</Warning>

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

<CardGroup cols={2}>
  <Card title="Create Condition" icon="plus" href="/latest/condition/create-condition">
    Create a Condition and attach Environments, Policies, and Metrics.
  </Card>

  <Card title="Update Condition" icon="pen" href="/latest/condition/update-condition">
    Create a new revision with selected fields changed.
  </Card>

  <Card title="Check an Event" icon="bolt" href="/latest/events/check-event">
    Send metadata that Conditions evaluate per Event.
  </Card>

  <Card title="Event Selectors" icon="filter" href="/latest/first-steps/policies">
    Configure which Event types and fields each Policy evaluates.
  </Card>
</CardGroup>