---
title: File explorer API
description: "Browse, read, and edit agent workspace files and manage git operations from the dashboard"
---

# File explorer API

<Warning>This API is not live on Agentbot. The page is kept as an internal roadmap/spec reference and is intentionally not linked from the main docs navigation.</Warning>

The file explorer lets you view and edit files in an agent's workspace directory without SSH access. It also provides git status, diff, sync, and log operations.

All endpoints require bearer token authentication and are served by the backend API.

## Base URL

```
https://agentbot.sh/api/browse
```

## Get file tree

```http
GET /api/browse/tree
```

Returns a recursive file tree of the workspace directory. Folders are listed before files, both sorted alphabetically. Directories such as `node_modules`, `.git`, `.next`, `dist`, `build`, `.cache`, and `__pycache__` are excluded automatically.

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `depth` | integer | `3` | Maximum recursion depth. Capped at `4`. |

### Response

```json
{
  "ok": true,
  "root": {
    "type": "folder",
    "name": "workspace",
    "path": "/",
    "children": [
      {
        "type": "folder",
        "name": "src",
        "path": "/src",
        "children": [
          {
            "type": "file",
            "name": "index.ts",
            "path": "/src/index.ts"
          }
        ]
      },
      {
        "type": "file",
        "name": "README.md",
        "path": "/README.md"
      }
    ]
  }
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `root` | object | Root tree node |
| `root.type` | string | `"file"` or `"folder"` |
| `root.name` | string | File or directory name |
| `root.path` | string | Path relative to the workspace root |
| `root.children` | array | Child nodes (only present for folders) |

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — missing or invalid bearer token |

## Read a file

```http
GET /api/browse/read
```

Reads the contents of a single file from the workspace.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | yes | Path to the file relative to the workspace root, for example `/SOUL.md` |

### Response

```json
{
  "ok": true,
  "path": "/SOUL.md",
  "content": "# Agent Soul\nPersonality and behavior definitions.",
  "size": 52,
  "modified": "2026-03-22T00:30:00.000Z"
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `path` | string | Requested file path |
| `content` | string | UTF-8 file contents |
| `size` | number | File size in bytes |
| `modified` | string | ISO 8601 last-modified timestamp |

### Errors

| Code | Description |
|------|-------------|
| 400 | `path` query parameter is missing, path traversal was detected, or the path is not a regular file |
| 400 | File exceeds the 1 MB size limit |
| 401 | Unauthorized — missing or invalid bearer token |
| 500 | File could not be read |

## Write a file

```http
POST /api/browse/write
```

Writes or overwrites a file in the workspace. Parent directories are created automatically if they do not exist.

### Request body

```json
{
  "path": "/src/config.ts",
  "content": "export const PORT = 3000;"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | yes | Destination path relative to the workspace root |
| `content` | string | yes | File content to write (UTF-8) |

### Response

```json
{
  "ok": true,
  "path": "/src/config.ts",
  "size": 25
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `path` | string | Written file path |
| `size` | number | Written content size in bytes |

### Errors

| Code | Description |
|------|-------------|
| 400 | `path` or `content` is missing, or path traversal was detected |
| 401 | Unauthorized — missing or invalid bearer token |
| 500 | File could not be written |

## Git status

```http
GET /api/browse/git-status
```

Returns the current git status of the workspace, including branch name, remote tracking info, and a list of changed files.

### Response

```json
{
  "ok": true,
  "isGitRepo": true,
  "branch": "main",
  "remote": "origin/main",
  "changes": [
    {
      "status": "M",
      "path": "src/index.ts"
    },
    {
      "status": "??",
      "path": "new-file.md"
    }
  ],
  "hasChanges": true
}
```

If the workspace is not a git repository, the response returns `isGitRepo: false` with no other git fields.

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `isGitRepo` | boolean | Whether the workspace directory is a git repository |
| `branch` | string | Current branch name |
| `remote` | string \| null | Remote tracking branch, or `null` if none |
| `changes` | array | List of changed files |
| `changes[].status` | string | Git status code (for example `M`, `A`, `D`, `??`) |
| `changes[].path` | string | File path relative to the repository root |
| `hasChanges` | boolean | `true` if there are uncommitted changes |

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — missing or invalid bearer token |

## Git diff

```http
GET /api/browse/git-diff
```

Returns the unstaged and staged diffs for the workspace, or for a specific file.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | no | File path to diff. Omit to get the full workspace diff. |

### Response

```json
{
  "ok": true,
  "unstaged": "diff --git a/src/index.ts b/src/index.ts\n...",
  "staged": null
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `unstaged` | string \| null | Unstaged diff output, or `null` if there are no unstaged changes |
| `staged` | string \| null | Staged diff output, or `null` if there are no staged changes |

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — missing or invalid bearer token |

## Git sync

```http
POST /api/browse/git-sync
```

Stages all changes, commits them with the provided message, and pushes to the remote.

### Request body

```json
{
  "message": "update agent configuration"
}
```

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `message` | string | no | `"sync changes"` | Commit message |

### Response

```json
{
  "ok": true,
  "committed": true,
  "pushed": true,
  "hash": "a1b2c3d",
  "message": "update agent configuration"
}
```

When there are no changes to commit, the response returns `committed: false` and `pushed: false` with a `message` explaining there is nothing to sync.

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `committed` | boolean | Whether a commit was created |
| `pushed` | boolean | Whether the commit was pushed to the remote |
| `hash` | string | Short commit hash (empty string if no commit was made) |
| `message` | string | Commit message or status explanation |

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — missing or invalid bearer token |
| 500 | Workspace is not a git repository, staging failed, or commit failed |

## Git log

```http
GET /api/browse/git-log
```

Returns recent commit history for the workspace.

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | `20` | Number of commits to return. Capped at `100`. |

### Response

```json
{
  "ok": true,
  "commits": [
    {
      "hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "shortHash": "a1b2c3d",
      "subject": "update agent configuration",
      "author": "agentbot",
      "date": "2 hours ago"
    }
  ]
}
```

### Response fields

| Field | Type | Description |
|-------|------|-------------|
| `ok` | boolean | Whether the request succeeded |
| `commits` | array | List of commits, newest first |
| `commits[].hash` | string | Full commit SHA |
| `commits[].shortHash` | string | Abbreviated commit SHA |
| `commits[].subject` | string | Commit message subject line |
| `commits[].author` | string | Author name |
| `commits[].date` | string | Relative date (for example "2 hours ago") |

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — missing or invalid bearer token |
