Octop Chat API: WebSocket Streaming and Thread Management

Send messages to Octop agents via WebSocket for real-time streaming. Manage conversation threads with session create, list, and history endpoints.

Octop streams agent responses over a WebSocket connection, delivering chunks in real time as the model generates them. Thread management — creating, listing, renaming, and retrieving history — uses standard REST endpoints under the same agent path. All endpoints require owner-level access to the target agent.

​

WebSocket chat

​

Endpoint

WS /api/agents/{id}/chat/ws?token=<jwt>

Pass your JWT as the token query parameter. The WebSocket connection stays open for the lifetime of a conversation session; you can send multiple turns on the same connection.

​

Message frames

Send a user turn:

{"type": "user_turn", "content": "Hello, what can you help me with?", "thread_id": "abc123"}

Receive streaming response chunks — the server emits one or more content frames, then terminates with a done or error frame:

{"type": "chunk", "content": "I can help you with research, writing, "}
{"type": "chunk", "content": "code review, and more."}
{"type": "done"}

On error:

{"type": "error", "message": "Agent runtime is unavailable."}

Keepalive ping/pong:

// Send
{"type": "ping"}

// Receive
{"type": "pong"}

Resume an in-flight turn after reconnect — disconnect alone does not cancel the turn. Send subscribe to attach to a thread that is still streaming; the server replies with turn_status:

// Send
{"type": "subscribe", "thread_id": "abc123"}

// Receive
{"type": "turn_status", "thread_id": "abc123", "active": true}

Stop an active turn explicitly:

{"type": "cancel", "thread_id": "abc123"}

thread_id is stable across sessions. Pass the same thread_id on every turn to keep messages in one continuous conversation. Use session_key to resume a specific thread when opening a new WebSocket connection. After a page reload, call history and check turn_active before re-subscribe.

​

Thread management endpoints

Method	Path	Auth	Description
GET	/agents/{id}/chat/sessions	owner	List threads
POST	/agents/{id}/chat/sessions	owner	Create thread
PATCH	/agents/{id}/chat/sessions/{thread_id}	owner	Rename or pin thread
DELETE	/agents/{id}/chat/sessions/{thread_id}	owner	Archive thread
GET	/agents/{id}/chat/sessions/{thread_id}/history	owner	Paginated message history; includes turn_active, artifacts, and knowledge citations when present
POST	/agents/{id}/threads/{thread_id}/fork	owner	Fork a thread at an assistant reply
GET	/agents/{id}/threads/{thread_id}/trajectory	owner	Paginated run-trajectory summaries; use before_seq for older rows
GET	/agents/{id}/threads/{thread_id}/trajectory/events/{event_id}	owner	Full event payload
GET	/agents/{id}/threads/{thread_id}/trajectory/metrics	owner	Aggregated turn, timing, and token metrics
GET	/agents/{id}/threads/{thread_id}/trajectory/stream	owner	Live SSE; resume with after_seq or Last-Event-ID
GET	/agents/{id}/threads/{thread_id}/trajectory/export	owner	Download the ledger as JSONL (default) or JSON

​

Create a thread

Creating a thread returns a thread_id for routing turns and a session_key for resuming the thread across WebSocket reconnections.

cURL

curl -X POST http://127.0.0.1:8088/api/agents/main/chat/sessions \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

​

Get message history

Retrieve paginated message history for a specific thread.

cURL

curl 'http://127.0.0.1:8088/api/agents/main/chat/sessions/abc123/history' \
  -H 'Authorization: Bearer $TOKEN'

The response returns a paginated array of message objects ordered chronologically, plus turn_active (boolean). When turn_active is true, re-open the chat WebSocket and send {"type":"subscribe","thread_id":"..."} to resume streaming. Use the standard limit and offset query parameters to page through long threads.

​

Rename or pin a thread

Send a PATCH request with a title to rename a thread, or set pinned: true to pin it to the top of the session list.

cURL

curl -X PATCH http://127.0.0.1:8088/api/agents/main/chat/sessions/abc123 \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Q2 Research Session", "pinned": true}'

​

Polish endpoint

The polish endpoint accepts a single prompt and returns a refined version in one shot — useful for improving user messages before sending them to an agent.

cURL

curl -X POST http://127.0.0.1:8088/api/agents/main/chat/polish \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text": "make this shorter: ...your text..."}'

The response body is {"text": "...refined text..."}. You can optionally pass default_model to override the agent’s default for this one call.

​

Fork a thread

POST /api/agents/{id}/threads/{thread_id}/fork copies a conversation into a new thread up to a chosen assistant reply. The original thread is unchanged. Send assistant_turns_from_end: 1 to fork from the latest reply, or pass a message_id. The agent must be running.

​

Files and knowledge citations

Thread list and history include generated files (for example after the agent writes a file or takes a desktop screenshot) and knowledge-base sources when the reply used your documents. Click a citation in the web UI to preview the document in chat.

​

Run trajectory

GET /agents/{id}/threads/{thread_id}/trajectory* exposes the same ledger as the chat trajectory drawer: paginated event summaries, a single full event, aggregated metrics, a live SSE stream, and an export. Use these when you need an audit of turns and tool calls without scraping the chat UI.

Use the polish endpoint in your own UI to offer a “Improve my prompt” button — it adds minimal latency and runs on the same model as the agent without persisting anything to the thread history.