Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ntrp.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

ntrp uses a persistent SSE connection per session. Connect to GET /chat/events/{session_id} to receive all events (agent responses, tool calls, background task results). Messages are sent via POST /chat/message as fire-and-forget — the response arrives on the 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

Complete response text block. 
{"type": "text", "content": "Based on your calendar, you have 3 meetings today."}

​
text_delta

Streamed token-level text delta. Only sent when streaming is enabled (pass ?stream=true on the SSE connection, or enable in Settings > Connection). 
{"type": "text_delta", "content": "Based"}
Deltas arrive as individual tokens. Accumulate them to build the full response. A final text event is also sent as a complete fallback.

​
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 /tools/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}

​
background_task

A background task changed state (started, completed, failed, or cancelled). 
{"type": "background_task", "task_id": "bg_abc123", "command": "research(deep): research topic", "status": "completed"}

​
backgrounded

A running agent was moved to background mode. 
{"type": "backgrounded", "run_id": "run_abc"}

​
cancelled

User cancelled the run. 
{"type": "cancelled", "run_id": "run_abc"}

​
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 /tools/result:
curl -X POST http://localhost:6877/tools/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.