Events

Check One Event

POST
/api/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.

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.

Response Overview

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:

SituationNote
No Condition selected any Policy or MetricNo policies or metrics were selected for this Event
A reference did not resolveReferenced event was not found or is not accessible
The Event failed validation or checkingThe 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.

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.

Selected Metrics run asynchronously and are not returned in the synchronous policies map. View Metric results in the dashboard after processing completes.

See Conditions for expression syntax and Policy or Metric attachments.

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 and browse in the dashboard. For a full walkthrough with sub-agents, see Runs and the Event Graph.

FieldUse forCan point to
parent_event_idThe one Event that produced this Event, such as the agent step that made a tool callAn event_id in the same run
linksOutputs this Event consumed, such as sub-agent results merged into a final answerAny 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.

  • Run graph API. Get a Run Graph 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.

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

  • Authorizationstringheaderrequired

    API Key required. Format: Bearer wc-your-api-key

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-06-01"

Body

application/json

  • environment_idstringrequired

    Environment whose Conditions, Policies, and Metrics apply. Required on every request.

  • eventobjectrequired

    The Event to check or reference.

    Show child attributes
    • event.typeenum<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.rolestring | null

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

      Content to check for message, artifact, and reasoning Events. Messages and reasoning take text; artifacts take an image object.

    • event.deltaany

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

      Arguments of a tool or function call. Accepts any JSON value; White Circle keeps its shape.

    • event.outputany

      Result of a tool, function, or agent. Accepts any JSON value.

    • event.definitionany

      Schema or description of a tool or function, such as an OpenAI tool definition. Accepts any JSON value.

    • event.inputany

      Task or input given to an agent, checked as user-direction content.

    • event.instructionsany

      System instructions given to an agent. Enters context with the system role.

    • event.stateany

      Snapshot of an agent's internal state.

    • event.event_idstring | null

      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_idstring | null

      Run for this Event. Overrides the top-level run_id. Up to 128 characters: letters, numbers, ., _, :, and -.

    • event.external_session_idstring | null

      Session for this Event. Overrides the top-level external_session_id. Up to 256 characters.

    • event.parent_event_idstring | null

      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.external_artifact_idstring | null

      Your ID for the image in an artifact Event. Used as the event_id when you omit event_id. Up to 256 characters.

    • event.namestring | null

      Name of the tool, function, agent, or artifact, such as lookup_order. Up to 256 characters.

    • event.call_idstring | null

      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_idstring | null

      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.sequenceinteger<int64> | null

      Position of this chunk in its stream. Stored and returned in the run graph.

    • event.formatstring | null

      Free-form label for the content format, such as markdown. Stored only. Up to 256 characters.

    • event.started_atstring<date-time> | null

      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_atstring<date-time> | null

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

      Custom JSON object, up to 256 KiB. Conditions match against it to select Policies and Metrics for this Event.

  • run_idstring | null

    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_idstring | null

    Your conversation or session ID. Reuse it for every Event in the same conversation. See Event Context. Up to 256 characters.

  • rolestring | null

    Default role for message and artifact Events that do not set their own role. Other Event types ignore it.

  • include_shadowboolean | null

    Also return shadow-policy results (each marked shadow: true). Shadow results never affect the top-level flagged/violation verdict.

Response

application/json

Success

  • eventobjectrequired

    Identity and status of the Event that was submitted.

    Show child attributes
    • event.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • event.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • event.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • event.internal_event_idstring | null

      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_idstringrequired

    Run the Event was recorded in.

  • flaggedboolean | null

    Absent when no check ran, such as a reference, a failure, or an Event no Condition selected policies for.

  • policiesobject | null

    Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

    Show child attributes
    • policies.{key}object

      Show child attributes
      • policies.{key}.flaggedbooleanrequired

        Whether this Event violated the Policy.

      • policies.{key}.namestringrequired

        Human-readable Policy name.

      • policies.{key}.enabled_by_conditionsobject[] | null

        The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

        Show child attributes
        • policies.{key}.enabled_by_conditions.idstringrequired

        • policies.{key}.enabled_by_conditions.namestringrequired

      • policies.{key}.shadowboolean

        Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

  • notestring | null

    Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.