> ## 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.
# Check One Event
Check a single Event against the Policies and Metrics selected by active Conditions in your Environment. Use this endpoint for one message, tool output, function call, agent update, reasoning, or inline image artifact.
## How It Works
1. You submit one Event with a `type`, one content field, and optional `metadata`
2. Conditions match the Event's metadata and select Policies and Metrics.
3. Event selectors filter them to the submitted type and field
4. You receive synchronous Policy results, and selected Metrics continue asynchronously.
If you omit all content fields, the request becomes a reference-only Event. White Circle looks up the latest matching result by `run_id` and `event_id`.
## Example Request
```bash theme={null}
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 '{
"environment_id": "environment_123",
"run_id": "run_refund_123",
"external_session_id": "conversation_456",
"event": {
"type": "message",
"role": "user",
"content": "I need help with a refund. My account number is 123-45-6789.",
"metadata": {
"user": {
"region": "eu"
}
},
"event_id": "evt_user_001"
}
}'
```
## Request Overview
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment_id` | string | ✓ | Environment to use. Required for every request. |
| `run_id` | string | | Your ID for a group of related Events. Reusing it supplies [context](/latest/events/context) when no `external_session_id` is sent. Generated if omitted for Events with content. |
| `external_session_id` | string | | Your conversation or session tracking ID. Reusing it checks this Event against the previous Events of that conversation. See [Event Context](/latest/events/context). |
| `role` | string | | Role applied to `message` and `artifact` Events that do not set their own. |
| `event` | object | ✓ | Event payload to check or reference. |
## Event Payload
| Field | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `type` | string | ✓ | Event type: `message`, `artifact`, `tool`, `function`, `agent`, or `reasoning`. |
| `event_id` | string | | Your ID for this Event. Generated if omitted for Events with content. Required for references. |
| `run_id` | string | | Event-specific group ID. If omitted, the top-level `run_id` is used. |
| `parent_event_id` | string | | Optional same-run structural parent Event ID. |
| `links` | array | | Causal input references as `{event_id, run_id?}`. Omit `run_id` for same-run links. |
| `external_session_id` | string | | Event-specific session tracking ID. Overrides the top-level value for this Event's context. |
| `role` | string | | Role for this Event. Required for `message` Events with content when no top-level `role` is set. |
| `timestamp` | string | | Optional ISO 8601 timestamp from your system. |
| `name` | string | | Optional tool, function, agent, or Artifact name. |
| `call_id` | string | | Optional tool or function call ID. |
| `format` | string | | Optional format label from your system. |
| `external_artifact_id` | string | | Optional Artifact tracking ID for Artifact Events. |
| `metadata` | object | | Custom metadata, up to 256 KiB serialized. |
## Content Fields
Provide exactly one content field per Event.
| Event type | Allowed fields |
| ----------- | ------------------------------------------ |
| `message` | `content` |
| `artifact` | `content` |
| `tool` | `arguments`, `output`, `definition` |
| `function` | `arguments`, `output`, `definition` |
| `agent` | `input`, `instructions`, `output`, `state` |
| `reasoning` | `content` |
`tool.arguments` and `function.arguments` accept any JSON value, including a string, number, boolean, `null`, array, or nested object. White Circle preserves the JSON shape for moderation.
For an `artifact` image with raw base64 `data`, `mime_type` is optional for JPEG, PNG, WebP, and GIF content. White Circle detects the image type from the decoded bytes.
An Event can include at most one content field for evaluation. To evaluate multiple fields, submit multiple Events.
## Response Overview
| Field | Type | Description |
| ---------- | ------- | ---------------------------------------------------------------------------- |
| `flagged` | boolean | `true` if the Event violated at least one Policy. Omitted when no check ran. |
| `policies` | object | Map of Policy IDs to Policy results. Omitted when no check ran. |
| `note` | string | Explanation of an outcome that produced no verdict. |
| `event` | object | The Event that was checked. |
| `run_id` | string | Run ID used for the Event. |
The verdict is reported once, at the top level. The `event` object carries identity and status only.
The `event` object includes:
| Field | Description |
| ------------------- | ------------------------------------------------------- |
| `type` | Event type. |
| `status` | `completed`, `failed`, `referenced`, or `not_found`. |
| `event_id` | Your ID for this Event. |
| `internal_event_id` | White Circle's ID for one saved result, when available. |
`flagged` and `policies` are present only when `status` is `completed`. For any other status no check ran, so the response states no verdict rather than reporting `false`.
`note` explains why:
| Situation | Note |
| ------------------------------------------ | ----------------------------------------------------- |
| No Condition selected any Policy or Metric | `No policies or metrics were selected for this Event` |
| A reference did not resolve | `Referenced event was not found or is not accessible` |
| The Event failed validation or checking | The failure reason |
Each Policy object includes:
* `flagged` — Whether this Policy was violated
* `name` — Human-readable Policy name
* `enabled_by_conditions` — The Conditions that selected this Policy for this Event, which is why it was evaluated. Absent when no Condition was involved.
## Conditions and Metadata
White Circle evaluates active Conditions against the `metadata` object on this Event. Matching Conditions select the applicable Policies and Metrics. Event selectors then filter them to this Event's type, field, and direction.
If no active Condition matches, the Event completes without evaluating any Policies and queues no Metrics. Conditions do not fall back to every Policy or Metric in the Environment.
Selected Metrics run asynchronously and are not returned in the synchronous `policies` map. View Metric results in the dashboard after processing completes.
See [Conditions](/latest/condition/overview) for expression syntax and Policy or Metric attachments.
## Parents and Links
Use one `parent_event_id` for the Event's structural place in the run. Use `links` when an Event consumes multiple outputs or depends on Events from other runs:
```json theme={null}
{
"event": {
"type": "message",
"role": "assistant",
"content": "Combined result",
"links": [
{ "run_id": "run_security", "event_id": "security_output" },
{ "run_id": "run_tests", "event_id": "test_output" }
],
"event_id": "final_answer",
"parent_event_id": "main_agent"
},
"environment_id": "environment_123",
"run_id": "run_main"
}
```
Parents and links are used for auditing and navigation in this API version. White Circle does not automatically add target content to moderation context.
Reference-only Events cannot declare `parent_event_id` or `links` because references are read-only lookups.
White Circle returns `400` for self-parenting, direct mutual parents such as `A → B → A`, and parent cycles contained in one batch. It does not recursively traverse all prior cross-request ancestors on the write path.
## Event Identity and Retries
`run_id` and `event_id` help you connect Events to your own application data. They are not retry keys. If you submit the same `run_id` and `event_id` again, White Circle may run another check. The latest durable attempt (completed or failed) defines the current graph relationships. Each retry replaces the complete parent/link declaration set; omitted relationships are cleared from the current graph.
Use `internal_event_id` to refer to one saved result.
## Reference an Existing Event
To reference an existing Event, send the type and `event_id` without a content field:
```json theme={null}
{
"event": {
"type": "agent",
"event_id": "evt_agent_state_001"
},
"environment_id": "environment_123",
"run_id": "run_refund_123"
}
```
White Circle returns `referenced` when the latest matching result has the same Event type. Otherwise, it returns `not_found`.
## Tool Output Example
```json theme={null}
{
"event": {
"type": "tool",
"name": "send_refund_email",
"output": {
"subject": "Refund approved",
"body": "Your refund has been approved."
},
"event_id": "evt_tool_output_1",
"call_id": "call_abc"
},
"environment_id": "environment_123",
"run_id": "run_tool_123"
}
```
## OpenAPI
````yaml POST /api/event
openapi: 3.1.0
info:
title: WhiteCircle API Backend
description: 'Authentication: Bearer API Key Required'
license:
name: ''
version: '2026-06-01'
servers:
- url: https://eu.whitecircle.com
- url: https://us.whitecircle.com
security: []
tags:
- name: Session
description: Session-based content checking and moderation
- name: User
description: User risk assessment and scoring
- name: Policy
description: Policy management CRUD
- name: Metric
description: Metric management CRUD
- name: Artifact
description: Standalone artifact moderation
- name: Events
description: Append-only event ingestion and public event lookup
- name: Condition
description: Metadata-driven policy routing
paths:
/api/event:
post:
tags:
- Events
operationId: event_check_v1
parameters:
- name: whitecircle-version
in: header
description: API Version
required: true
schema:
type: string
example: '2026-06-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventRequestEnvelope'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventResponseEnvelope'
'400':
description: Bad Request
security:
- bearerAuth: []
components:
schemas:
EventRequestEnvelope:
type: object
required:
- environment_id
- event
properties:
environment_id:
type: string
run_id:
type:
- string
- 'null'
external_session_id:
type:
- string
- 'null'
role:
type:
- string
- 'null'
event:
$ref: '#/components/schemas/EventPayload'
EventResponseEnvelope:
type: object
required:
- event
- run_id
properties:
flagged:
type:
- boolean
- 'null'
description: >-
Absent when no check ran, such as a reference, a failure, or an
Event
no Condition selected policies for.
policies:
type:
- object
- 'null'
additionalProperties:
$ref: '#/components/schemas/EventPolicyResult'
propertyNames:
type: string
note:
type:
- string
- 'null'
event:
$ref: '#/components/schemas/CheckedEvent'
run_id:
type: string
example:
flagged: true
policies:
70289e06-9111-463e-b121-7247c2b7bfbd:
flagged: true
name: No PII Sharing
enabled_by_conditions:
- id: 019f0000-0000-7000-8000-000000000001
name: EU users
event:
event_id: evt_user_001
internal_event_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890
status: completed
type: message
run_id: run_refund_123
EventPayload:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/EventType'
role:
type:
- string
- 'null'
content: {}
delta: {}
arguments: {}
output: {}
definition: {}
input: {}
instructions: {}
state: {}
event_id:
type:
- string
- 'null'
run_id:
type:
- string
- 'null'
external_session_id:
type:
- string
- 'null'
parent_event_id:
type:
- string
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/EventLink'
external_artifact_id:
type:
- string
- 'null'
name:
type:
- string
- 'null'
call_id:
type:
- string
- 'null'
stream_id:
type:
- string
- 'null'
sequence:
type:
- integer
- 'null'
format: int64
format:
type:
- string
- 'null'
timestamp:
type:
- string
- 'null'
format: date-time
metadata: {}
EventPolicyResult:
type: object
required:
- flagged
- name
properties:
flagged:
type: boolean
name:
type: string
enabled_by_conditions:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/EnabledByCondition'
description: >-
The Conditions that selected this Policy for this Event, which is
why it
was evaluated at all.
CheckedEvent:
type: object
description: |-
The Event a single check was run against. Identity and status only; the
verdict lives on the response so it is stated exactly once.
required:
- type
- status
- event_id
properties:
type:
$ref: '#/components/schemas/EventType'
status:
$ref: '#/components/schemas/EventResultStatus'
event_id:
type: string
internal_event_id:
type:
- string
- 'null'
EventType:
type: string
enum:
- message
- artifact
- tool
- function
- agent
- reasoning
EventLink:
type: object
required:
- event_id
properties:
run_id:
type:
- string
- 'null'
event_id:
type: string
EnabledByCondition:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
EventResultStatus:
type: string
enum:
- completed
- failed
- referenced
- not_found
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'API Key required. Format: Bearer wc-your-api-key'
````