Base URL http://localhost:3333/api/ · Authentication · Conventions

FileSystem Routes

Base path: /api/filesystem

Provides a sandboxed file system for the built-in code editor. All file paths are relative to the configured workspace root. Path traversal outside the workspace is blocked (403).

Get Settings

GET /settings

Authentication: Required
Description: Returns the current workspace root directory and default root
Response:

{
  "workspaceRoot": "/home/user/.agnt/data/projects",
  "defaultRoot": "/home/user/.agnt/data/projects"
}

Update Settings

PUT /settings

Authentication: Required
Description: Update the workspace root directory
Body:

{
  "workspaceRoot": "/path/to/new/workspace"
}

Response:

{
  "success": true,
  "workspaceRoot": "/path/to/new/workspace"
}

Get Directory Tree

GET /tree?dir=<relPath>

Authentication: Required
Parameters:
- dir (query, optional): Relative path within workspace (default: root)
Description: Returns directory listing for the given relative path. Hidden files (dot-prefixed) are excluded. Directories are listed first.
Response:

{
  "items": [
    { "name": "src", "type": "directory", "path": "src" },
    { "name": "index.js", "type": "file", "path": "index.js" }
  ],
  "root": "/"
}

Read File

GET /file?path=<relPath>

Authentication: Required
Parameters:
- path (query, required): Relative file path within workspace
Description: Returns the content of a file as UTF-8 text
Response:

{
  "content": "file contents here...",
  "path": "src/index.js"
}

Error (404): File not found

Write File

POST /file

Authentication: Required
Description: Create or overwrite a file. Parent directories are created automatically.
Body:

{
  "path": "src/index.js",
  "content": "console.log('hello');"
}

Response:

{
  "success": true,
  "path": "src/index.js"
}

Create Directory

POST /mkdir

Authentication: Required
Description: Create a directory (recursive)
Body:

{
  "path": "src/components"
}

Response:

{
  "success": true,
  "path": "src/components"
}

Rename / Move

POST /rename

Authentication: Required
Description: Rename or move a file or directory
Body:

{
  "oldPath": "src/old-name.js",
  "newPath": "src/new-name.js"
}

Response:

{
  "success": true,
  "oldPath": "src/old-name.js",
  "newPath": "src/new-name.js"
}

Delete File or Directory

DELETE /file?path=<relPath>

Authentication: Required
Parameters:
- path (query, required): Relative path within workspace
Description: Delete a file or directory (recursive for directories)
Response:

{
  "success": true,
  "path": "src/old-file.js"
}

Error (404): File not found

Search Files

GET /search

Authentication: Required
Description: Recursively searches file/directory names under dir (default: workspace root). Case-insensitive substring match on the name. Returns a truncated flag when the result cap or entry-scan cap is hit (safety valve for pathological workspaces).
Parameters:
- q (query, required): search substring
- dir (query, optional): subdirectory relative to workspace root
Response:

{
  "items": [],
  "truncated": false
}

Serve Raw File

GET /raw

Authentication: Required
Description: Serves a workspace file with its native content type (images, videos, etc.) via streaming. Path traversal outside the workspace root is rejected with 403.
Parameters:
- path (query, required): file path relative to workspace root
Response: File bytes with the detected Content-Type; 400 if path is missing

Upload Files

POST /upload

Authentication: Required
Content-Type: multipart/form-data
Description: OS drag-and-drop uploads. Files land inside dir (relative to workspace root; empty string = root). Name collisions get a " (n)" suffix before the extension.
Body:
- dir (string, optional): target directory relative to workspace root
- files (file[]): one or more files
Response: List of stored files. 400 if no files are uploaded or dir resolves to a file instead of a directory

FileSystem