File explorer API

Browse, read, and edit agent workspace files and manage git operations from the dashboard

File explorer API

The file explorer API is planned for a future release. The endpoints described on this page are not yet available. This page documents the intended specification for reference.

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.raveculture.xyz/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