The File Operations endpoints manage the lifecycle of files in your containers: searching, uploading, modifying, copying, moving, and deleting. Use these endpoints when you need to write or restructure files, run targeted searches, or apply POSIX-style permission changes. Image processing and bulk file operations are exposed alongside standard CRUD.

All operations run against the per-container file service hostname. Substitute projectId, containerId, and server with your container’s values.

Search & Discovery

GET /{directory}?q

Search a directory for filenames matching a query. Results are returned as HTML by default; pass ?json= to receive JSON.

Parameters

Name	In	Type	Required	Description
directory	path	string	Yes	Directory path to search.
q	query	string	Yes	Search query (case-insensitive filename match). Maximum 512 BYTES of UTF-8 after form/percent decoding, measured both before and after Unicode lowercasing — lowercasing can change a string’s byte length in either direction. Longer queries are rejected with 400; they are not truncated. Note this is a byte limit, not a character limit, so it is deliberately not expressed as maxLength.
json	query	string	No	Return JSON format instead of HTML. Literal value must be an empty string ("").

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/data/projects?q=config&json="

SDK

await client.files.search('/data/projects', { q: 'config', json: '' });

200

{
  "auth": true,
  "allow_search": true,
  "allow_upload": true,
  "allow_delete": true,
  "allow_archive": true,
  "kind": "Index",
  "dir_exists": true,
  "href": "/data/projects/",
  "uri_prefix": "/",
  "user": "alice",
  "paths": [
    {
      "name": "config.json",
      "size": 1024,
      "mtime": 1717000000000,
      "path_type": "File",
      "revisions": 3
    },
    {
      "name": "src",
      "size": 12,
      "mtime": 1717050000000,
      "path_type": "Dir",
      "revisions": null
    }
  ]
}

400

Query q exceeds 512 bytes of UTF-8, measured both before and after Unicode lowercasing. The query is rejected, not truncated.

{
  "success": false,
  "error": "Search query exceeds maximum length of 512 UTF-8 bytes"
}

Error Code	Title	Description	Resolution
SEARCH_QUERY_TOO_LONG	Search query too long	q is limited to 512 UTF-8 bytes. Note this is a BYTE limit, not a character limit, and it is applied to the percent-decoded value both as received and after lowercasing — case folding can change a string’s byte length in either direction.	Shorten the query. Non-ASCII characters consume 2-4 bytes each.

403

Search not allowed.

{
  "success": false,
  "error": "Search operation is not allowed"
}

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 a different account.

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

Find files and directories matching a glob pattern within a directory. Supports recursive patterns (**/*.rs), brace expansion ({ts,tsx}), character classes ([a-z]), 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. Allowed values: asc, desc. Default: desc for mtime, asc for name/size.

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/glob/workspace/src?pattern=**/*.rs&max_results=200"

SDK

await client.files.glob('/workspace/src', { pattern: '**/*.rs', max_results: 200 });

200

{
  "pattern": "**/*.rs",
  "path": "/workspace/src",
  "count": 2,
  "total_scanned": 312,
  "truncated": false,
  "duration_ms": 18,
  "entries": [
    {
      "name": "src/main.rs",
      "is_dir": false,
      "size": 4096,
      "modified": 1717061234
    },
    {
      "name": "src/lib",
      "is_dir": true,
      "size": 0,
      "modified": 1717050000
    }
  ]
}

400

Invalid pattern or parameters.

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

403

Search not allowed.

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

404

Path not found.

{
  "success": false,
  "error": "Path not found: /workspace/missing"
}

429

Too many concurrent searches.

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

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 (10 MB).
timeout	query	integer	No	Search timeout in seconds. Default: 30.
no_ignore	query	boolean	No	Bypass .gitignore filtering. Default: false.

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/grep/workspace?pattern=TODO&max_count=20"

SDK

await client.files.grep('/workspace', { pattern: 'TODO', max_count: 20 });

200

{
  "pattern": "TODO",
  "path": "/workspace",
  "total_matches": 1,
  "total_files_matched": 1,
  "total_files_searched": 142,
  "truncated": false,
  "duration_ms": 27,
  "matches": [
    {
      "path": "/workspace/src/main.rs",
      "line_number": 42,
      "column_byte": 5,
      "line": "    // TODO: implement retry logic",
      "context_before": [],
      "context_after": []
    }
  ]
}

400

Invalid pattern or parameters.

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

403

Grep not allowed.

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

404

Path not found.

{
  "success": false,
  "error": "Path not found: /workspace/missing"
}

429

Too many concurrent searches.

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

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.

Parameters

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

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/realpath/data/projects/legacy/../current/script.sh"

SDK

await client.files.realpath('/data/projects/legacy/../current/script.sh');

200

{
  "path": "/data/projects/legacy/../current/script.sh",
  "real_path": "/data/projects/current/script.sh"
}

400

Invalid path or symlink loop.

{
  "success": false,
  "error": "Too many levels of symbolic links"
}

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

Permission denied or resolved path escapes serve root.

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

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

Path not found or dangling symlink.

{
  "success": false,
  "error": "Path not found: /data/missing"
}

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.

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/stat/data/file.txt"

SDK

await client.files.stat('/data/file.txt');

200

{
  "name": "file.txt",
  "path": "/data/file.txt",
  "path_type": "File",
  "size": 2048,
  "mtime": 1717000000000,
  "permissions": "644",
  "owner": "alice",
  "group": "staff",
  "is_symlink": false,
  "symlink_target": null,
  "revisions": 5
}

404

File or directory not found.

{
  "success": false,
  "error": "Path not found: /data/file.txt"
}

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

Image Processing

GET /{image}?thumbnail

Process and convert images on-the-fly with format conversion, resizing, and effects. Supports JPEG, PNG, WebP, GIF, and BMP input and 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. Literal value must be an empty string ("").
format	query	string	No	Output format. Allowed values: jpeg, png, webp, gif, bmp. Default: "jpeg".
size	query	string	No	Width by Height in pixels (max: 2000 by 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. Allowed values: fit (preserve aspect, fit within), fill (exact size, crop), cover (cover area), exact (force dimensions). Default: "fit".
quality	query	string	No	Resize algorithm quality. Allowed values: 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. Literal value must be an empty string ("").
bg	query	string	No	Background color for transparency (hex RGB, e.g. ffffff for white).

This endpoint takes no request body.

cURL

curl -X GET "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/photos/cover.jpg?thumbnail=&format=webp&size=800x600&q=80"

SDK

await client.files.images.process('/photos/cover.jpg', { thumbnail: '', format: 'webp', size: '800x600', q: 80 });

200

Processed image in the requested format is returned as binary. The Content-Type response header is set to one of image/jpeg, image/png, image/webp, image/gif, or image/bmp. The Cache-Control header is set to public, max-age=3600.

400

Invalid image or unsupported format.

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

File Operations

POST /api/v1/files/{path}

Perform various file operations through a single endpoint. Pass one of the following query flags to select the operation: mkdir, extract, download_from, move_to, or copy_to.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Target path.
backend	query	string	No	Backend ID for remote storage operations.
mkdir	query	string	No	Create directory. Literal value must be an empty string ("").
extract	query	string	No	Extract archive. Empty value extracts all; non-empty value is a selective path to extract (e.g. src/ 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 means the server default create owner. Applies to mkdir, extract, download_from, and copy_to.

This endpoint takes no request body.

cURL

curl -X POST "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/data/new-folder?mkdir="

SDK

await client.files.operate('/data/new-folder', { mkdir: '' });

200

Move or copy operation successful.

{
  "source": "/data/file.txt",
  "destination": "/data/backup/file.txt",
  "success": true
}

201

Directory created or extraction/download successful.

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

404

Source file or directory not found.

{
  "success": false,
  "error": "Source not found: /data/missing"
}

409

Destination already exists.

{
  "success": false,
  "error": "Destination already exists: /data/backup"
}

500

Server error. Includes create-owner enforcement failure: when the default create-owner feature is active and the service cannot set ownership of a newly-created inode, the request fails closed (the partially-created file/dir is rolled back) rather than leaving it owned by root.

{
  "success": false,
  "error": "Internal server error"
}

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

Copy a file or directory to a new location. Supports recursive directory copy. Auto-creates parent directories at the 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. Allowed values: true, false. Default: false.
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for newly-created copies. Requires --allow-chown and allowlist; refuses root. Overwritten existing files preserve their owner. Absent means server default.

This endpoint takes no request body.

cURL

curl -X POST "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/copy/src/notes.txt?copy_to=/dst/notes.txt"

SDK

await client.files.copy('/src/notes.txt', { copy_to: '/dst/notes.txt' });

200

File copied successfully.

{
  "source": "/src/notes.txt",
  "destination": "/dst/notes.txt",
  "success": true
}

403

Copy not allowed (requires upload permission).

{
  "success": false,
  "error": "Copy 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.

404

Source file or directory not found.

{
  "success": false,
  "error": "Source not found: /src/notes.txt"
}

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

409

Destination already exists (use ?overwrite=true to replace).

{
  "success": false,
  "error": "Destination already exists: /dst/notes.txt"
}

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 the 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 and --allowed-create-owners; refuses root. The moved inode itself preserves its existing owner. Absent means server default.

This endpoint takes no request body.

cURL

curl -X POST "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/move/src/notes.txt?move_to=/archive/notes.txt"

SDK

await client.files.move('/src/notes.txt', { move_to: '/archive/notes.txt' });

200

File moved successfully.

{
  "source": "/src/notes.txt",
  "destination": "/archive/notes.txt",
  "success": true
}

403

Move not allowed (requires both upload and delete permissions).

{
  "success": false,
  "error": "Move 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.

404

Source file or directory not found.

{
  "success": false,
  "error": "Source not found: /src/notes.txt"
}

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

409

Destination already exists.

{
  "success": false,
  "error": "Destination already exists: /archive/notes.txt"
}

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 & Append

PUT /{path}

Upload a file to the server. Creates a new file or overwrites an existing one.

Parameters

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

Request Body

Binary body — the raw file contents (application/octet-stream).

cURL

curl -X PUT "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/uploads/data.bin" \
  --data-binary @./local-file.bin

SDK

await client.files.upload('/uploads/data.bin');
// Pass the binary file contents as the request body.

201

File uploaded successfully.

403

Upload not allowed.

{
  "success": false,
  "error": "Upload not allowed"
}

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. Literal value must be an empty string ("").

This endpoint takes no request body.

cURL

curl -X PUT "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/tmp/marker.txt?touch="

SDK

await client.files.touch('/tmp/marker.txt', { touch: '' });

201

File created (did not exist).

204

Modification time updated (file already existed).

400

Cannot touch a directory.

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

403

Touch not allowed.

{
  "success": false,
  "error": "Touch 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.

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. Literal value must be an empty string ("").
owner	query	string	No	Create-time owner (user[:group]/uid[:gid]) for a newly-created file. Requires --allow-chown and --allowed-create-owners; refuses root. Overwrites and appends to an existing file preserve its owner. Absent means server default.

Request Body

Binary body — the raw file contents (application/octet-stream).

cURL

curl -X PUT "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/logs/app.log?append=" \
  --data-binary @./incremental.log

SDK

await client.files.put('/logs/app.log', { append: '' });
// Pass the binary data as the request body.

200

Data appended successfully (when ?append is used).

{
  "path": "/logs/app.log",
  "new_size": 16384,
  "success": true
}

201

File uploaded successfully.

{
  "message": "File uploaded",
  "path": "/uploads/data.bin",
  "size": 2048,
  "success": true
}

403

Upload not allowed (feature disabled or insufficient permissions).

{
  "success": false,
  "error": "Upload not allowed"
}

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 a 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 and allowlist; refuses root. Absent means server default.

Request Body

Binary body — the raw data to append (application/octet-stream).

cURL

curl -X PUT "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/append/logs/app.log" \
  --data-binary "request_id=abc123 status=200 latency_ms=42"

SDK

await client.files.append('/logs/app.log');
// Pass the binary data as the request body.

200

Data appended successfully.

{
  "path": "/logs/app.log",
  "new_size": 16384,
  "success": true
}

403

Upload not allowed.

{
  "success": false,
  "error": "Upload not allowed"
}

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.

Modify & Rename

PATCH /{path}

Multi-purpose file operation endpoint. Send a JSON body to change permissions (chmod), ownership (chown), or rename the file; send an octet-stream body to perform a resumable upload or append (set the X-Update-Range: append header for appends).

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	Target file 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. Literal value: append.

Request Body

One of the following JSON bodies, or a raw binary body for resumable uploads.

Chmod request (changes Unix permissions):

Field	Type	Required	Description
mode	string	Yes	Octal permission mode (e.g. "755", "644").

{
  "mode": "755"
}

Chown request (changes Unix ownership):

Field	Type	Required	Description
owner	string	No	Username or UID.
group	string	No	Group name or GID.

{
  "owner": "alice",
  "group": "staff"
}

Rename request (renames in place):

Field	Type	Required	Description
name	string	Yes	New filename (cannot contain path separators).

{
  "name": "new-filename.txt"
}

For resumable uploads or appends, send raw binary in the body and use the X-Update-Range: append header to append.

cURL

# Rename via JSON body
curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/data/old-name.txt" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name.txt"}'

# Append via binary body
curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/logs/app.log" \
  -H "X-Update-Range: append" \
  --data-binary "incremental line"

SDK

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

// Append with binary body
await client.files.patch('/logs/app.log', fileData, { XUpdateRange: 'append' });

204

Operation successful.

400

Invalid operation or parameters.

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

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

Operation not allowed.

{
  "success": false,
  "error": "Operation 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.

409

Conflict — file or directory already exists.

{
  "success": false,
  "error": "Target name 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 the conflicting file.

PATCH /api/v1/files/{path}

REST v1 variant of file property modification. 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.
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 and --allowed-create-owners; cannot be root. The moved item keeps its own owner. Absent means 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

One of the following JSON bodies.

Move request (moves the file to a new path):

Field	Type	Required	Description
move_to	string	Yes	Full destination path.

{
  "move_to": "/new/dir/file.txt"
}

Rename request (renames the file in place):

Field	Type	Required	Description
name	string	Yes	New filename (cannot contain path separators).

{
  "name": "renamed.txt"
}

cURL

# chmod via query
curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/data/script.sh?chmod=755"

# rename via JSON body
curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/data/old-name.txt" \
  -H "Content-Type: application/json" \
  -d '{"name": "renamed.txt"}'

SDK

// chmod via query
await client.files.patchApi('/data/script.sh', undefined, { chmod: '755' });

// rename via JSON body
await client.files.patchApi('/data/old-name.txt', { name: 'renamed.txt' });

200

Operation successful.

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

400

Invalid operation or parameters.

{
  "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.

403

Operation not allowed.

{
  "success": false,
  "error": "Chmod 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.

404

File or directory not found.

{
  "success": false,
  "error": "Path not found: /data/missing.txt"
}

409

Destination already exists (for move/rename).

{
  "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).

This endpoint takes no request body.

cURL

curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/chmod/data/script.sh?chmod=755"

SDK

await client.files.chmod('/data/script.sh', { chmod: '755' });

200

Permissions changed successfully.

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

400

Invalid octal mode value.

{
  "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.

403

chmod not allowed.

{
  "success": false,
  "error": "Chmod 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.

404

File or directory not found.

{
  "success": false,
  "error": "Path not found: /data/script.sh"
}

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).

This endpoint takes no request body.

cURL

curl -X PATCH "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/chown/data/file.txt?chown=alice:staff"

SDK

await client.files.chown('/data/file.txt', { chown: 'alice:staff' });

200

Ownership changed successfully.

{
  "path": "/data/file.txt",
  "owner": "alice",
  "group": "staff",
  "success": true
}

400

Invalid owner or group.

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

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

chown not allowed.

{
  "success": false,
  "error": "Chown not allowed"
}

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

File or directory not found.

{
  "success": false,
  "error": "Path not found: /data/file.txt"
}

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.

This endpoint takes no request body.

cURL

curl -X DELETE "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/tmp/old-file.txt"

SDK

await client.files.deleteRecursive('/tmp/old-file.txt');

200

Deleted successfully.

{
  "message": "Deleted /tmp/old-file.txt",
  "success": true
}

403

Delete not allowed.

{
  "success": false,
  "error": "Delete not allowed"
}

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

File or directory not found.

{
  "success": false,
  "error": "Path not found: /tmp/old-file.txt"
}

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 delete.
backend	query	string	No	Backend ID for remote file deletion.

This endpoint takes no request body.

cURL

curl -X DELETE "https://proj-abc123-cont-xyz789-files-1.eu-west-1.containers.hoody.icu/api/v1/files/tmp/old-file.txt"

SDK

await client.files.delete('/tmp/old-file.txt');

200

Deleted successfully.

{
  "message": "Deleted /tmp/old-file.txt",
  "success": true
}

403

Delete not allowed.

{
  "success": false,
  "error": "Delete not allowed"
}

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

File or directory not found.

{
  "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.