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

---