> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt > Use this file to discover all available pages before exploring further. # Threads API > Starting threads, reading thread models and history, managing the thread tree, and handling thread notifications. Threads are Pioneer's durable conversation containers. A thread belongs to a workspace, has a mode, stores its turns, and appears in the workspace tree unless it is hidden. Chat clients render threads directly; task and subagent flows often create hidden threads that remain durable and auditable. The protocol separates thread data from sidebar layout. Use `thread/get` for one thread, `thread/history` for replay, and `thread/tree` for the complete workspace tree. ## Methods | Method | Params | Result | Purpose | | ---------------------- | -------------------------- | ---------------------------- | ----------------------------------------------------------- | | `thread/start` | `ThreadStartParams` | `ThreadStartResponse` | Create or open a thread. | | `thread/get` | `ThreadGetParams` | `ThreadGetResponse` | Load one thread. | | `thread/tree` | `ThreadTreeParams` | `ThreadTreeResponse` | Load threads, folders, and placements for a workspace. | | `thread/history` | `ThreadHistoryParams` | `ThreadHistoryResponse` | Replay persisted thread events. | | `thread/timeline/page` | `ThreadTimelinePageParams` | `ThreadTimelinePageResponse` | Load a paginated semantic timeline block page for a thread. | | `thread/move` | `ThreadMoveParams` | `ThreadMoveResponse` | Move a thread within the tree. | | `thread/folder/create` | `ThreadFolderCreateParams` | `ThreadFolderCreateResponse` | Create a folder. | | `thread/folder/move` | `ThreadFolderMoveParams` | `ThreadFolderMoveResponse` | Move a folder. | | `thread/folder/delete` | `ThreadFolderDeleteParams` | `ThreadFolderDeleteResponse` | Delete a folder. | | `thread/unsubscribe` | `ThreadUnsubscribeParams` | `ThreadUnsubscribeResponse` | Stop receiving live notifications for a thread. | ## Starting a thread Clients provide the thread id. This supports reconnect and optimistic UI flows: the client can create local state immediately and reconcile it with the gateway response. ```json theme={null} { "jsonrpc": "2.0", "id": "aaaaaaaaaaaaaaaaaaaaa", "method": "thread/start", "params": { "thread_id": "thr_000000000000000001", "workspace_id": "ws_000000000000000001", "name": "Architecture review", "model": "gpt-5.1", "model_provider": "openai", "mode": "Agent", "sandbox": "FullAccess", "origin_kind": "user", "sidebar_visibility": "visible" } } ``` Important fields: | Field | Meaning | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `thread_id` | Client-provided stable id. | | `workspace_id` | Workspace that owns the thread. | | `name` | Optional display name. | | `model`, `model_provider` | Optional defaults used by turns in this thread. | | `mode` | `Chat` or `Agent`. Chat is plain assistant conversation; Agent enables tool and task orchestration. | | `sandbox` | Legacy thread sandbox display field. Current value is `FullAccess`; turn-level permission and sandbox/resource behavior is controlled by `permission_profile` in [Turns API](/protocol/turns). | | `origin_kind` | `collaborative`, `direct_message`, `user`, `task_run`, or `system`. `collaborative` threads run Composer submissions as detached task work; the other origins use foreground Composer execution. | | `sidebar_visibility` | `visible` or `hidden`. Hidden threads are useful for subagents and internal task runs. | | `agent_nickname`, `agent_role` | Optional labels for agent/subagent threads. | `mode` and `sandbox` are PascalCase because they are Rust enum variants without snake-case renaming. `origin_kind` and `sidebar_visibility` are snake-case strings. ## Thread modes `Chat` and `Agent` are part of the thread model, not separate APIs. A client starts turns the same way in both modes through `turn/start`; the gateway decides which execution path to run. In `Chat` mode the gateway focuses on conversation with the selected model. In `Agent` mode the gateway can compile richer context, expose tools, call MCP servers, invoke skills, create tasks, and coordinate subagents. Clients should show the mode clearly because it changes what a user should expect from a turn. ## Composer execution mode Thread origin also determines how a Composer submission is admitted: | Thread origin | Composer execution | Product meaning | | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collaborative` | `detached_task` | Each submitted request runs independently in a child conversation. The parent timeline receives a live task card and the result is delivered back when ready. | | `direct_message` | `foreground_turn` | The Composer request runs in the current conversation. | | `user`, `task_run`, `system` | `foreground_turn` | Compatibility and internal origins that keep foreground Composer behavior. | Clients should render the resolved execution behavior from the thread contract. Do not infer it from sidebar visibility: a hidden task thread and a visible collaborative thread have different roles, but both are gateway-owned execution state. ## Reading one thread ```json theme={null} { "jsonrpc": "2.0", "id": "bbbbbbbbbbbbbbbbbbbbb", "method": "thread/get", "params": { "thread_id": "thr_000000000000000001" } } ``` Use `thread/get` when opening a thread by id or reconciling after a notification. The response contains the durable thread row with its workspace id, mode, model defaults, status fields, and timestamps. ## Workspace tree `thread/tree` is the primary method for a sidebar or thread picker. It returns related collections: threads, folders, placements, and AGENTS.md summaries. Do not sort threads by timestamps and call it a tree; folder placement is stored separately. ```json theme={null} { "jsonrpc": "2.0", "id": "ccccccccccccccccccccc", "method": "thread/tree", "params": { "workspace_id": "ws_000000000000000001" } } ``` Response shape: ```json theme={null} { "workspace_id": "ws_000000000000000001", "threads": [], "folders": [], "placements": [], "agents_docs": [] } ``` Placements let the gateway preserve UI structure across clients. `agents_docs` contains content-free summaries for root and folder `AGENTS.md` files. If another client moves a thread or changes an AGENTS.md file, your client should refresh the tree after `thread/tree/changed`. See [AGENTS.md API](/protocol/agents-md) for reading and editing full file content. ## Moving threads and folders Use move methods for tree edits instead of mutating local order and hoping the gateway catches up. ```json theme={null} { "jsonrpc": "2.0", "id": "ddddddddddddddddddddd", "method": "thread/move", "params": { "workspace_id": "ws_000000000000000001", "thread_id": "thr_000000000000000001", "folder_id": "fld_000000000000000001" } } ``` Folder methods follow the same shape: create a folder under a workspace, move it to a different parent, or delete it. Folder deletion is a layout operation; clients should refresh `thread/tree` afterward to render the gateway's resulting state. ## Thread history `thread/history` returns durable protocol events as well as final assistant messages. Use it to rebuild a thread timeline after reconnect, crash recovery, or opening a thread on another device. ```json theme={null} { "jsonrpc": "2.0", "id": "eeeeeeeeeeeeeeeeeeeee", "method": "thread/history", "params": { "thread_id": "thr_000000000000000001", "limit": 200 } } ``` History events include turn starts, item starts, streamed deltas, item completions, retries, recovery events, tool-loop budget events, and terminal turn events. For current rendering, prefer `thread/timeline/page` for semantic thread blocks and [Turns API](/protocol/turns) `turn/work/page` for expanded turn work; use `thread/history` when you need to rebuild from the thread level. `thread/history` is not the semantic recall API. It gives clients durable events so they can render and recover UI. It should not be used to dump an entire old thread into a model prompt. For agent-side "what did we discuss earlier?" behavior, Pioneer uses thread episodic context internally: visible conversation material is indexed, searched, filtered, and inserted as bounded prompt snippets when recall decides it is useful. That layer is configured through settings and described in [Thread Episodic Context](/architecture/thread-episodic-context). ## Semantic timeline page `thread/timeline/page` is the paginated, semantic timeline read API used by shared client timeline reducers. It returns display-oriented blocks rather than raw event rows. ```json theme={null} { "method": "thread/timeline/page", "params": { "threadId": "thr_000000000000000001", "anchor": { "kind": "newest" }, "limit": 40 } } ``` `anchor` is a `TimelinePageAnchor`: `newest`, `oldest`, `before`, `after`, or `around`. Cursor-based anchors carry a `cursor.value`. The response includes `workspaceId`, `threadId`, `projectionVersion`, `blocks`, and `page`. Blocks can represent: | Block kind | Meaning | | ------------------- | ---------------------------------------------------------------------------------------------------------- | | `user_message` | User input, text, and attachment chips. | | `turn_work` | Collapsible work block for a turn, with state and pagination cursors. | | `detached_task_run` | A background Composer request represented as a task card, with task status and child-conversation linkage. | | `assistant_message` | Assistant-visible answer block. | | `turn_state` | Terminal or intermediate turn state block. | | `pending_request` | Runtime-native pending request block, such as a CLI approval/input prompt. | Use `thread/timeline/page` for scrollable client timelines. Use `thread/history` when you need durable event replay. Generated schemas: * `/schemas/thread_timeline_page_params.json` * `/schemas/thread_timeline_page_response.json` * `/schemas/thread_timeline_blocks_changed_notification.json` * `/schemas/timeline_page_anchor.json` * `/schemas/timeline_page_info.json` * `/schemas/timeline_block.json` * `/schemas/timeline_block_kind.json` ## Unsubscribing ```json theme={null} { "jsonrpc": "2.0", "id": "fffffffffffffffffffff", "method": "thread/unsubscribe", "params": { "thread_id": "thr_000000000000000001" } } ``` Use this when a client closes a thread view but keeps the WebSocket connection open. It reduces live event fan-out; it does not delete the thread or its history. ## Notifications | Event | Meaning | | -------------------------------- | ---------------------------------------------------------------------------------------------- | | `thread/started` | A thread was created/opened. | | `thread/updated` | Thread metadata changed. | | `thread/closed` | Thread was closed. | | `thread/tree/changed` | The workspace thread tree changed and should be reloaded. | | `thread/agents_doc/changed` | A root or folder AGENTS.md file changed and affected tree summaries or effective instructions. | | `thread/timeline/blocks/changed` | A semantic timeline block page may be stale; reload affected blocks or the current page. | Thread notifications are not a replacement for read methods. Treat them as invalidation and streaming hints, then call `thread/get`, `thread/tree`, `thread/history`, `thread/timeline/page`, `turn/work/page`, or `turn/work/items/get` as needed.