POST /capture-event

Records a single event within a conversation. An event is either a turn-pair (the user’s message and the agent’s reply) or a tool call. Send one capture-event per turn and one per tool call.

POST https://api.hone.dev/api/v1/capture-event

Headers

Header	Value	Required
`x-api-key`	Your API key, `sk_...`	Yes
`Content-Type`	`application/json`	Yes

Body

Field	Type	Required	Description
`event_id`	UUID	Yes	Client-generated so child events can reference it as their parent.
`session_id`	UUID	Yes	The session this event belongs to, from `capture-session`.
`primitive_name`	string	Yes	The agent name for a turn-pair, or the tool name for a tool call.
`primitive_type`	string	No	The kind of primitive, for example `tool`, `resource`, or `prompt`.
`args`	string	Yes	The input: the user’s message, or the tool’s arguments as JSON.
`result`	string	Yes	The output: the agent’s reply, or the tool’s result as JSON.
`success`	boolean	No	Whether the event succeeded. Defaults to `true`.
`latency`	integer (ms)	No	How long the operation took, in milliseconds.
`timestamp`	integer (ms)	No	Epoch milliseconds for the event. Defaults to server time.
`parent_id`	UUID	No	For a tool call, the `event_id` of the turn or tool that triggered it.
`metadata`	object	No	Free-form metadata. `checkpoint.*` keys drive per-tool execution timelines in Pulse.

The event tree

Events form a tree so the trace of a conversation is preserved:

A turn-pair is a top-level event: primitive_name is your agent’s name, args is the user’s message, and result is the reply. It has no parent_id.
A tool call sets parent_id to the event_id of the turn that triggered it. Sub-tools chain further by pointing at the parent tool’s event_id.

This parent and child structure is what powers the trace view and the tool timelines in the dashboard.

Checkpoints

Ride named checkpoints in metadata under checkpoint.* keys to record milestones inside a single tool call. Hone reads them to draw a per-tool execution timeline in Pulse.

Request

curl https://api.hone.dev/api/v1/capture-event \
  -H "x-api-key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b",
    "session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
    "primitive_name": "support-bot",
    "primitive_type": "prompt",
    "args": "How do I reset my password?",
    "result": "Head to Settings, then Security, and choose Reset password.",
    "success": true,
    "latency": 812,
    "metadata": {
      "model": "claude-sonnet-4"
    }
  }'

A tool call under a turn

curl https://api.hone.dev/api/v1/capture-event \
  -H "x-api-key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "d9e0c1a2-7b34-4f56-8a9b-0c1d2e3f4a5b",
    "session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
    "primitive_name": "knowledge_search",
    "primitive_type": "tool",
    "parent_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b",
    "args": "{\"query\": \"password reset\"}",
    "result": "{\"hits\": 3}",
    "success": true,
    "latency": 143,
    "metadata": {
      "checkpoint.retrieved": 1712345678901,
      "checkpoint.ranked": 1712345678944
    }
  }'

Response

{
  "status": "ok",
  "event_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b"
}

Generate event_id client-side as a UUID so a later tool call can set its parent_id to this value.

​Headers

​Body

​The event tree

​Checkpoints

​Request

​A tool call under a turn

​Response

Headers

Body

The event tree

Checkpoints

Request

A tool call under a turn

Response