# Check One Event

`POST /api/event`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [latest/openapi.json](https://whitecircle.com/docs/latest/openapi.json)

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.

> [!NOTE]
> 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`.

## Content Fields

Provide exactly one content field per Event.

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

> [!WARNING]
> An Event can include at most one content field for evaluation. To evaluate multiple fields, submit multiple Events.

## Response Overview

> [!NOTE]
> The verdict is reported once, at the top level. The `event` object carries identity and status only.

`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.
* `shadow` — Present and `true` only for shadow-mode Policies returned via `include_shadow`. A shadow result never affects the top-level `flagged` verdict. Absent for production Policies.

> [!NOTE]
> Shadow-mode Policies are evaluated but omitted from the response by default so they cannot affect production traffic. Set `include_shadow` to inspect them — for example, to test a prompt set against your current configuration before promoting a Policy out of shadow mode.

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

> [!WARNING]
> 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](https://whitecircle.com/docs/latest/condition/overview.md) for expression syntax and Policy or Metric attachments.

## Parents and Links

`parent_event_id` and `links` record how Events relate inside your agent: which step produced an Event, and which outputs it used. White Circle stores them as a run graph that you can load with [Get a Run Graph](https://whitecircle.com/docs/latest/events/get-run-graph.md) and browse in the dashboard. For a full walkthrough with sub-agents, see [Runs and the Event Graph](https://whitecircle.com/docs/latest/first-steps/runs-and-event-graph.md).

| Field | Use for | Can point to |
| ----- | ------- | ------------ |
| `parent_event_id` | The one Event that produced this Event, such as the agent step that made a tool call | An `event_id` in the same run |
| `links` | Outputs this Event consumed, such as sub-agent results merged into a final answer | Any run in the same Environment, up to 50 per Event |

In this example, the main agent merges the results of two sub-agent runs into its final answer:

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

The parent and link targets do not have to exist yet. The run graph keeps the reference and resolves it when the target Event arrives.

### Where Parents and Links Appear

* **Run graph API.** [Get a Run Graph](https://whitecircle.com/docs/latest/events/get-run-graph.md) returns a `parent` edge for each `parent_event_id` and a `link` edge for each entry in `links`.
* **Dashboard.** The Runs page draws parent edges as the run tree and breadcrumbs, and shows links as causal inputs, including inputs from other runs.

### Tool Call Pairing

When a `tool` or `function` Event sends `output` without a `call_id`, White Circle pairs it with the call whose `event_id` matches the output's `parent_event_id`. The model then sees the arguments and the output as one call.

```json
[
  { "type": "tool", "name": "lookup_order", "event_id": "lookup_args", "arguments": { "order_id": "4815" } },
  { "type": "tool", "name": "lookup_order", "event_id": "lookup_result", "parent_event_id": "lookup_args", "output": { "refund_eligible": true } }
]
```

Sending the same `call_id` on both Events pairs them the same way.

### Sub-agents

Send a sub-agent's Events in the same run as the agent that started it, and set the `parent_event_id` of the sub-agent's first Event to the step that started it. Each sub-agent then becomes its own branch of the run tree. Use `links` when an Event consumes another branch's output, or an Event from another run. A parent must be in the same run, so connections between runs always use `links`.

### Validation

Reference-only Events cannot declare `parent_event_id` or `links`, because references are read-only lookups.

White Circle returns `400` for self-parenting, self-links, duplicate links, direct mutual parents such as `A → B → A`, and parent cycles inside one batch. It does not check for longer cycles across earlier requests.

White Circle also returns `400` when `finished_at` is earlier than `started_at`. See [Execution Timing](https://whitecircle.com/docs/latest/events/overview.md#execution-timing).

## 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. White Circle returns `referenced` when the latest matching result has the same Event type. Otherwise, it returns `not_found`.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-06-01"`.

## Body

`application/json`

- `environment_id` (`string`, required): Environment whose Conditions, Policies, and Metrics apply. Required on every request.
- `event` (`object`, required): The Event to check or reference.
- `event.type` (`enum<string>`, required): Kind of Event. Determines which content fields are allowed and which Policies can apply. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `event.role` (`string | null`, optional): Who produced the content: `user`, `assistant`, `system`, `developer`, or `tool`. Required for `message` Events with content unless the request sets a top-level `role`. Overrides the Policy direction of other Event types; when omitted, White Circle picks it from the type and field, for example `tool.output` as `assistant`.
- `event.content` (`any`, optional): Content to check for `message`, `artifact`, and `reasoning` Events. Messages and reasoning take text; artifacts take an image object.
- `event.delta` (`any`, optional): An incremental chunk of a streamed `message` or `reasoning` Event. Each delta is checked as its own Event; White Circle does not join deltas, so send chunks large enough to judge, such as every N tokens or sentences.
- `event.arguments` (`any`, optional): Arguments of a `tool` or `function` call. Accepts any JSON value; White Circle keeps its shape.
- `event.output` (`any`, optional): Result of a `tool`, `function`, or `agent`. Accepts any JSON value.
- `event.definition` (`any`, optional): Schema or description of a `tool` or `function`, such as an OpenAI tool definition. Accepts any JSON value.
- `event.input` (`any`, optional): Task or input given to an `agent`, checked as user-direction content.
- `event.instructions` (`any`, optional): System instructions given to an `agent`. Enters context with the `system` role.
- `event.state` (`any`, optional): Snapshot of an `agent`'s internal state.
- `event.event_id` (`string | null`, optional): Your ID for this Event. Required for reference-only Events. Generated when omitted for Events with content. Not a retry key: sending the same `run_id` and `event_id` again runs a new check. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `event.run_id` (`string | null`, optional): Run for this Event. Overrides the top-level `run_id`. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `event.external_session_id` (`string | null`, optional): Session for this Event. Overrides the top-level `external_session_id`. Up to 256 characters.
- `event.parent_event_id` (`string | null`, optional): `event_id` of this Event's structural parent in the same run, such as the agent step that produced it. Appears as a `parent` edge in the run graph and pairs a tool or function `output` with the call that has this `event_id` when you send no `call_id`. Not allowed on reference-only Events. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `event.links` (`object[]`, optional): Causal inputs this Event consumed, in this run or in other runs of the same Environment. Each appears as a `link` edge in the run graph. Up to 50 per Event. Not allowed on reference-only Events.
- `event.links.event_id` (`string`, required): `event_id` of the linked Event. The target does not have to exist yet.
- `event.links.run_id` (`string | null`, optional): Run of the linked Event. Omit for an Event in the same run. Links can point to any run in the same Environment.
- `event.external_artifact_id` (`string | null`, optional): Your ID for the image in an `artifact` Event. Used as the `event_id` when you omit `event_id`. Up to 256 characters.
- `event.name` (`string | null`, optional): Name of the tool, function, agent, or artifact, such as `lookup_order`. Up to 256 characters.
- `event.call_id` (`string | null`, optional): Your ID for one tool or function invocation. Send the same `call_id` on the `arguments` and `output` Events so the model sees them as one call. Up to 256 characters.
- `event.stream_id` (`string | null`, optional): Your ID for the stream a `delta` belongs to. Stored and returned in the run graph; does not change how deltas are checked. Up to 256 characters.
- `event.sequence` (`integer<int64> | null`, optional): Position of this chunk in its stream. Stored and returned in the run graph.
- `event.format` (`string | null`, optional): Free-form label for the content format, such as `markdown`. Stored only. Up to 256 characters.
- `event.started_at` (`string<date-time> | null`, optional): When the work behind this Event started in your system, as RFC 3339. Shown on the Event with `finished_at` as its duration. Display only: it does not change Event ordering or `created_at`.
- `event.finished_at` (`string<date-time> | null`, optional): When the work behind this Event finished in your system, as RFC 3339. Must not be earlier than `started_at`. Display only: it does not change Event ordering or `created_at`.
- `event.metadata` (`any`, optional): Custom JSON object, up to 256 KiB. Conditions match against it to select Policies and Metrics for this Event.
- `run_id` (`string | null`, optional): Your ID for a group of related Events, such as one agent run. Defaults to `external_session_id` when omitted. `parent_event_id` and same-run `links` resolve inside this run. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `external_session_id` (`string | null`, optional): Your conversation or session ID. Reuse it for every Event in the same conversation. See [Event Context](https://whitecircle.com/docs/latest/events/context.md). Up to 256 characters.
- `role` (`string | null`, optional): Default role for `message` and `artifact` Events that do not set their own `role`. Other Event types ignore it.
- `include_shadow` (`boolean | null`, optional): Also return shadow-policy results (each marked `shadow: true`). Shadow results never affect the top-level `flagged`/`violation` verdict.

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/event' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2026-06-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "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 order number is 4815.",
    "event_id": "evt_user_001"
  }
}'
```

## Response

### 200

Success

`application/json`

- `event` (`object`, required): Identity and status of the Event that was submitted.
- `event.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `event.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `event.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `event.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `run_id` (`string`, required): Run the Event was recorded in.
- `flagged` (`boolean | null`, optional): Absent when no check ran, such as a reference, a failure, or an Event no Condition selected policies for.
- `policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `policies.{key}` (`object`, optional)
- `policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `policies.{key}.name` (`string`, required): Human-readable Policy name.
- `policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `policies.{key}.enabled_by_conditions.id` (`string`, required)
- `policies.{key}.enabled_by_conditions.name` (`string`, required)
- `policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.

**Example**

```json
{
  "flagged": false,
  "policies": {
    "01930000-0000-7000-8000-000000000001": {
      "flagged": false,
      "name": "PII disclosure",
      "enabled_by_conditions": [
        {
          "id": "01930000-0000-7000-8000-000000000002",
          "name": "EU users"
        }
      ]
    }
  },
  "event": {
    "type": "message",
    "status": "completed",
    "event_id": "evt_user_001",
    "internal_event_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890"
  },
  "run_id": "run_refund_123"
}
```

### 400

Bad Request
