Event Schema

Every event shares a common envelope and carries a category-specific payload. This page documents the full schema for all 7 canonical event categories.

Envelope

All fields apply to every event regardless of category.

Field	Type	Required	Description
`eventId`	UUID	Yes	Client-generated unique identifier
`agentId`	string	Yes	Agent identifier (1–255 chars)
`sessionId`	string	Yes	Session identifier (1–255 chars)
`sourceTimestamp`	ISO 8601	Yes	When the event occurred (datetime with timezone)
`category`	string	Yes	One of the 7 categories below
`schemaVersion`	string	Yes	Schema version (currently `"1.0"`)
`payload`	object	Yes	Category-specific data
`previousHash`	string	No	SHA-256 hash of the previous event (chain integrity)

Attribution metadata (optional)

These fields are optional on every event and enable richer analysis:

Field	Type	Description
`sourceFramework`	string	SDK/framework that generated the event
`traceId`	string	Distributed trace identifier
`runId`	string	Execution run identifier
`correlationId`	string	Cross-session correlation ID
`parentEventId`	UUID	Parent event for causal chains
`causationEventId`	UUID	Direct cause event
`agentVersion`	string	Agent software version
`toolType`	string	Tool classification (e.g. `database`, `external_api`)
`targetSystem`	string	Target system identifier (e.g. `crm`, `production-db`)
`operation`	string	Operation type (e.g. `read`, `write`, `delete`)
`initiatorType`	string	Who initiated: `human`, `agent`, or `system`
`initiatorId`	string	Initiator identifier
`actorType`	string	Actor type
`actorId`	string	Actor identifier

Categories

`identity`

Agent identity assertion. Typically sent at session start.


{
  "category": "identity",
  "payload": {
    "agentName": "Support Bot",
    "version": "2.1.0",
    "capabilities": ["web_search", "database_query"]
  }
}

`reasoning`

Decision trace capturing the agent’s reasoning process.


{
  "category": "reasoning",
  "payload": {
    "summary": "Decided to escalate to human reviewer",
    "confidence": 0.85,
    "alternatives": ["auto-approve", "request-more-info"]
  }
}

`tool_api`

Tool or API invocation — the most common event type.


{
  "category": "tool_api",
  "payload": {
    "toolName": "database_query",
    "argumentsHash": "sha256:a1b2c3d4...",
    "responseStatus": 200,
    "endpoint": "/api/customers"
  }
}

Security note: Never include raw arguments in the payload. Use argumentsHash to capture a hash of the arguments for auditability without exposing sensitive data.

`browser_desktop`

UI interaction events for browser-based or desktop agents.


{
  "category": "browser_desktop",
  "payload": {
    "action": "navigate",
    "url": "https://crm.example.com/customers",
    "screenshotHash": "sha256:e5f6..."
  }
}

`data_movement`

Data access, modification, or export events.


{
  "category": "data_movement",
  "payload": {
    "operation": "export",
    "objectIds": ["customer-001", "customer-002"],
    "diffSummary": "Exported 2 customer records to CSV"
  }
}

Supported operations: read, write, delete, export.

`approval`

Human decision events — approvals or rejections.


{
  "category": "approval",
  "payload": {
    "approverId": "user-42",
    "scope": "delete:crm:customers:bulk",
    "decision": "approved"
  }
}

Supported decisions: approved, rejected.

`environment`

Runtime context events describing the agent’s operating environment.


{
  "category": "environment",
  "payload": {
    "isSandbox": false,
    "networkSegment": "prod-vpc",
    "workspace": "production-cluster"
  }
}

Validation

The API enforces strict validation on the event envelope — unknown top-level fields are rejected with a 400 error. The payload object accepts arbitrary keys within each category.

Events with an unknown category or missing required payload fields receive a 422 response. The raw event is still stored and can be re-processed when a normalization strategy becomes available.

Idempotency

Sending the same eventId for the same tenant is idempotent. The API returns 202 with the original receivedAt timestamp. No duplicate is created.