File explorer API

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.

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

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

{
  "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

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

{
  "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

POST /api/browse/write

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

Request body

{
  "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

{
  "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

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

{
  "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

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

{
  "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

POST /api/browse/git-sync

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

Request body

{
  "message": "update agent configuration"
}

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

Response

{
  "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

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

{
  "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

​File explorer API

​Base URL

​Get file tree

​Query parameters

​Response

​Response fields

​Errors

​Read a file

​Query parameters

​Response

​Response fields

​Errors

​Write a file

​Request body

​Response

​Response fields

​Errors

​Git status

​Response

​Response fields

​Errors

​Git diff

​Query parameters

​Response

​Response fields

​Errors

​Git sync

​Request body

​Response

​Response fields

​Errors

​Git log

​Query parameters

​Response

​Response fields

​Errors

File explorer API

Base URL

Get file tree

Query parameters

Response

Response fields

Errors

Read a file

Query parameters

Response

Response fields

Errors

Write a file

Request body

Response

Response fields

Errors

Git status

Response

Response fields

Errors

Git diff

Query parameters

Response

Response fields

Errors

Git sync

Request body

Response

Response fields

Errors

Git log

Query parameters

Response

Response fields

Errors