Chat API

The Chat API manages conversations and message streaming. All endpoints are mounted under /api/chat (e.g., /api/chat/conversations).

Tip

For day-to-day usage, use the Chat page in the Snippbot UI rather than calling these endpoints directly.

Endpoints

Method	Path	Description
GET	/api/chat/conversations	List conversations
POST	/api/chat/conversations	Create a conversation
GET	/api/chat/conversations/{id}	Get a conversation
PUT	/api/chat/conversations/{id}	Update a conversation
DELETE	/api/chat/conversations/{id}	Delete a conversation
GET	/api/chat/conversations/{id}/mode	Get conversation mode
PATCH	/api/chat/conversations/{id}/mode	Set conversation mode
GET	/api/chat/conversations/{id}/execution-mode	Get execution mode
PUT	/api/chat/conversations/{id}/execution-mode	Set execution mode
POST	/api/chat/conversations/{id}/approval-response	Submit approval response
GET	/api/chat/conversations/{id}/check-ins	List open check-ins
DELETE	/api/chat/conversations/{id}/check-ins	Cancel all open check-ins
DELETE	/api/chat/conversations/{id}/check-ins/{check_in_id}	Cancel one check-in
POST	/api/chat/messages/stream	Send a message (streaming SSE)
POST	/api/chat/messages/inject	Inject a message into a conversation
POST	/api/chat/messages/truncate	Truncate messages
POST	/api/chat/welcome	Generate a welcome message
GET	/api/chat/sessions/{session_id}/stream	Remote session SSE stream

---

List Conversations

GET /api/chat/conversations

Returns all conversations.

---

Create Conversation

POST /api/chat/conversations

Creates a new conversation.

---

Get Conversation

GET /api/chat/conversations/{id}

Returns a single conversation by ID.

---

Update Conversation

PUT /api/chat/conversations/{id}

Updates a conversation (e.g., title).

---

Delete Conversation

DELETE /api/chat/conversations/{id}

Permanently deletes a conversation and its messages.

---

Send Message (Streaming)

POST /api/chat/messages/stream

Sends a message and returns the response as a stream of Server-Sent Events (SSE). The connection stays open until the full response is delivered.

SSE Event Format

Each event in the stream uses standard SSE format. The following event types are emitted:

token — incremental text chunk

event: token
data: {"content": "def reverse_linked_list"}

tool_use — agent is calling a tool

event: tool_use
data: {"tool": "write_file", "input": {"path": "solution.py"}}

tool_result — result of a tool call

event: tool_result
data: {"tool": "write_file", "output": {"success": true}}

done — response complete

event: done
data: {"message_id": "msg_01j9abc123", "input_tokens": 120, "output_tokens": 245, "total_tokens": 365}

error — stream error

event: error
data: {"code": "rate_limit", "message": "Provider rate limit reached. Retry in 30s."}

Note

The stream uses chunked transfer encoding. Some HTTP clients require explicit SSE or streaming support.

---

Inject Message

POST /api/chat/messages/inject

Injects a message into a conversation without triggering an agent response. Useful for programmatically adding context or instructions.

---

Truncate Messages

POST /api/chat/messages/truncate

Truncates messages in a conversation.

---

Generate Welcome

POST /api/chat/welcome

Generates a welcome message for a new conversation.

---

Conversation Mode

GET  /api/chat/conversations/{id}/mode
PATCH /api/chat/conversations/{id}/mode

Get or set the conversation mode for a specific conversation.

---

Execution Mode

GET /api/chat/conversations/{id}/execution-mode
PUT /api/chat/conversations/{id}/execution-mode

Get or set the execution mode (e.g., autonomous vs. approval-required) for a conversation.

---

Approval Response

POST /api/chat/conversations/{id}/approval-response

Submit an approval or rejection for a pending action within a conversation.

---

Check-ins

GET    /api/chat/conversations/{id}/check-ins
DELETE /api/chat/conversations/{id}/check-ins
DELETE /api/chat/conversations/{id}/check-ins/{check_in_id}

List the conversation’s open check-ins (armed or queued behind the room), soonest first, or cancel one or all of them.

{
  "check_ins": [
    {
      "check_in_id": "chk_3f2a9c1b7e04",
      "agent_id": "adam-dev",
      "due_at": "2026-09-30T17:36:37+00:00",
      "delay_minutes": 14,
      "waiting_on": "CI run for PR #2077",
      "estimate_basis": "runs take 15–18 min; 4 elapsed, 2/6 jobs done",
      "status": "pending",
      "source": "agent",
      "sequence": 1
    }
  ]
}

status is pending (armed) or delivering (due, waiting for the room). source is agent (the agent scheduled it), fallback (a backup armed because the agent ended waiting without one) or system (armed by the daemon, e.g. after a restart interrupted work). Cancelling returns {"cancelled": {...}} for one (404 if it isn’t open in this conversation) or {"cancelled": <count>} for all.

Changes are announced on /ws/events as chat.check_in.changed with {conversation_id, agent_id?}.