File operations provide a comprehensive set of endpoints for managing files and directories — uploading, modifying, deleting, searching, and inspecting them. Use these endpoints to integrate file management directly into your applications, with support for both local storage and remote cloud backends.

Searching & Discovery

GET /{directory}?q

Search for files matching a query string. Returns HTML by default, or JSON when ?json is supplied. Matches are case-insensitive filename matches.

Parameters

Name	In	Type	Required	Description
directory	path	string	Yes	Directory to search within
q	query	string	Yes	Search query (case-insensitive filename match)
json	query	string	No	Return JSON format instead of HTML

cURL

curl -X GET "https://api.example.com/documents?q=report&json"

SDK

const results = await client.files.search({
  directory: "documents",
  q: "report",
  json: ""
});

200

{
  "allow_archive": true,
  "allow_delete": true,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/documents",
  "kind": "Index",
  "paths": [
    {
      "mtime": 1718400000000,
      "name": "Q2-report.pdf",
      "path_type": "File",
      "revisions": 3,
      "size": 248320
    },
    {
      "mtime": 1718313600000,
      "name": "monthly-reports",
      "path_type": "Dir",
      "revisions": null,
      "size": 12
    }
  ],
  "uri_prefix": "/documents/",
  "user": "user@example.com"
}

403

{
  "error": "Search is not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
SEARCH_FORBIDDEN	Search operation not allowed	Server is not configured to allow file searching	Contact administrator to enable —allow-search flag
INSUFFICIENT_PERMISSIONS	Insufficient permissions	User account does not have search permissions for this path	Contact administrator for search permissions or authenticate with different account

GET /{image}?thumbnail

Process and convert images on the fly. Supports JPEG, PNG, WebP, GIF, and BMP input/output, with resizing, quality control, blur, grayscale, and background color options. Works for both local files and all 60+ remote cloud storage backends.

Parameters

Name	In	Type	Required	Description
image	path	string	Yes	Path to image file
thumbnail	query	string	Yes	Enable image processing
format	query	string	No	Output format (default: jpeg) — one of jpeg, png, webp, gif, bmp
size	query	string	No	Width×Height in pixels (max: 2000×2000)
width	query	integer	No	Width in pixels (height auto-calculated)
height	query	integer	No	Height in pixels (width auto-calculated)
resize	query	string	No	Resize mode: fit (preserve aspect, fit within), fill (exact size, crop), cover (cover area), exact (force dimensions) — default: fit
quality	query	string	No	Resize algorithm quality: low (box filter), medium (bilinear), high (Lanczos3) — default: medium
q	query	integer	No	JPEG/WebP quality (1-100, higher is better quality) — default: 85
blur	query	number	No	Gaussian blur radius (0-50)
grayscale	query	string	No	Convert to grayscale/black-and-white
bg	query	string	No	Background color for transparency (hex RGB, e.g., ffffff for white)

cURL

curl -X GET "https://api.example.com/photos/landscape.png?thumbnail=&width=800&format=webp&q=80" \
  -o landscape-800.webp

SDK

const image = await client.files.images.process({
  image: "photos/landscape.png",
  thumbnail: "",
  format: "webp",
  width: 800,
  q: 80
});

200

{
  "description": "Processed image returned as binary data with Content-Type matching the requested format. Cache-Control: public, max-age=3600"
}

400

{
  "error": "Unsupported image format",
  "success": false
}

GET /api/v1/files/glob/{path}

Find files and directories matching a glob pattern. Supports recursive patterns (**/*.rs), brace expansion ({ts,tsx}), character classes [a-z], and standard wildcards (*). Returns file metadata sorted by modification time (newest first) by default. Respects .gitignore by default.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Directory path to search within
pattern	query	string	Yes	Glob pattern (e.g. **/*.rs, src/**/*.{ts,tsx}, *.md)
max_results	query	integer	No	Maximum entries to return — default: 1000
max_depth	query	integer	No	Maximum directory recursion depth — default: 50
max_files_scanned	query	integer	No	Maximum filesystem entries to scan — default: 100000
timeout	query	integer	No	Search timeout in seconds — default: 30
no_ignore	query	boolean	No	Bypass .gitignore filtering — default: false
sort	query	string	No	Sort results by: mtime (modification time), name, or size — default: mtime
order	query	string	No	Sort order. Default: desc for mtime, asc for name/size — one of asc, desc

cURL

curl -X GET "https://api.example.com/api/v1/files/glob/src?pattern=**/*.ts&max_results=50"

SDK

const results = await client.files.glob({
  path: "src",
  pattern: "**/*.ts",
  max_results: 50
});

200

{
  "count": 2,
  "duration_ms": 47,
  "entries": [
    {
      "is_dir": false,
      "modified": 1718400000,
      "name": "src/index.ts",
      "size": 1842
    },
    {
      "is_dir": false,
      "modified": 1718313600,
      "name": "src/utils/helpers.ts",
      "size": 4096
    }
  ],
  "path": "src",
  "pattern": "**/*.ts",
  "total_scanned": 128,
  "truncated": false
}

400

{
  "error": "Invalid glob pattern",
  "success": false
}

403

{
  "error": "Search is not enabled on this server",
  "success": false
}

404

{
  "error": "Path not found",
  "success": false
}

429

{
  "error": "Too many concurrent searches",
  "success": false
}

GET /api/v1/files/grep/{path}

Search file or directory contents using regex patterns. Powered by ripgrep with .gitignore support, binary file detection, and configurable limits. Returns matching lines with optional context.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path to search
pattern	query	string	Yes	Search pattern (regex by default, literal if fixed_string=true)
ignore_case	query	boolean	No	Case-insensitive matching — default: false
fixed_string	query	boolean	No	Treat pattern as literal string, not regex — default: false
glob	query	string	No	Filter files by glob pattern (e.g. *.rs, *.{ts,tsx})
context	query	integer	No	Number of context lines before and after each match — default: 0
max_count	query	integer	No	Maximum matches per file — default: 50
max_matches	query	integer	No	Total maximum matches across all files — default: 500
max_depth	query	integer	No	Maximum directory recursion depth — default: 50
max_filesize	query	integer	No	Skip files larger than this (bytes) — default: 10485760
timeout	query	integer	No	Search timeout in seconds — default: 30
no_ignore	query	boolean	No	Bypass .gitignore filtering — default: false

cURL

curl -X GET "https://api.example.com/api/v1/files/grep/src?pattern=TODO&context=2&max_count=20"

SDK

const results = await client.files.grep({
  path: "src",
  pattern: "TODO",
  context: 2,
  max_count: 20
});

200

{
  "duration_ms": 124,
  "matches": [
    {
      "column_byte": 4,
      "context_after": ["    return result;"],
      "context_before": ["function calculate() {"],
      "line": "    // TODO: handle edge case",
      "line_number": 42,
      "path": "src/utils/math.ts"
    }
  ],
  "path": "src",
  "pattern": "TODO",
  "total_files_matched": 1,
  "total_files_searched": 84,
  "total_matches": 1,
  "truncated": false
}

400

{
  "error": "Invalid regex pattern",
  "success": false
}

403

{
  "error": "Grep is not enabled on this server",
  "success": false
}

404

{
  "error": "Path not found",
  "success": false
}

429

{
  "error": "Too many concurrent searches",
  "success": false
}

GET /api/v1/files/realpath/{path}

Resolve a file or directory path to its canonical absolute form by following all symbolic links and resolving all ./.. segments. Equivalent to POSIX realpath(3) or Node.js fs.realpath(). The returned real_path is relative to the serve root. Returns 404 if the path does not exist, 400 for circular symlinks (ELOOP), and 403 if the resolved path escapes the serve root.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path to resolve

cURL

curl -X GET "https://api.example.com/api/v1/files/realpath/docs/../README.md"

SDK

const result = await client.files.realpath({
  path: "docs/../README.md"
});

200

{
  "path": "docs/../README.md",
  "real_path": "/README.md"
}

400

{
  "error": "Symlink loop detected",
  "success": false
}

Error Code	Title	Description	Resolution
INVALID_PATH	Invalid path	Path contains invalid characters or traversal attempts	—
ELOOP	Symlink loop	Too many levels of symbolic links (circular chain)	—
OPERATION_CONFLICT	Operation conflict	Cannot combine realpath with other query operations	—

403

{
  "error": "Resolved path is outside serve root",
  "success": false
}

Error Code	Title	Description	Resolution
PERMISSION_DENIED	Permission denied	Insufficient permissions to access the path	—
PATH_ESCAPE	Path escapes root	Resolved canonical path is outside the serve root	—

404

{
  "error": "Path not found",
  "success": false
}

Error Code	Title	Description	Resolution
PATH_NOT_FOUND	Path not found	The path does not exist or contains a broken symlink	Verify the path exists and all symlinks in the chain are valid

GET /api/v1/files/stat/{path}

Get detailed metadata (stat) for a single file or directory without downloading content. Returns name, type, size, modification time, permissions, ownership, and symlink information.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path

cURL

curl -X GET "https://api.example.com/api/v1/files/stat/README.md"

SDK

const metadata = await client.files.stat({
  path: "README.md"
});

200

{
  "group": "staff",
  "is_symlink": false,
  "mtime": 1718400000000,
  "name": "README.md",
  "owner": "user",
  "path": "README.md",
  "path_type": "File",
  "permissions": "644",
  "revisions": 5,
  "size": 4096,
  "symlink_target": null
}

404

{
  "error": "File not found",
  "success": false
}

Error Code	Title	Description	Resolution
FILE_NOT_FOUND	File not found	The specified path does not exist	Verify the path is correct

File Operations

POST /api/v1/files/{path}

Perform various file operations: create directory, extract archive, download from URL, move, or copy. Pass the operation as a query parameter.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Target file or directory path
backend	query	string	No	Backend ID for remote operations
mkdir	query	string	No	Create directory
extract	query	string	No	Extract archive. Empty value extracts all; non-empty value is a selective path to extract (e.g. src/main.rs or lib/)
dest	query	string	No	Destination directory name for extraction (default: archive name without extension)
download_from	query	string	No	Download file from remote URL
move_to	query	string	No	Move file/directory to destination path
copy_to	query	string	No	Copy file/directory to destination path
overwrite	query	string	No	Allow overwriting existing destination (for copy) — one of true, false
owner	query	string	No	Create-time owner for newly-created inodes as user[:group] or uid[:gid]. Requires —allow-chown and must resolve to an entry in —allowed-create-owners; refuses root (uid/gid 0). Absent → the server default create owner. Applies to mkdir/extract/download_from/copy_to.

cURL (mkdir)

curl -X POST "https://api.example.com/api/v1/files/projects/new-app?mkdir="

cURL (extract)

curl -X POST "https://api.example.com/api/v1/files/downloads/release.tar.gz?extract="

cURL (download)

curl -X POST "https://api.example.com/api/v1/files/data.csv?download_from=https://example.com/data.csv"

SDK

// Create a directory
await client.files.operate({
  path: "projects/new-app",
  mkdir: ""
});

// Extract an archive
await client.files.operate({
  path: "downloads/release.tar.gz",
  extract: ""
});

200

{
  "source": "/data/old.csv",
  "destination": "/data/new.csv",
  "success": true
}

201

{
  "message": "Directory created",
  "success": true
}

404

{
  "error": "Source file or directory not found",
  "success": false
}

409

{
  "error": "Destination already exists",
  "success": false
}

POST /api/v1/files/copy/{path}

Copy a file or directory to a new location. Supports recursive directory copy. Auto-creates parent directories at destination. Use ?overwrite=true to replace existing destination.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Source file or directory path
copy_to	query	string	Yes	Destination path to copy the file/directory to
overwrite	query	string	No	Allow overwriting existing destination (default: false) — one of true, false
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for newly-created copies. Requires —allow-chown + allowlist; refuses root. Overwritten existing files preserve their owner. Absent → server default.

cURL

curl -X POST "https://api.example.com/api/v1/files/copy/src/index.ts?copy_to=backup/index.ts"

SDK

const result = await client.files.copy({
  path: "src/index.ts",
  copy_to: "backup/index.ts"
});

200

{
  "destination": "backup/index.ts",
  "source": "src/index.ts",
  "success": true
}

403

{
  "error": "Copy operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
COPY_FORBIDDEN	Copy not allowed	Server requires —allow-upload flag for copy operations	Contact administrator to enable —allow-upload flag

404

{
  "error": "Source file or directory not found",
  "success": false
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	The source path does not exist	Verify the source path is correct

409

{
  "error": "Destination already exists",
  "success": false
}

Error Code	Title	Description	Resolution
DESTINATION_EXISTS	Destination conflict	A file or directory already exists at the destination path	Use ?overwrite=true to replace or choose a different destination

POST /api/v1/files/move/{path}

Move or rename a file/directory to a new location. Works across directories. Auto-creates parent directories at destination. Requires both upload and delete permissions.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Source file or directory path
move_to	query	string	Yes	Destination path to move the file/directory to
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for newly-created destination PARENT directories. Requires —allow-chown + —allowed-create-owners; refuses root. The moved inode itself preserves its existing owner. Absent → server default.

cURL

curl -X POST "https://api.example.com/api/v1/files/move/draft.md?move_to=published/draft.md"

SDK

const result = await client.files.move({
  path: "draft.md",
  move_to: "published/draft.md"
});

200

{
  "destination": "published/draft.md",
  "source": "draft.md",
  "success": true
}

403

{
  "error": "Move operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
MOVE_FORBIDDEN	Move not allowed	Server requires both —allow-upload and —allow-delete flags for move operations	Contact administrator to enable both flags

404

{
  "error": "Source file or directory not found",
  "success": false
}

Error Code	Title	Description	Resolution
SOURCE_NOT_FOUND	Source not found	The source path does not exist	Verify the source path is correct

409

{
  "error": "Destination already exists",
  "success": false
}

Error Code	Title	Description	Resolution
DESTINATION_EXISTS	Destination conflict	A file or directory already exists at the destination path	Delete the existing file first or choose a different destination

Uploading & Appending

PUT /{path}

Upload a file to the server. Creates new files or overwrites existing ones.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Destination file path

Request Body

Sends the file content as application/octet-stream binary data.

cURL

curl -X PUT "https://api.example.com/uploads/report.pdf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @report.pdf

SDK

const result = await client.files.upload({
  path: "uploads/report.pdf",
  body: fileBuffer
});

201

{
  "description": "File uploaded successfully"
}

403

{
  "error": "Upload operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
UPLOAD_FORBIDDEN	Upload operation not allowed	Server is not configured to allow file uploads	Contact administrator to enable —allow-upload flag

PUT /{path}?touch

Create an empty file if it does not exist, or update the modification time if it does. Cannot be used on directories.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File path to touch
touch	query	string	Yes	Flag to indicate touch operation

cURL

curl -X PUT "https://api.example.com/logs/today.txt?touch="

SDK

await client.files.touch({
  path: "logs/today.txt",
  touch: ""
});

201

{
  "description": "File created (did not exist)"
}

204

{
  "description": "Modification time updated (file already existed)"
}

400

{
  "error": "Cannot touch a directory",
  "success": false
}

403

{
  "error": "Touch operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
TOUCH_FORBIDDEN	Touch operation not allowed	Server is not configured to allow touch operations	Contact administrator to enable —allow-touch flag

PUT /api/v1/files/{path}

Upload a file to the server or to a remote backend. Use ?append to append to an existing file instead of overwriting.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Destination file path
backend	query	string	No	Backend ID for remote upload
append	query	string	No	Append body to end of existing file (create if missing) instead of overwriting
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for a newly-created file. Requires —allow-chown + —allowed-create-owners; refuses root. Overwrites/appends to an existing file preserve its owner. Absent → server default.

Request Body

Sends the file content as application/octet-stream binary data.

cURL

curl -X PUT "https://api.example.com/api/v1/files/uploads/data.csv" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv

SDK

const result = await client.files.put({
  path: "uploads/data.csv",
  body: fileBuffer
});

200

{
  "new_size": 8192,
  "path": "logs/server.log",
  "success": true
}

201

{
  "message": "File uploaded successfully",
  "path": "uploads/data.csv",
  "size": 4096,
  "success": true
}

403

{
  "error": "Upload operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
UPLOAD_FORBIDDEN	Upload operation not allowed	Server is not configured to allow file uploads	Contact administrator to enable —allow-upload flag
INSUFFICIENT_PERMISSIONS	Insufficient permissions	User account does not have upload permissions for this path	Contact administrator for write permissions or authenticate with different account

PUT /api/v1/files/append/{path}

Append binary data to the end of an existing file. Creates the file if it does not exist. Auto-creates parent directories.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File path
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) when this append creates a new file. Requires —allow-chown + allowlist; refuses root. Absent → server default.

Request Body

Sends the file content as application/octet-stream binary data.

cURL

curl -X PUT "https://api.example.com/api/v1/files/append/logs/server.log" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "New log line\n"

SDK

const result = await client.files.append({
  path: "logs/server.log",
  body: Buffer.from("New log line\n")
});

200

{
  "new_size": 12288,
  "path": "logs/server.log",
  "success": true
}

403

{
  "error": "Upload operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
UPLOAD_FORBIDDEN	Upload not allowed	Server is not configured to allow file uploads	Contact administrator to enable —allow-upload flag

Modifying Properties

PATCH /{path}

Supports resumable uploads, appending to files, changing file permissions (Unix only), changing file ownership (Unix only), and renaming files or directories.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path
X-Update-Range	header	string	No	Set to append to append data to the end of the file. Perfect for logs and incremental writes. Example: curl -X PATCH -H 'X-Update-Range: append' --data-binary @data.txt http://server/file.log

Request Body

The request body is one of:

• ChmodRequest ({ "mode": "755" }) — change file permissions
• ChownRequest ({ "owner": "user", "group": "users" }) — change file ownership
• RenameRequest ({ "name": "new-filename.txt" }) — rename file or directory
• Binary application/octet-stream — for resumable uploads or appending (use X-Update-Range: append header)

cURL (chmod)

curl -X PATCH "https://api.example.com/script.sh" \
  -H "Content-Type: application/json" \
  -d '{"mode": "755"}'

cURL (rename)

curl -X PATCH "https://api.example.com/old-name.txt" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name.txt"}'

cURL (append)

curl -X PATCH "https://api.example.com/logs/server.log" \
  -H "X-Update-Range: append" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "New log line\n"

SDK

// Change permissions
await client.files.patch({
  path: "script.sh",
  data: { mode: "755" }
});

// Rename
await client.files.patch({
  path: "old-name.txt",
  data: { name: "new-name.txt" }
});

204

{
  "description": "Operation successful"
}

400

{
  "error": "Invalid permissions format",
  "success": false
}

Error Code	Title	Description	Resolution
INVALID_OPERATION	Invalid operation	The requested operation is not valid or parameters are malformed	Check request format and ensure valid operation parameters
INVALID_PERMISSIONS_FORMAT	Invalid permissions format	Chmod mode must be valid octal format (e.g., 755, 644)	Use valid octal permission format

403

{
  "error": "Operation not allowed on this server",
  "success": false
}

Error Code	Title	Description	Resolution
OPERATION_FORBIDDEN	Operation not allowed	Server is not configured to allow this operation (chmod/chown/rename/upload)	Contact administrator to enable appropriate flags
INSUFFICIENT_PERMISSIONS	Insufficient permissions	User account does not have permissions for this operation	Contact administrator for required permissions

409

{
  "error": "A file with the target name already exists",
  "success": false
}

Error Code	Title	Description	Resolution
FILE_EXISTS	File already exists	Cannot rename - a file or directory with the target name already exists	Choose a different name or delete the existing file first
NAME_CONFLICT	Name conflict	The target filename conflicts with an existing entry	Use a unique filename or remove conflicting file

PATCH /api/v1/files/{path}

Modify file properties or move/rename via REST API v1. Supports chmod (?chmod=755), chown (?chown=user:group), rename (JSON body with name), and cross-directory move (JSON body with move_to).

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File path
backend	query	string	No	Backend ID for remote file operations
chmod	query	string	No	Set file permissions using octal mode value (e.g., ?chmod=755)
chown	query	string	No	Set file ownership (e.g., ?chown=user:group or ?chown=user)
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for newly-created destination parent directories on a JSON-body move_to. Requires —allow-chown + —allowed-create-owners; cannot be root. The moved item keeps its own owner. Absent → server default.

Request Body

The request body is one of:

• MoveRequest ({ "move_to": "/new/dir/file.txt" }) — move file to a new path
• RenameRequest ({ "name": "new-filename.txt" }) — rename file in place

cURL (chmod)

curl -X PATCH "https://api.example.com/api/v1/files/script.sh?chmod=755"

cURL (chown)

curl -X PATCH "https://api.example.com/api/v1/files/script.sh?chown=user:staff"

cURL (move)

curl -X PATCH "https://api.example.com/api/v1/files/old/path.txt" \
  -H "Content-Type: application/json" \
  -d '{"move_to": "/new/dir/path.txt"}'

SDK

// Change permissions via query
await client.files.patchApi({
  path: "script.sh",
  chmod: "755"
});

// Move via body
await client.files.patchApi({
  path: "old/path.txt",
  data: { move_to: "/new/dir/path.txt" }
});

200

{
  "mode": "755",
  "path": "script.sh",
  "success": true
}

400

{
  "error": "Invalid chmod mode",
  "success": false
}

Error Code	Title	Description	Resolution
INVALID_MODE	Invalid chmod mode	The chmod mode value is not valid octal notation	Use octal notation like 755 or 644 (max 7777)
INVALID_OWNER	Invalid owner or group	The specified user or group could not be resolved	Verify the username/group exists on the system

403

{
  "error": "chmod not allowed on this server",
  "success": false
}

Error Code	Title	Description	Resolution
CHMOD_FORBIDDEN	Chmod not allowed	Server is not configured to allow chmod operations	Contact administrator to enable —allow-chmod flag
CHOWN_FORBIDDEN	Chown not allowed	Server is not configured to allow chown operations	Contact administrator to enable —allow-chown flag

404

{
  "error": "File or directory not found",
  "success": false
}

409

{
  "error": "Destination already exists",
  "success": false
}

PATCH /api/v1/files/chmod/{path}

Change file or directory permissions using octal mode (Unix only). Pass the mode value in the chmod query parameter, e.g., ?chmod=755.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path
chmod	query	string	Yes	Octal permission mode (e.g., 755, 644, 0755)

cURL

curl -X PATCH "https://api.example.com/api/v1/files/chmod/script.sh?chmod=755"

SDK

const result = await client.files.chmod({
  path: "script.sh",
  chmod: "755"
});

200

{
  "mode": "755",
  "path": "script.sh",
  "success": true
}

400

{
  "error": "Invalid chmod mode",
  "success": false
}

Error Code	Title	Description	Resolution
INVALID_MODE	Invalid chmod mode	The mode value is not valid octal notation	Use octal notation like 755 or 644 (max 7777)
UNIX_ONLY	Unix only	chmod is only supported on Unix systems	Use a Unix-based server

403

{
  "error": "chmod not allowed on this server",
  "success": false
}

Error Code	Title	Description	Resolution
CHMOD_FORBIDDEN	Chmod not allowed	Server is not configured to allow chmod operations	Contact administrator to enable —allow-chmod flag

404

{
  "error": "File or directory not found",
  "success": false
}

PATCH /api/v1/files/chown/{path}

Change file or directory ownership (Unix only). Pass owner:group in the chown query parameter, e.g., ?chown=user:group. Group is optional.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	File or directory path
chown	query	string	Yes	Owner and optional group (e.g., user:group, user, :group, or UID:GID)

cURL

curl -X PATCH "https://api.example.com/api/v1/files/chown/data.csv?chown=app:staff"

SDK

const result = await client.files.chown({
  path: "data.csv",
  chown: "app:staff"
});

200

{
  "group": "staff",
  "owner": "app",
  "path": "data.csv",
  "success": true
}

400

{
  "error": "Invalid owner or group",
  "success": false
}

Error Code	Title	Description	Resolution
INVALID_OWNER	Invalid owner	The specified user could not be resolved	Verify the username or UID exists on the system
INVALID_GROUP	Invalid group	The specified group could not be resolved	Verify the group name or GID exists on the system
UNIX_ONLY	Unix only	chown is only supported on Unix systems	Use a Unix-based server

403

{
  "error": "chown not allowed on this server",
  "success": false
}

Error Code	Title	Description	Resolution
CHOWN_FORBIDDEN	Chown not allowed	Server is not configured to allow chown operations	Contact administrator to enable —allow-chown flag

404

{
  "error": "File or directory not found",
  "success": false
}

Deletion

DELETE /{path}

Permanently delete a file or directory. Recursive — deleting a directory removes its contents.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path to file or directory to delete

cURL

curl -X DELETE "https://api.example.com/old/draft.txt"

SDK

const result = await client.files.deleteRecursive({
  path: "old/draft.txt"
});

200

{
  "message": "File deleted successfully",
  "success": true
}

403

{
  "error": "Delete operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
DELETE_FORBIDDEN	Delete operation not allowed	Server is not configured to allow file deletion	Contact administrator to enable —allow-delete flag

404

{
  "error": "File or directory not found",
  "success": false
}

DELETE /api/v1/files/{path}

Delete a file or directory from the server or a remote backend. Supports a backend query parameter to target a specific cloud storage backend.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Path to file or directory to delete
backend	query	string	No	Backend ID for remote file deletion

cURL

curl -X DELETE "https://api.example.com/api/v1/files/old/draft.txt"

SDK

const result = await client.files.delete({
  path: "old/draft.txt"
});

200

{
  "message": "File deleted successfully",
  "success": true
}

403

{
  "error": "Delete operations are not enabled on this server",
  "success": false
}

Error Code	Title	Description	Resolution
DELETE_FORBIDDEN	Delete operation not allowed	Server is not configured to allow file deletion	Contact administrator to enable —allow-delete flag
INSUFFICIENT_PERMISSIONS	Insufficient permissions	User account does not have delete permissions for this path	Contact administrator for write permissions

404

{
  "error": "File or directory not found",
  "success": false
}

Error Code	Title	Description	Resolution
FILE_NOT_FOUND	File or directory not found	The specified path does not exist in storage or backend	Verify the path is correct and the file exists