Skip to main content
POST
/
api
/
v1
/
capture-event
Capture event
curl --request POST \
  --url https://api.agnost.ai/api/v1/capture-event \
  --header 'Content-Type: application/json' \
  --header 'x-org-id: <x-org-id>' \
  --data '
{
  "event_id": "e8b1c52f-3a9d-4e7c-8f0b-2d6a91c4ef58",
  "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
  "primitive_name": "your-agent-name",
  "args": "your input in plain text or JSON-encoded string",
  "result": "your output in plain text or JSON-encoded string",
  "success": true,
  "latency": 5200,
  "timestamp": 1714867201000,
  "parent_id": "4c7d2e8a-1b95-4f3d-a08e-7b3c9d12f5e6",
  "metadata": {
    "language": "hi-IN"
  }
}
'
{
  "event_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
Generate event_id client-side (UUID) so child events can reference their parent before the parent’s response returns.

​
Body

FieldTypeRequiredDescription
event_idstring (UUID)RequiredClient-generated UUID. Use as parent_id on child events.
session_idstring (UUID)RequiredSession UUID from capture-session.
primitive_namestringRequiredAgent name (turn-pair) or tool name (tool call).
argsstringRequiredInput: user message or JSON-encoded tool args.
resultstringRequiredOutput: assistant reply or JSON-encoded tool result.
successbooleanOptionalDefaults to true.
latencyinteger (ms)OptionalExecution time in milliseconds.
timestampinteger (ms)OptionalUnix time in ms when the event occurred. Defaults to server time.
parent_idstring (UUID)OptionalParent event UUID. Set on tool calls to point at the agent turn (or parent tool) that triggered them.
metadataobjectOptionalFree-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.

Headers

​
x-org-id
string
required

Your organization ID (UUID, case-insensitive).

Example:

"<org-id>"

Body

application/json
​
event_id
string<uuid>
required

Client-generated UUID. Use as parent_id on child events.

Example:

"e8b1c52f-3a9d-4e7c-8f0b-2d6a91c4ef58"

​
session_id
string<uuid>
required

Session UUID from capture-session.

Example:

"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731"

​
primitive_name
string
required

Agent name (turn-pair) or tool name (tool call).

Example:

"your-agent-name"

​
args
string
required

Input — user message or JSON-encoded tool args.

Example:

"your input in plain text or JSON-encoded string"

​
result
string
required

Output — assistant reply or JSON-encoded tool result.

Example:

"your output in plain text or JSON-encoded string"

​
success
boolean

Defaults to true.

​
latency
integer

Execution time in ms.

Example:

5200

​
timestamp
integer<int64>

Unix time in ms when the event occurred. Defaults to server time.

Example:

1714867201000

​
parent_id
string<uuid>

Parent event UUID. Set on tool calls to point at the agent turn (or parent tool) that triggered them.

Example:

"4c7d2e8a-1b95-4f3d-a08e-7b3c9d12f5e6"

​
metadata
object

Free-form event metadata.

Example:
{ "language": "hi-IN" }

Response

Event recorded

​
event_id
string<uuid>