Threads API

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. Message clients render ordinary conversations; Agent, task, and subagent flows can create hidden threads that remain durable and auditable. The protocol separates thread data from sidebar layout. Use thread/get for one thread, thread/timeline/page for a paginated conversation view, and thread/tree for the complete workspace tree.

Methods

Method	Params	Result	Purpose
`thread/start`	`ThreadStartParams`	`ThreadStartResponse`	Create or open a thread.
`thread/update`	`ThreadUpdateParams`	`ThreadUpdateResponse`	Rename, archive, or change the visibility of a thread.
`thread/get`	`ThreadGetParams`	`ThreadGetResponse`	Load one thread.
`thread/tree`	`ThreadTreeParams`	`ThreadTreeResponse`	Load threads, folders, and placements for a workspace.
`thread/timeline/page`	`ThreadTimelinePageParams`	`ThreadTimelinePageResponse`	Load a paginated semantic timeline block page for a thread.
`thread/participants/list`	`ThreadParticipantsListParams`	`ThreadParticipantsResponse`	List the principals who can participate in a thread.
`thread/participants/add`	`ThreadParticipantMutationParams`	`ThreadParticipantsResponse`	Add a workspace member to a thread.
`thread/participants/remove`	`ThreadParticipantMutationParams`	`ThreadParticipantsResponse`	Remove a participant from a thread.
`thread/read`	`ThreadReadParams`	`ThreadReadResponse`	Move the caller’s read cursor through a thread.
`thread/patch_steps/page`	`ThreadPatchStepsPageParams`	`ThreadPatchStepsPageResponse`	Read verified or provider-reported patch steps for a thread.
`thread/file_patch_history/page`	`ThreadFilePatchHistoryPageParams`	`ThreadFilePatchHistoryPageResponse`	Read the change history for one workspace file.
`thread/file/view_grant/create`	`ThreadFileViewGrantCreateParams`	`ThreadFileViewGrantCreateResponse`	Create a short-lived grant for opening a linked workspace file.
`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.

{
  "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`	`Message` or `Agent`. Message is a people-focused conversation; Agent enables tool and task orchestration. `Chat` remains a compatibility value for older persisted threads.
`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.
`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

Message 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. Chat is retained for compatibility with older data. In Message mode the gateway focuses on conversation with the selected model and does not expose skill or MCP controls. 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

{
  "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.

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "thread/tree",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}

Response shape:

{
  "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 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.

{
  "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.

Timeline and read state

thread/timeline/page is the public thread-level read API. It returns semantic blocks for user messages, turn work, detached task runs, assistant messages, terminal state, and pending runtime requests. Use turn/work/page from the Turns API to expand the work inside a turn. The response includes a projection version and before/after cursors. A reconnecting client should refetch the affected page when it receives thread/timeline/blocks/changed, rather than rebuilding the view from notification order. thread/read records how far the current principal has read. The response returns the canonical cursor and unread count. Use thread/read/changed as an invalidation event for other clients. 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.

Participants and linked files

Participant methods are workspace-scoped and authorization-gated. A client should load the participant list before showing mentions or participant actions, and should refresh it after thread/participants/changed. The patch-history methods expose file changes associated with the thread. They report whether a result came from the native patch engine, a provider aggregate, or an incomplete observation. A linked workspace file is opened through thread/file/view_grant/create, which returns a short-lived /storage/views/... URL after the gateway checks the thread and file scope. See Patch history API for the request shapes.

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.

{
  "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 Turns API turn/items/page when you need raw item-event replay for one turn. 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

{
  "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/timeline/page, thread/read, turn/work/page, or turn/work/items/get as needed.

Introduction

Workspace & Threads

Features

Methods

Starting a thread

Thread modes

Composer execution mode

Reading one thread

Workspace tree

Moving threads and folders

Timeline and read state

Participants and linked files

Semantic timeline page

Unsubscribing

Notifications

​Methods

​Starting a thread

​Thread modes

​Composer execution mode

​Reading one thread

​Workspace tree

​Moving threads and folders

​Timeline and read state

​Participants and linked files

​Semantic timeline page

​Unsubscribing

​Notifications

Methods

Starting a thread

Thread modes

Composer execution mode

Reading one thread

Workspace tree

Moving threads and folders

Timeline and read state

Participants and linked files

Semantic timeline page

Unsubscribing

Notifications