Skip to main content

​
Overview

The POST /chat endpoint returns a Server-Sent Events (SSE) stream. Each event has a type field indicating what happened.

​
Event types

​
thinking

Agent is processing. Includes a status message. 
{"type": "thinking", "content": "Searching memory..."}

​
text

Streamed response text (arrives in chunks). 
{"type": "text", "content": "Based on your "}

​
tool_call

Agent invoked a tool. 
{
  "type": "tool_call",
  "name": "recall",
  "args": {"query": "meeting notes"},
  "tool_id": "tc_abc123",
  "depth": 0
}

​
tool_result

Tool execution completed. 
{
  "type": "tool_result",
  "tool_id": "tc_abc123",
  "content": "Found 3 relevant facts...",
  "preview": "3 facts found",
  "duration": 0.45
}

​
approval_needed

Tool requires user approval before executing. 
{
  "type": "approval_needed",
  "tool_id": "tc_abc123",
  "name": "send_email",
  "args": {"to": "alice@example.com", "subject": "..."},
  "description": "Send email to alice@example.com"
}
Respond with POST /tool-result to approve or reject.

​
session_info

Session metadata update. 
{
  "type": "session_info",
  "session_id": "abc-123",
  "session_name": "Work planning"
}

​
done

Execution complete. Includes token usage. 
{
  "type": "done",
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 200,
    "cache_read_tokens": 800,
    "cost": 0.012
  }
}

​
error

An error occurred. 
{"type": "error", "content": "Rate limit exceeded", "fatal": false}

​
cancelled

User cancelled the run. 
{"type": "cancelled"}

​
Approval flow

When approval_needed is received:
  1. Display the tool call to the user
  2. Collect their decision (approve/reject)
  3. Submit via POST /tool-result:
curl -X POST http://localhost:8000/tool-result \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_abc",
    "tool_id": "tc_abc123",
    "result": "Approved",
    "approved": true
  }'
The stream continues after approval.