File Operations

The File Operations API provides endpoints for searching, processing, uploading, modifying, and deleting files. Use these endpoints to interact with the file system programmatically — including glob and regex content search, on-the-fly image processing, resumable uploads, permission/ownership changes, and recursive delete operations.

Search & Discovery

`GET /{directory}?q`

Search a directory for files whose names match a query. Returns HTML by default; pass ?json to receive JSON instead.

Parameters

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

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

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

{
  "allow_archive": true,
  "allow_delete": true,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/documents/",
  "kind": "Index",
  "paths": [
    {
      "name": "annual-report.pdf",
      "path_type": "File",
      "size": 245678,
      "mtime": 1714000000000,
      "revisions": 3
    },
    {
      "name": "monthly",
      "path_type": "Dir",
      "size": 12,
      "mtime": 1714100000000,
      "revisions": null
    }
  ],
  "uri_prefix": "",
  "user": "analyst"
}

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

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`

On-the-fly image processing with format conversion, resizing, and effects. Supports JPEG, PNG, WebP, GIF, BMP input/output. 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. Allowed values: `jpeg`, `png`, `webp`, `gif`, `bmp`. Default: `"jpeg"`
`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	Yes	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 -X GET "https://api.hoody.com/images/hero.jpg?thumbnail=&format=webp&width=800&quality=high"

await client.files.images.process({
  image: "images/hero.jpg",
  thumbnail: "",
  format: "webp",
  width: 800,
  quality: "high"
});

Returns the processed image binary in the requested format. The response includes Content-Type and Cache-Control: public, max-age=3600 headers.

{
  "success": false,
  "error": "Invalid image or unsupported format"
}

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

Find files and directories matching a glob pattern. Supports recursive patterns (**/*.rs), brace expansion ({ts,tsx}), character classes, and standard wildcards. Results are sorted by modification time (newest first) by default and respect .gitignore.

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. Allowed values: `asc`, `desc`

curl -X GET "https://api.hoody.com/api/v1/files/glob/src?pattern=**/*.rs&max_results=50&sort=mtime"

await client.files.glob({
  path: "src",
  pattern: "**/*.rs",
  max_results: 50,
  sort: "mtime"
});

{
  "count": 3,
  "duration_ms": 42,
  "entries": [
    {
      "name": "src/main.rs",
      "is_dir": false,
      "size": 1842,
      "modified": 1714520000
    },
    {
      "name": "src/lib.rs",
      "is_dir": false,
      "size": 932,
      "modified": 1714510000
    },
    {
      "name": "src/utils",
      "is_dir": true,
      "size": 0,
      "modified": 1714490000
    }
  ],
  "path": "src",
  "pattern": "**/*.rs",
  "total_scanned": 120,
  "truncated": false
}

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

{
  "success": false,
  "error": "Glob search is not allowed"
}

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

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

`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 -X GET "https://api.hoody.com/api/v1/files/grep/src?pattern=TODO&ignore_case=true&context=2"

await client.files.grep({
  path: "src",
  pattern: "TODO",
  ignore_case: true,
  context: 2
});

{
  "duration_ms": 18,
  "matches": [
    {
      "path": "src/main.rs",
      "line_number": 42,
      "column_byte": 4,
      "line": "    // TODO: implement retry logic",
      "context_before": [
        "    let client = build_client();"
      ],
      "context_after": [
        "    let backoff = Duration::from_millis(100);"
      ]
    }
  ],
  "path": "src",
  "pattern": "TODO",
  "total_files_matched": 1,
  "total_files_searched": 24,
  "total_matches": 1,
  "truncated": false
}

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

{
  "success": false,
  "error": "Grep search is not allowed"
}

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

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

`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. The returned real_path is relative to the serve root.

Parameters

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

curl -X GET "https://api.hoody.com/api/v1/files/realpath/src/./utils/../lib.rs"

await client.files.realpath({
  path: "src/./utils/../lib.rs"
});

{
  "path": "src/./utils/../lib.rs",
  "real_path": "src/lib.rs"
}

{
  "success": false,
  "error": "Invalid path or symlink loop"
}

Error Code	Title	Description	Resolution
`INVALID_PATH`	Invalid path	Path contains invalid characters or traversal attempts	Provide a valid path without invalid characters
`ELOOP`	Symlink loop	Too many levels of symbolic links (circular chain)	Break the symlink cycle or reduce indirection
`OPERATION_CONFLICT`	Operation conflict	Cannot combine realpath with other query operations	Use the realpath endpoint on its own

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

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	Permission denied	Insufficient permissions to access the path	Authenticate with appropriate credentials
`PATH_ESCAPE`	Path escapes root	Resolved canonical path is outside the serve root	Use a path within the serve root
`SEARCH_FORBIDDEN`	Search operation not allowed	Server is not configured to allow file searching	Contact administrator to enable —allow-search flag

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

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 -X GET "https://api.hoody.com/api/v1/files/stat/src/main.rs"

await client.files.stat({
  path: "src/main.rs"
});

{
  "name": "main.rs",
  "path": "src/main.rs",
  "path_type": "File",
  "size": 1842,
  "mtime": 1714520000000,
  "permissions": "644",
  "owner": "alice",
  "group": "developers",
  "is_symlink": false,
  "symlink_target": null,
  "revisions": 4
}

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

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

File Operations (mkdir, extract, download, move, copy)

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

Perform various file operations: create directory (?mkdir=), extract archive (?extract=), download from URL (?download_from=), move (?move_to=), or copy (?copy_to=).

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	Target path for the operation
`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). Allowed values: `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.

# Make a directory
curl -X POST "https://api.hoody.com/api/v1/files/projects/new-app?mkdir="

# Download from URL
curl -X POST "https://api.hoody.com/api/v1/files/installer.bin?download_from=https://example.com/installer.bin"

# Move
curl -X POST "https://api.hoody.com/api/v1/files/draft/notes.md?move_to=published/notes.md"

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

// Download from URL
await client.files.operate({
  path: "installer.bin",
  download_from: "https://example.com/installer.bin"
});

// Move
await client.files.operate({
  path: "draft/notes.md",
  move_to: "published/notes.md"
});

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

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

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

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

{
  "success": false,
  "error": "Server error: could not set ownership of newly-created inode"
}

`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 an 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`). Allowed values: `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 -X POST "https://api.hoody.com/api/v1/files/copy/src/lib.rs?copy_to=backup/lib.rs"

await client.files.copy({
  path: "src/lib.rs",
  copy_to: "backup/lib.rs"
});

{
  "source": "src/lib.rs",
  "destination": "backup/lib.rs",
  "success": true
}

{
  "success": false,
  "error": "Copy operations are not allowed"
}

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

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

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

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

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 or 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 -X POST "https://api.hoody.com/api/v1/files/move/draft/notes.md?move_to=published/notes.md"

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

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

{
  "success": false,
  "error": "Move operations are not allowed"
}

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

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

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

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

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

Upload

`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

Binary body sent as application/octet-stream containing the file contents.

curl -X PUT "https://api.hoody.com/uploads/photo.jpg" \
  --data-binary @./photo.jpg \
  -H "Content-Type: application/octet-stream"

await client.files.upload({
  path: "uploads/photo.jpg"
}, fs.readFileSync("./photo.jpg"));

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

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 -X PUT "https://api.hoody.com/logs/today.log?touch="

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

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

{
  "success": false,
  "error": "Touch operations are not allowed"
}

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
`UPLOAD_FORBIDDEN`	Upload operation not allowed	Server is not configured to allow file uploads	Contact administrator to enable —allow-upload 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

Binary body sent as application/octet-stream containing the file contents.

# Upload
curl -X PUT "https://api.hoody.com/api/v1/files/uploads/photo.jpg" \
  --data-binary @./photo.jpg \
  -H "Content-Type: application/octet-stream"

# Append
curl -X PUT "https://api.hoody.com/api/v1/files/logs/today.log?append=" \
  --data-binary @./newline.log \
  -H "Content-Type: application/octet-stream"

// Upload
await client.files.put({
  path: "uploads/photo.jpg"
}, fs.readFileSync("./photo.jpg"));

// Append
await client.files.put({
  path: "logs/today.log",
  append: ""
}, fs.readFileSync("./newline.log"));

{
  "path": "logs/today.log",
  "new_size": 2048,
  "success": true
}

{
  "success": true,
  "message": "File uploaded successfully",
  "path": "uploads/photo.jpg",
  "size": 245678
}

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

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

Binary body sent as application/octet-stream containing the data to append.

curl -X PUT "https://api.hoody.com/api/v1/files/append/logs/today.log" \
  --data-binary @./newline.log \
  -H "Content-Type: application/octet-stream"

await client.files.append({
  path: "logs/today.log"
}, fs.readFileSync("./newline.log"));

{
  "path": "logs/today.log",
  "new_size": 2048,
  "success": true
}

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

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

Patch

`PATCH /{path}`

File operations: resumable upload, append to files (via X-Update-Range: append header), change file permissions (Unix only), change file ownership (Unix only), or rename file/directory.

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. Example: `curl -X PATCH -H 'X-Update-Range: append' --data-binary @data.txt http://server/file.log`

Request Body

For permission/ownership changes or rename, send JSON: {"mode": "755"}, {"owner": "user", "group": "users"}, or {"name": "new-filename.txt"}. For append, send binary data with the X-Update-Range: append header.

# Chmod
curl -X PATCH "https://api.hoody.com/scripts/run.sh" \
  -H "Content-Type: application/json" \
  -d '{"mode":"755"}'

# Chown
curl -X PATCH "https://api.hoody.com/data/records.csv" \
  -H "Content-Type: application/json" \
  -d '{"owner":"alice","group":"analysts"}'

# Rename
curl -X PATCH "https://api.hoody.com/draft/notes.md" \
  -H "Content-Type: application/json" \
  -d '{"name":"final-notes.md"}'

# Append
curl -X PATCH "https://api.hoody.com/logs/app.log" \
  -H "X-Update-Range: append" \
  --data-binary @./more.log

// Chmod
await client.files.patch({
  path: "scripts/run.sh"
}, { mode: "755" });

// Rename
await client.files.patch({
  path: "draft/notes.md"
}, { name: "final-notes.md" });

{
  "success": false,
  "error": "Invalid operation or parameters"
}

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

{
  "success": false,
  "error": "Operation is not allowed"
}

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

{
  "success": false,
  "error": "File or directory already exists"
}

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}`

REST API v1 modification endpoint. Supports ?chmod=755, ?chown=user:group, rename via JSON body, and cross-directory move via JSON body.

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	File path
`backend`	query	string	No	Backend ID for remote file operations
`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.
`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`)

Request Body

JSON body matching one of: MoveRequest ({ "move_to": "/new/dir/file.txt" }) or RenameRequest ({ "name": "new-filename.txt" }).

# Chmod via query
curl -X PATCH "https://api.hoody.com/api/v1/files/scripts/run.sh?chmod=755"

# Chown via query
curl -X PATCH "https://api.hoody.com/api/v1/files/scripts/run.sh?chown=alice:developers"

# Move via body
curl -X PATCH "https://api.hoody.com/api/v1/files/draft/notes.md" \
  -H "Content-Type: application/json" \
  -d '{"move_to": "/published/notes.md"}'

// Chmod
await client.files.patchApi({
  path: "scripts/run.sh",
  chmod: "755"
});

// Move via body
await client.files.patchApi({
  path: "draft/notes.md"
}, { move_to: "/published/notes.md" });

{
  "mode": "755",
  "path": "scripts/run.sh",
  "success": true
}

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

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
`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

{
  "success": false,
  "error": "Operation is not allowed"
}

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
`OPERATION_FORBIDDEN`	Operation not allowed	Server is not configured to allow this operation (chmod/chown/rename/upload)	Contact administrator to enable appropriate flags

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

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

`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 -X PATCH "https://api.hoody.com/api/v1/files/chmod/scripts/run.sh?chmod=755"

await client.files.chmod({
  path: "scripts/run.sh",
  chmod: "755"
});

{
  "mode": "755",
  "path": "scripts/run.sh",
  "success": true
}

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

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
`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

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

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
`OPERATION_FORBIDDEN`	Operation not allowed	Server is not configured to allow this operation (chmod/chown/rename/upload)	Contact administrator to enable appropriate flags

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

`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 -X PATCH "https://api.hoody.com/api/v1/files/chown/data/records.csv?chown=alice:analysts"

await client.files.chown({
  path: "data/records.csv",
  chown: "alice:analysts"
});

{
  "owner": "alice",
  "group": "analysts",
  "path": "data/records.csv",
  "success": true
}

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

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
`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

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

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
`OPERATION_FORBIDDEN`	Operation not allowed	Server is not configured to allow this operation (chmod/chown/rename/upload)	Contact administrator to enable appropriate flags

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

Delete

`DELETE /{path}`

Permanently delete a file or directory.

Parameters

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

curl -X DELETE "https://api.hoody.com/temp/junk.txt"

await client.files.deleteRecursive({
  path: "temp/junk.txt"
});

{
  "success": true,
  "message": "Deleted successfully"
}

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

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

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

`DELETE /api/v1/files/{path}`

Delete a file or directory from the server or a remote 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 -X DELETE "https://api.hoody.com/api/v1/files/temp/junk.txt"

await client.files.delete({
  path: "temp/junk.txt"
});

{
  "success": true,
  "message": "Deleted successfully"
}

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

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

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

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