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 (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

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

{
  "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.
`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
    }
  ]
}

Thread history

thread/history returns durable events as well as final messages. Use it to rebuild a timeline after reconnect.

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

Introduction