Get Started
Ingestion API

Capture Event

Record one turn-pair or tool call within a session

POSThttps://api.voxmith.com/api/v1/capture-event

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.
  • For tool calls, set parent_id when the tool was triggered by another agent/tool event.

Next steps

Headers

x-org-idstringrequired
Your organization ID (UUID, case-insensitive).

Request body

event_idstring · uuidrequired
Client-generated UUID. Use as parent_id on child events.
session_idstring · uuidrequired
Session UUID from capture-session.
primitive_namestringrequired
Agent name (turn-pair) or tool name (tool call).
argsstringrequired
Input — user message or JSON-encoded tool args.
resultstringrequired
Output — assistant reply or JSON-encoded tool result.
successboolean
Defaults to true.
latencyinteger
Execution time in ms.
timestampinteger · int64
Unix time in ms when the event occurred. Defaults to server time.
parent_idstring · uuid
Parent event UUID. Set on tool calls to point at the agent turn (or parent tool) that triggered them.
metadataobject
Free-form event metadata.

Responses

200Event recorded
400Invalid request body