Overview Workspaces provide agents with an isolated sandbox file system. When an agent uses agent reasoning mode, it has access to built-in file tools (write, read, edit, grep, delete) that operate on workspace files.
Workspaces must be enabled for agents to use file tools, edit mode (chat_mode: 'edit'), and plan mode (chat_mode: 'plan'). When workspace is disabled, these tools are removed and chat mode falls back to ask.
Each workspace is scoped per-agent and per-user:
Authenticated users — each user gets their own workspace per agentAnonymous users — each chat conversation gets an isolated workspace
When an agent runs in agent reasoning mode, these tools are automatically available:
Tool Description Approval writeCreate or overwrite a file Conditional readRead file content (supports line ranges) Auto editExact string replacement in a file Conditional grepRegex search across workspace files Auto deleteSoft-delete a file Conditional
Tools marked “Conditional” require user approval before execution (configurable per agent). Tools marked “Auto” execute without approval.
write Create a new file or overwrite an existing one:
Parameter Type Required Description file_pathstring Yes Virtual file path (e.g., /src/app.js) contentstring Yes Full file content languagestring No Programming language hint
read Read a file’s content, optionally by line range:
Parameter Type Required Description file_pathstring Yes Virtual file path to read start_lineinteger No Start line (1-based) end_lineinteger No End line (1-based, inclusive)
edit Apply an exact string replacement to a file:
Parameter Type Required Description file_pathstring Yes Virtual file path to edit old_stringstring Yes Exact text to find (must match uniquely) new_stringstring Yes Replacement text (empty string to delete)
grep Search across workspace files using regex:
Parameter Type Required Description patternstring Yes Search pattern (regex supported) file_pathstring No Restrict to a specific file includestring No File extension filter (e.g., .js)
delete Remove a file from the workspace (soft delete):
Parameter Type Required Description file_pathstring Yes Virtual file path to delete
REST API Manage workspaces and files programmatically. All endpoints require API key authentication.
List Workspaces GET /v1/bot/workspace/readall?project_id={project_id}&bot_id={bot_id}
Response: { "workspaces" : [ { "uuid" : "ws_abc123" , "name" : "Default" , "is_default" : 1 , "created_at" : "2026-02-01T12:00:00Z" } ] }
Create Workspace POST /v1/bot/workspace/create
Parameter Type Required Description project_idstring Yes Project ID bot_idstring Yes Bot ID namestring Yes Workspace name descriptionstring No Workspace description
Delete Workspace DELETE /v1/bot/workspace/delete?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}
The default workspace cannot be deleted.
List Files GET /v1/bot/workspace/files?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}
Response: { "files" : [ { "uuid" : "file_xyz" , "file_path" : "/src/app.js" , "language" : "javascript" , "version" : 3 , "created_at" : "2026-02-01T12:00:00Z" } ] }
Read File GET /v1/bot/workspace/file?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}&file_uuid={file_uuid}
Create File POST /v1/bot/workspace/file
Parameter Type Required Description project_idstring Yes Project ID bot_idstring Yes Bot ID workspace_uuidstring Yes Workspace UUID file_pathstring Yes Virtual file path (e.g., /src/app.js) contentstring No File content languagestring No Programming language
Update File PUT /v1/bot/workspace/file
Parameter Type Required Description project_idstring Yes Project ID bot_idstring Yes Bot ID workspace_uuidstring Yes Workspace UUID file_uuidstring Yes File UUID contentstring Yes New file content
Delete File DELETE /v1/bot/workspace/file?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}&file_uuid={file_uuid}
Rename/Move File PUT /v1/bot/workspace/file/rename
Parameter Type Required Description project_idstring Yes Project ID bot_idstring Yes Bot ID workspace_uuidstring Yes Workspace UUID old_pathstring Yes Current file path new_pathstring Yes New file path is_folderboolean No Move all files under path prefix (folder rename)
Next Steps
Chat API Send messages and receive AI responses
API Reference Complete API documentation
