Workspaces

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 agent
Anonymous users — each chat conversation gets an isolated workspace

Workspaces can also be published. A published workspace gives generated files or pages a public URL, and eligible plans can attach a custom domain.

Built-in File Tools

When an agent runs in agent reasoning mode, these tools are automatically available:

Tool	Description	Approval
`write`	Create or overwrite a file	Conditional
`read`	Read file content (supports line ranges)	Auto
`edit`	Exact string replacement in a file	Conditional
`grep`	Regex search across workspace files	Auto
`delete`	Soft-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_path`	string	Yes	Virtual file path (e.g., `/src/app.js`)
`content`	string	Yes	Full file content
`language`	string	No	Programming language hint

read

Read a file’s content, optionally by line range:

Parameter	Type	Required	Description
`file_path`	string	Yes	Virtual file path to read
`start_line`	integer	No	Start line (1-based)
`end_line`	integer	No	End line (1-based, inclusive)

edit

Apply an exact string replacement to a file:

Parameter	Type	Required	Description
`file_path`	string	Yes	Virtual file path to edit
`old_string`	string	Yes	Exact text to find (must match uniquely)
`new_string`	string	Yes	Replacement text (empty string to delete)

grep

Search across workspace files using regex:

Parameter	Type	Required	Description
`pattern`	string	Yes	Search pattern (regex supported)
`file_path`	string	No	Restrict to a specific file
`include`	string	No	File extension filter (e.g., `.js`)

delete

Remove a file from the workspace (soft delete):

Parameter	Type	Required	Description
`file_path`	string	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_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`name`	string	Yes	Workspace name
`description`	string	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_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID
`file_path`	string	Yes	Virtual file path (e.g., `/src/app.js`)
`content`	string	No	File content
`language`	string	No	Programming language

Update File

PUT /v1/bot/workspace/file

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID
`file_uuid`	string	Yes	File UUID
`content`	string	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_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID
`old_path`	string	Yes	Current file path
`new_path`	string	Yes	New file path
`is_folder`	boolean	No	Move all files under path prefix (folder rename)

Publishing

Publish a workspace when the agent has created a deliverable that should be shared publicly, such as a page, report, prototype, or client-facing document.

Suggest Subdomain

GET /v1/bot/workspace/suggest-subdomain?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Returns an available workspace subdomain and root domain.

Publish Workspace

PUT /v1/bot/workspace/publish

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID
`subdomain`	string	Yes	Public workspace subdomain

Response:

{
  "published": true,
  "published_url": "https://client-report.boostgpt.co"
}

Unpublish Workspace

PUT /v1/bot/workspace/unpublish

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID

A workspace with an attached custom domain must have the custom domain removed before it can be unpublished.

Custom Domains

Workspace custom domains require a plan that includes custom domains and a published workspace.

Add Custom Domain

POST /v1/bot/workspace/domain/add

Parameter	Type	Required	Description
`project_id`	string	Yes	Project ID
`bot_id`	string	Yes	Bot ID
`workspace_uuid`	string	Yes	Workspace UUID
`custom_domain`	string	Yes	Domain to attach, e.g. `report.example.com`

The response includes the DNS target. The domain starts as pending until verification completes.

Domain Status

GET /v1/bot/workspace/domain/status?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Refreshes and returns the custom domain verification status.

Domain Info

GET /v1/bot/workspace/domain/info?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Returns the workspace subdomain URL, custom domain URL, DNS target, and custom domain status.

Remove Custom Domain

DELETE /v1/bot/workspace/domain/remove?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Getting Started

Choose Your Path

Providers & Models

Overview

Built-in File Tools

write

read

edit

grep

delete

REST API

List Workspaces

Create Workspace

Delete Workspace

List Files

Read File

Create File

Update File

Delete File

Rename/Move File

Publishing

Suggest Subdomain

Publish Workspace

Unpublish Workspace

Custom Domains

Add Custom Domain

Domain Status

Domain Info

Remove Custom Domain

Next Steps

Chat API

API Reference

​Overview

​Built-in File Tools

​write

​read

​edit

​grep

​delete

​REST API

​List Workspaces

​Create Workspace

​Delete Workspace

​List Files

​Read File

​Create File

​Update File

​Delete File

​Rename/Move File

​Publishing

​Suggest Subdomain

​Publish Workspace

​Unpublish Workspace

​Custom Domains

​Add Custom Domain

​Domain Status

​Domain Info

​Remove Custom Domain

​Next Steps

Chat API

API Reference

Overview

Built-in File Tools

write

read

edit

grep

delete

REST API

List Workspaces

Create Workspace

Delete Workspace

List Files

Read File

Create File

Update File

Delete File

Rename/Move File

Publishing

Suggest Subdomain

Publish Workspace

Unpublish Workspace

Custom Domains

Add Custom Domain

Domain Status

Domain Info

Remove Custom Domain

Next Steps