> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Sandbox file system for AI agents

## 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.

> [!NOTE]
>
> 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-conversation — every chat gets its own
isolated workspace, whether the user is authenticated or anonymous.

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 |

> [!NOTE]
>
> 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:**

```json theme={null}
{
  "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}
```

> [!WARNING]
>
> 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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 |

> [!WARNING]
>
> 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}
```

## Next Steps

> [card] [Chat API](/docs/sdk/core/chat-api.md)
>
> Send messages and receive AI responses

> [card] [API Reference](/docs/sdk/core/api-reference.md)
>
> Complete API documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.