Skip to main content

​
Connect to event stream

Open a persistent SSE connection to receive events for a session. 
curl -N http://localhost:6877/chat/events/{session_id} \
  -H "Authorization: Bearer $API_KEY"
Returns text/event-stream. See Streaming for event types.

​
Send message

curl -X POST http://localhost:6877/chat/message \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What meetings do I have today?", "session_id": "abc-123"}'
Useful request fields:
FieldTypeDescription
messagestringUser message
session_idstringTarget session
imagesarrayOptional base64 image attachments
skip_approvalsbooleanAuto-approve all tool calls for this run
Response: 
{"run_id": "run_abc", "session_id": "abc-123"}
The assistant response arrives on the SSE stream.

​
Submit tool result

Approve or reject a pending tool call. 
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
  }'

​
Background a run

Move an active agent run into background mode. The UI is unblocked immediately and results are delivered via SSE when complete. 
curl -X POST http://localhost:6877/chat/background \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_id": "run_abc"}'

​
Cancel

Cancel a running agent loop by run or session. 
curl -X POST http://localhost:6877/cancel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"run_abc"}'
Or: 
{"session_id":"abc-123"}
Cancel a foreground subagent tool call: 
curl -X POST http://localhost:6877/chat/subagents/{tool_call_id}/cancel \
  -H "Authorization: Bearer $API_KEY"

​
Queued injections

If a message is queued for injection into an active run, cancel it by client id: 
curl -X DELETE http://localhost:6877/chat/inject/{client_id} \
  -H "Authorization: Bearer $API_KEY"

​
Run status

curl http://localhost:6877/chat/runs/status \
  -H "Authorization: Bearer $API_KEY"

curl http://localhost:6877/chat/{session_id}/workflows \
  -H "Authorization: Bearer $API_KEY"

​
Background tasks and child agents

curl http://localhost:6877/chat/background-tasks \
  -H "Authorization: Bearer $API_KEY"

curl -X POST http://localhost:6877/chat/background-tasks/{task_id}/cancel \
  -H "Authorization: Bearer $API_KEY"
Child agents created by research/workflow tools can be inspected and controlled: 
curl http://localhost:6877/chat/child-agents \
  -H "Authorization: Bearer $API_KEY"

curl http://localhost:6877/chat/child-agents/{child_run_id}/result \
  -H "Authorization: Bearer $API_KEY"

curl -X POST http://localhost:6877/chat/child-agents/{child_run_id}/cancel \
  -H "Authorization: Bearer $API_KEY"

curl -X POST http://localhost:6877/chat/child-agents/{child_run_id}/inject \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"extra context"}'

​
Context usage

curl http://localhost:6877/context \
  -H "Authorization: Bearer $API_KEY"
Response includes model, context limit, message count, and visible/deferred/loaded tool counts.

​
Compact context

Compress conversation history to free token space. 
curl -X POST http://localhost:6877/compact \
  -H "Authorization: Bearer $API_KEY"