> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boostgpt.co/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.

<Info>
  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`.
</Info>

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 |

<Info>
  Tools marked "Conditional" require user approval before execution (configurable per agent). Tools marked "Auto" execute without approval.
</Info>

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

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

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

<CardGroup cols={2}>
  <Card title="Chat API" icon="message-bot" href="/sdk/core/chat-api">
    Send messages and receive AI responses
  </Card>

  <Card title="API Reference" icon="code" href="/sdk/core/api-reference">
    Complete API documentation
  </Card>
</CardGroup>