Skip to main content

​
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

ParameterTypeDefaultDescription
depthinteger3Maximum 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

FieldTypeDescription
okbooleanWhether the request succeeded
rootobjectRoot tree node
root.typestring"file" or "folder"
root.namestringFile or directory name
root.pathstringPath relative to the workspace root
root.childrenarrayChild nodes (only present for folders)

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token

​
Read a file

GET /api/browse/read
Reads the contents of a single file from the workspace.

​
Query parameters

ParameterTypeRequiredDescription
pathstringyesPath 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

FieldTypeDescription
okbooleanWhether the request succeeded
pathstringRequested file path
contentstringUTF-8 file contents
sizenumberFile size in bytes
modifiedstringISO 8601 last-modified timestamp

​
Errors

CodeDescription
400path query parameter is missing, path traversal was detected, or the path is not a regular file
400File exceeds the 1 MB size limit
401Unauthorized — missing or invalid bearer token
500File 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;"
}
FieldTypeRequiredDescription
pathstringyesDestination path relative to the workspace root
contentstringyesFile content to write (UTF-8)

​
Response

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

​
Response fields

FieldTypeDescription
okbooleanWhether the request succeeded
pathstringWritten file path
sizenumberWritten content size in bytes

​
Errors

CodeDescription
400path or content is missing, or path traversal was detected
401Unauthorized — missing or invalid bearer token
500File 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

FieldTypeDescription
okbooleanWhether the request succeeded
isGitRepobooleanWhether the workspace directory is a git repository
branchstringCurrent branch name
remotestring | nullRemote tracking branch, or null if none
changesarrayList of changed files
changes[].statusstringGit status code (for example M, A, D, ??)
changes[].pathstringFile path relative to the repository root
hasChangesbooleantrue if there are uncommitted changes

​
Errors

CodeDescription
401Unauthorized — 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

ParameterTypeRequiredDescription
pathstringnoFile 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

FieldTypeDescription
okbooleanWhether the request succeeded
unstagedstring | nullUnstaged diff output, or null if there are no unstaged changes
stagedstring | nullStaged diff output, or null if there are no staged changes

​
Errors

CodeDescription
401Unauthorized — 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"
}
FieldTypeRequiredDefaultDescription
messagestringno"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

FieldTypeDescription
okbooleanWhether the request succeeded
committedbooleanWhether a commit was created
pushedbooleanWhether the commit was pushed to the remote
hashstringShort commit hash (empty string if no commit was made)
messagestringCommit message or status explanation

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token
500Workspace 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

ParameterTypeDefaultDescription
limitinteger20Number 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

FieldTypeDescription
okbooleanWhether the request succeeded
commitsarrayList of commits, newest first
commits[].hashstringFull commit SHA
commits[].shortHashstringAbbreviated commit SHA
commits[].subjectstringCommit message subject line
commits[].authorstringAuthor name
commits[].datestringRelative date (for example “2 hours ago”)

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token