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.
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.contentortool.output - Evaluates Policies synchronously and queues Metrics asynchronously
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
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
{
"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
{
"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
{
"type": "condition",
"field": "user.age",
"operator": "gte",
"value": 18
}Use dot-separated fields such as user.region to read nested Event metadata.
Group
JSON
{
"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.
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 a Condition and attach Environments, Policies, and Metrics.
Create a new revision with selected fields changed.
Send metadata that Conditions evaluate per Event.
Configure which Event types and fields each Policy evaluates.