# Capture Event

> Record one turn-pair or tool call within a session

Generate `event_id` client-side (UUID) so child events can reference their parent before the parent's response returns.

## Body

| Field | Type | Required | Description |
| - | - | - | - |
| `event_id` | `string` (UUID) | Required | Client-generated UUID. Use as `parent_id` on child events. |
| `session_id` | `string` (UUID) | Required | Session UUID from `capture-session`. |
| `primitive_name` | `string` | Required | Agent name (turn-pair) or tool name (tool call). |
| `args` | `string` | Required | Input: user message or JSON-encoded tool args. |
| `result` | `string` | Required | Output: assistant reply or JSON-encoded tool result. |
| `success` | `boolean` | Optional | Defaults to `true`. |
| `latency` | `integer` (ms) | Optional | Execution time in milliseconds. |
| `timestamp` | `integer` (ms) | Optional | Unix time in ms when the event occurred. Defaults to server time. |
| `parent_id` | `string` (UUID) | Optional | Parent event UUID. Set on tool calls to point at the agent turn (or parent tool) that triggered them. |
| `metadata` | `object` | Optional | Free-form event metadata. |

## Core rules

* **One session per conversation**: reuse `session_id` on every event.
* **One event per turn-pair**: `primitive_name` is the agent name, `args` is the user input, `result` is the assistant output. Don't emit separate output events.
* **Merge assistant turns**: if one user turn is followed by N assistant turns (with tool calls between), concatenate the N texts into a single `result`.
* **Tool calls = own event**: `primitive_name` is the tool name, `args`/`result` are plain text or JSON-encoded strings.
* **Sub-tools chain**: when a tool invokes another tool, set `parent_id` to the parent **tool's** `event_id`.

## Verify

Send one event, then open **Events** in Voxmith. Confirm `primitive_name`, `args`, `result`, `success`, and `latency` look right.

## Troubleshooting

* `event_id` and `session_id` must be UUIDs.
* Create the session first with [Capture Session](/capture-session).
* For tool calls, set `parent_id` when the tool was triggered by another agent/tool event.

## Next steps

* [Events](/using-events): inspect accepted events in Voxmith.
* [Capture a session](/capture-session): review the required conversation boundary.
* [Ingestion errors](/errors): troubleshoot rejected requests.