> ## 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. # Workspace & Threads API > JSON-RPC methods for workspace lookup, thread lifecycle, folders, thread history, and thread notifications. Workspaces group threads, provider configuration, skills, MCP policy, tasks, artifacts, and settings. Clients can list workspaces, create new ones, select the active workspace for a connection, persist the current workspace, and rename existing workspaces. Threads are the primary conversation container. A thread has a workspace, mode (`Chat` or `Agent`), model, model provider, optional name, sidebar visibility, and turn history. ## Workspace methods | Method | Params | Result | Purpose | | ------------------- | ------------------------ | -------------------------- | ----------------------------------------------------------------------------- | | `workspace/list` | `WorkspaceListParams` | `WorkspaceListResponse` | Return known workspaces. | | `workspace/default` | `WorkspaceDefaultParams` | `WorkspaceDefaultResponse` | Return or create the default workspace. | | `workspace/create` | `WorkspaceCreateParams` | `WorkspaceCreateResponse` | Create a workspace by caller-provided `workspace_id`. | | `workspace/select` | `WorkspaceSelectParams` | `WorkspaceSelectResponse` | Select a workspace for the current connection and optionally make it current. | | `workspace/update` | `WorkspaceUpdateParams` | `WorkspaceUpdateResponse` | Update workspace metadata such as the display name. | ## Workspace shape | Field | Meaning | | -------------------------- | ------------------------------------------------------------------------- | | `id` | Stable workspace id. | | `name` | Display name. | | `is_active` | Whether the workspace can be selected. | | `is_current` | Whether the workspace is the persisted current workspace for the gateway. | | `created_at`, `updated_at` | Unix timestamps. | ## Listing workspaces ```json theme={null} { "jsonrpc": "2.0", "id": "aaaaaaaaaaaaaaaaaaaaa", "method": "workspace/list", "params": {} } ``` Response: ```json theme={null} { "workspaces": [ { "id": "ws_000000000000000001", "name": "Default Workspace", "is_active": true, "is_current": true, "created_at": 1760000000, "updated_at": 1760000000 } ] } ``` ### `workspace/default` Use this when a client needs a workspace id and wants the gateway to create the default workspace if it does not exist. ```json theme={null} { "jsonrpc": "2.0", "id": "aaaaaaaaaaaaaaaaaaaaa", "method": "workspace/default", "params": {} } ``` Response: ```json theme={null} { "workspace": { "id": "ws_000000000000000001", "name": "Default Workspace", "is_active": true, "is_current": true, "created_at": 1760000000, "updated_at": 1760000000 } } ``` ## Creating a workspace The client generates the `workspace_id`. `name` is optional; if omitted, the gateway assigns a default display name. Set `make_current` when the new workspace should become the persisted current workspace. ```json theme={null} { "jsonrpc": "2.0", "id": "bbbbbbbbbbbbbbbbbbbbb", "method": "workspace/create", "params": { "workspace_id": "ws_000000000000000002", "name": "Client A", "make_current": true } } ``` Response: ```json theme={null} { "workspace": { "id": "ws_000000000000000002", "name": "Client A", "is_active": true, "is_current": true, "created_at": 1760000100, "updated_at": 1760000100 } } ``` ## Selecting a workspace `workspace/select` associates the current WebSocket connection with a workspace. Set `make_current` when the selection should also be persisted as the gateway's current workspace. ```json theme={null} { "jsonrpc": "2.0", "id": "ccccccccccccccccccccc", "method": "workspace/select", "params": { "workspace_id": "ws_000000000000000002", "make_current": true } } ``` After selecting a workspace, clients should reload workspace-scoped views such as the thread tree, providers, MCP servers, skills, tasks, and artifacts. ## Updating a workspace Use `workspace/update` to rename a workspace. ```json theme={null} { "jsonrpc": "2.0", "id": "ddddddddddddddddddddd", "method": "workspace/update", "params": { "workspace_id": "ws_000000000000000002", "name": "Client A Research" } } ``` ## Workspace notifications The gateway sends `workspace/changed` when a workspace is created, updated, or when the current workspace changes. The notification payload has `kind` (`created`, `updated`, or `current_changed`) and `workspace`. ## Thread methods | Method | Params | Result | Purpose | | ---------------------- | -------------------------- | ---------------------------- | ------------------------------------------------------------ | | `thread/start` | `ThreadStartParams` | `ThreadStartResponse` | Create a thread and subscribe the current connection to it. | | `thread/get` | `ThreadGetParams` | `ThreadGetResponse` | Load one thread. | | `thread/tree` | `ThreadTreeParams` | `ThreadTreeResponse` | Load workspace threads, folders, and placements. | | `thread/history` | `ThreadHistoryParams` | `ThreadHistoryResponse` | Replay durable history events for a thread. | | `thread/timeline/page` | `ThreadTimelinePageParams` | `ThreadTimelinePageResponse` | Load a paginated semantic timeline block page. | | `thread/move` | `ThreadMoveParams` | `ThreadMoveResponse` | Move a thread into or out of a folder. | | `thread/folder/create` | `ThreadFolderCreateParams` | `ThreadFolderCreateResponse` | Create a folder. | | `thread/folder/move` | `ThreadFolderMoveParams` | `ThreadFolderMoveResponse` | Move a folder under another folder or to root. | | `thread/folder/delete` | `ThreadFolderDeleteParams` | `ThreadFolderDeleteResponse` | Delete a folder. | | `thread/unsubscribe` | `ThreadUnsubscribeParams` | `ThreadUnsubscribeResponse` | Stop sending thread-scoped notifications to this connection. | ## Starting a thread ```json theme={null} { "jsonrpc": "2.0", "id": "eeeeeeeeeeeeeeeeeeeee", "method": "thread/start", "params": { "thread_id": "thr_000000000000000001", "workspace_id": "ws_000000000000000001", "name": "Research", "model": "google/gemini-3-flash-preview", "model_provider": "openrouter", "mode": "Agent", "sandbox": "FullAccess" } } ``` Important fields: | Field | Notes | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `thread_id` | Client-provided id. | | `workspace_id` | Workspace that owns the thread. | | `mode` | `Chat` disables tools; `Agent` enables the agent loop and tool 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 Composer submissions run as detached task work; task subagents use hidden task-run threads. | | `sidebar_visibility` | `visible` or `hidden`. Hidden is used for internal/task threads. | | `agent_nickname`, `agent_role` | Optional labels for task/subagent threads. | Response: ```json theme={null} { "thread": { "id": "thr_000000000000000001", "workspace_id": "ws_000000000000000001", "name": "Research", "mode": "Agent", "status": "Idle" }, "sandbox": { "mode": "FullAccess" } } ``` ## Thread tree `thread/tree` returns all threads plus folders and placement rows for a workspace. Clients should use this instead of trying to infer sidebar layout from thread rows alone. ```json theme={null} { "method": "thread/tree", "params": { "workspace_id": "ws_000000000000000001" } } ``` Result shape: ```json theme={null} { "workspace_id": "ws_000000000000000001", "threads": [], "folders": [], "placements": [ { "thread_id": "thr_000000000000000001", "workspace_id": "ws_000000000000000001", "folder_id": null } ] } ``` ## Thread history `thread/history` returns durable events as well as final messages. Use it to rebuild a timeline after reconnect. ```json theme={null} { "method": "thread/history", "params": { "thread_id": "thr_000000000000000001", "limit": 500 } } ``` History event payloads include turn start, item start, item deltas, item completion, recovery events, tool retry events, tool loop budget events, and terminal turn events. This is a replay surface for clients, not the semantic recall surface used by the agent. Clients should not use `thread/history` to push whole old transcripts into a model request. Agent-side recall uses thread episodic context: the gateway indexes visible conversation fragments, searches them when needed, and injects bounded snippets into prompt context. ## Thread notifications | Event | Params | Meaning | | --------------------- | ------------------------------- | --------------------------------------------------- | | `thread/started` | `ThreadStartedNotification` | A thread was created and started. | | `thread/updated` | `ThreadUpdatedNotification` | Thread metadata or status changed. | | `thread/closed` | `ThreadClosedNotification` | Thread was closed/unloaded for this client context. | | `thread/tree/changed` | `ThreadTreeChangedNotification` | Thread/folder/sidebar tree should be reloaded. | Thread subscription is connection-scoped. Starting or interacting with a thread associates the connection with that thread/workspace; `thread/unsubscribe` removes the thread subscription for that connection.