> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**

```json theme={null}
{"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:

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

**On error:**

```json theme={null}
{"type": "error", "message": "Agent runtime is unavailable."}
```

**Keepalive ping/pong:**

```json theme={null}
// 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`:

```json theme={null}
// Send
{"type": "subscribe", "thread_id": "abc123"}

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

**Stop an active turn explicitly:**

```json theme={null}
{"type": "cancel", "thread_id": "abc123"}
```

> [!NOTE]
>
> `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.

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

```json Response theme={null}
{"thread_id": "abc123", "session_key": "sk_..."}
```

## Get message history

Retrieve paginated message history for a specific thread.

```bash cURL theme={null}
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.

```bash cURL theme={null}
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.

```bash cURL theme={null}
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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.