> ## Documentation Index
> Fetch the complete documentation index at: https://www.sentrial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API

> REST API endpoints for tracking events within agent sessions.

## Base URL

```
https://api.sentrial.com
```

## Create Event

<ParamField body="sessionId" type="string" required>
  ID of the parent session.
</ParamField>

<ParamField body="eventType" type="string" required>
  `"tool_call"`, `"llm_decision"`, `"state_change"`, or `"error"`.
</ParamField>

<ParamField body="toolName" type="string">
  Name of the tool called (for `tool_call` events).
</ParamField>

<ParamField body="toolInput" type="object">
  Input passed to the tool.
</ParamField>

<ParamField body="toolOutput" type="object">
  Output returned by the tool.
</ParamField>

<ParamField body="reasoning" type="string">
  Agent's reasoning for this action.
</ParamField>

<ParamField body="alternativesConsidered" type="array">
  Other options the agent considered.
</ParamField>

<ParamField body="confidence" type="number">
  Confidence score (0.0 to 1.0).
</ParamField>

<ParamField body="estimatedCost" type="number">
  Cost for this event in USD.
</ParamField>

### Request

```bash theme={null}
POST /api/sdk/events
```

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```bash theme={null}
curl -X POST https://api.sentrial.com/api/sdk/events \
  -H "Authorization: Bearer sentrial_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

```bash theme={null}
curl -X POST https://api.sentrial.com/api/sdk/events \
  -H "Authorization: Bearer sentrial_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

<CardGroup cols={2}>
  <Card title="Sessions API" icon="server" href="/api/sessions">
    Create and manage sessions.
  </Card>

  <Card title="LangChain Integration" icon="link" href="/integrations/langchain">
    Automatic event tracking.
  </Card>
</CardGroup>