Hooks
The hooks API records and analyzes events from Claude Code hooks. Hooks fire at key lifecycle points (session start/end, before/after tool use) and can block dangerous operations. See Claude Hooks for configuration.
Endpoints
List Hook Events
GET /api/hooks/events
Retrieve hook events with filtering. Results are ordered by most recent first.
Authentication: Required
Query Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
eventType | string or string | No | Filter by type(s): SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit |
sessionId | string | No | Filter by Claude session ID |
toolName | string | No | Filter by tool name (e.g., Bash, Edit) |
blocked | boolean | No | Filter by blocked status (true or false) |
since | string (ISO date) | No | Only events after this timestamp |
limit | number | No | Max results (default 100, max 500) |
Response: 200 OK
{
"data": [
{
"id": "uuid",
"eventType": "PreToolUse",
"sessionId": "session-abc",
"projectDir": "/home/user/my-project",
"toolName": "Bash",
"toolMatcher": "Bash",
"eventData": { "command": "rm -rf /tmp/test" },
"exitCode": 2,
"blocked": true,
"blockReason": "Dangerous command blocked by protect-env hook",
"durationMs": 45,
"hookScript": "hooks/protect-env.sh",
"createdAt": "2026-02-18T12:00:00.000Z"
}
]
}
Log Hook Event
POST /api/hooks/events
Record a new hook event. Called by Claude Code hooks at runtime. Broadcasts a resource_change notification.
Authentication: Required
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
eventType | string | Yes | One of: SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit |
sessionId | string | No | Claude session ID |
projectDir | string | No | Working directory |
toolName | string | No | Tool that triggered the hook |
toolMatcher | string | No | Hook matcher pattern |
eventData | object | No | Arbitrary event metadata (stored as JSON) |
exitCode | number | No | Hook script exit code |
blocked | boolean | No | Whether the action was blocked (default false) |
blockReason | string | No | Human-readable reason for blocking |
durationMs | number | No | Hook execution time in milliseconds |
hookScript | string | No | Path to the hook script that ran |
Response: 201 Created
{
"data": {
"id": "uuid",
"eventType": "PreToolUse",
"blocked": true,
"blockReason": "Attempted to edit .env file",
"createdAt": "2026-02-18T12:00:00.000Z"
}
}
Hook Stats
GET /api/hooks/stats
Aggregate hook analytics for a given time period. Includes block rates, tool breakdowns, daily activity, and recent sessions.
Authentication: Required
Query Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
period | string | No | Time window: 24h, 7d (default), or 30d |
Response: 200 OK
{
"data": {
"totalEvents": 1250,
"blockedEvents": 42,
"blockRate": 3,
"avgDurationMs": 28,
"eventsByType": {
"PreToolUse": 600,
"PostToolUse": 580,
"SessionStart": 35,
"SessionEnd": 35
},
"toolBreakdown": [
{ "toolName": "Bash", "total": 400, "blocked": 30, "avgDurationMs": 35 },
{ "toolName": "Edit", "total": 200, "blocked": 12, "avgDurationMs": 20 }
],
"dailyActivity": [
{ "date": "2026-02-17", "total": 180, "blocked": 6, "allowed": 174, "avgDurationMs": 0 }
],
"recentSessions": ["session-abc", "session-def"]
}
}
Event Types
| Type | When It Fires |
|---|---|
SessionStart | Claude Code session begins |
SessionEnd | Claude Code session ends |
PreToolUse | Before a tool call executes (can block) |
PostToolUse | After a tool call succeeds |
PostToolUseFailure | After a tool call fails |
UserPromptSubmit | When the user submits a prompt |
The blockRate is a percentage (0-100). A high block rate may indicate overly aggressive hook rules or repeated attempts to perform restricted operations.