Workspace & Threads API

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 (Message or Agent), model, model provider, optional name, visibility, and turn history. Chat is a compatibility value for older threads.

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

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "workspace/list",
  "params": {}
}

Response:

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

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "workspace/default",
  "params": {}
}

Response:

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

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "workspace/create",
  "params": {
    "workspace_id": "ws_000000000000000002",
    "name": "Client A",
    "make_current": true
  }
}

Response:

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

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

{
  "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/timeline/page`	`ThreadTimelinePageParams`	`ThreadTimelinePageResponse`	Load a paginated semantic timeline block page.
`thread/update`	`ThreadUpdateParams`	`ThreadUpdateResponse`	Rename, archive, or change thread visibility.
`thread/participants/list`	`ThreadParticipantsListParams`	`ThreadParticipantsResponse`	List thread participants.
`thread/participants/add`	`ThreadParticipantMutationParams`	`ThreadParticipantsResponse`	Add a participant.
`thread/participants/remove`	`ThreadParticipantMutationParams`	`ThreadParticipantsResponse`	Remove a participant.
`thread/read`	`ThreadReadParams`	`ThreadReadResponse`	Update the caller’s read cursor.
`thread/patch_steps/page`	`ThreadPatchStepsPageParams`	`ThreadPatchStepsPageResponse`	Read patch steps associated with a thread.
`thread/file_patch_history/page`	`ThreadFilePatchHistoryPageParams`	`ThreadFilePatchHistoryPageResponse`	Read file-specific patch history.
`thread/file/view_grant/create`	`ThreadFileViewGrantCreateParams`	`ThreadFileViewGrantCreateResponse`	Create a short-lived workspace file view grant.
`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

{
  "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`	`Message` focuses on conversation and hides skill/MCP controls; `Agent` enables the agent loop and tool orchestration. `Chat` is retained for compatibility.
`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 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:

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

{
  "method": "thread/tree",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}

Result shape:

{
  "workspace_id": "ws_000000000000000001",
  "threads": [],
  "folders": [],
  "placements": [
    {
      "thread_id": "thr_000000000000000001",
      "workspace_id": "ws_000000000000000001",
      "folder_id": null
    }
  ]
}

Timeline and thread access

Use thread/timeline/page for the semantic conversation projection. It returns paginated blocks for messages, turn work, detached task runs, assistant output, terminal state, and pending runtime requests. Use turn/items/page for raw item events inside a specific turn. Neither API is the agent’s semantic recall surface; thread episodic context is an internal bounded prompt layer described in Thread Episodic Context. Thread access also includes participant membership and a per-principal read cursor. Participant changes publish thread/participants/changed; read progress publishes thread/read/changed. Clients should refetch the affected thread or timeline after either notification.

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.

Introduction