Documentation

Events API

REST API endpoints for tracking events within agent sessions.

Base URL

https://api.tryguardy.com

Create Event

sessionIdstringrequired

ID of the parent session.

eventTypestringrequired

"tool_call", "llm_decision", "state_change", or "error".

toolNamestring

Name of the tool called (for tool_call events).

toolInputobject

Input passed to the tool.

toolOutputobject

Output returned by the tool.

reasoningstring

Agent's reasoning for this action.

alternativesConsideredarray

Other options the agent considered.

confidencenumber

Confidence score (0.0 to 1.0).

estimatedCostnumber

Cost for this event in USD.

Request

POST /api/sdk/events

{
  "sessionId": "sess_abc123def456",
  "eventType": "tool_call",
  "toolName": "search_kb",
  "toolInput": {
    "query": "password reset"
  },
  "toolOutput": {
    "results": ["KB-001", "KB-002"]
  },
  "reasoning": "User needs password help",
  "estimatedCost": 0.001
}

Response

{
  "id": "evt_xyz789",
  "sessionId": "sess_abc123def456",
  "eventType": "tool_call",
  "toolName": "search_kb",
  "createdAt": "2025-01-12T10:30:01Z"
}

Event Types

tool\_call

Track when your agent calls a tool.

{
  "sessionId": "sess_abc123def456",
  "eventType": "tool_call",
  "toolName": "search_knowledge_base",
  "toolInput": {
    "query": "how to reset password"
  },
  "toolOutput": {
    "results": ["KB-001", "KB-002"],
    "count": 2
  },
  "reasoning": "User asked about password reset",
  "estimatedCost": 0.001
}

llm\_decision

Track agent decision points.

{
  "sessionId": "sess_abc123def456",
  "eventType": "llm_decision",
  "reasoning": "User needs password help. Will search KB first before escalating.",
  "alternativesConsidered": [
    "escalate_to_human",
    "ask_clarifying_question"
  ],
  "confidence": 0.92,
  "estimatedCost": 0.0015
}

cURL Examples

Tool Call Event

curl -X POST https://api.tryguardy.com/api/sdk/events \
  -H "Authorization: Bearer guardy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123def456",
    "eventType": "tool_call",
    "toolName": "search_kb",
    "toolInput": {"query": "password reset"},
    "toolOutput": {"results": ["KB-001"]}
  }'

Decision Event

curl -X POST https://api.tryguardy.com/api/sdk/events \
  -H "Authorization: Bearer guardy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123def456",
    "eventType": "llm_decision",
    "reasoning": "Will search KB before escalating",
    "alternativesConsidered": ["escalate", "clarify"],
    "confidence": 0.92
  }'

Error Codes

Code	Title	Description
`400`	Bad Request	Missing required fields or invalid event type
`401`	Unauthorized	Invalid or missing API key
`404`	Not Found	Session ID not found
`500`	Internal Server Error	Server error, please retry

Next Steps

Sessions API

Create and manage sessions.

LangChain Integration

Automatic event tracking.