File Operations

The file operations API covers day-to-day work of moving, mutating, and inspecting files in a container. It includes upload, touch, append, move, copy, delete, chmod, chown, plus content and filename search (glob, grep, realpath, stat) and on-the-fly image processing. Most endpoints accept an optional owner query parameter for create-time ownership on newly created inodes; chmod and chown are Unix-only. All endpoints are served from the container-scoped files service.

Search and Discovery

`GET /{directory}`

Search a directory for files matching a query. Returns an HTML index by default, or JSON when ?json is supplied. The q query parameter is limited to 512 UTF-8 BYTES after percent-decoding, measured both before and after Unicode lowercasing — case folding can change a string’s byte length in either direction. Longer queries are rejected with 400 rather than truncated.

Parameters

Name	In	Type	Required	Description
`directory`	path	string	Yes	Directory 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 empty value `""`

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/projects?q=report&json=" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "allow_archive": true,
  "allow_delete": true,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/projects?q=report",
  "kind": "Index",
  "paths": [
    {
      "name": "report-2024-q1.pdf",
      "path_type": "File",
      "size": 184230,
      "mtime": 1714584000000,
      "revisions": 3
    },
    {
      "name": "report-2024-q2.pdf",
      "path_type": "File",
      "size": 197845,
      "mtime": 1722388800000,
      "revisions": 2
    }
  ],
  "uri_prefix": "/projects/",
  "user": "alex"
}

{
  "success": false,
  "error": "Search query exceeds 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

{
  "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 /api/v1/files/glob/{path}`

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

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

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/glob/src?pattern=**%2F*.ts&max_results=50&sort=mtime&order=desc" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.glob('src', { pattern: '**/*.ts', max_results: 50, sort: 'mtime', order: 'desc' });

{
  "count": 2,
  "duration_ms": 12,
  "entries": [
    {
      "name": "/src/index.ts",
      "is_dir": false,
      "size": 4192,
      "modified": 1722388800
    },
    {
      "name": "/src/lib",
      "is_dir": true,
      "size": 8,
      "modified": 1719873600
    }
  ],
  "path": "/src",
  "pattern": "**/*.ts",
  "total_scanned": 1240,
  "truncated": false
}

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

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

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

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

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

Search file contents using a regex pattern. Backed by ripgrep with .gitignore support, binary file detection, and configurable budgets. Returns matching lines plus 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://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/grep/src?pattern=TODO&ignore_case=true&max_count=10" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.grep('src', { pattern: 'TODO', ignore_case: true, max_count: 10 });

{
  "duration_ms": 23,
  "matches": [
    {
      "column_byte": 4,
      "line": "// TODO: refactor before release",
      "line_number": 42,
      "path": "/src/index.ts",
      "context_after": ["export function run() {"],
      "context_before": ["import { foo } from './foo';"]
    }
  ],
  "path": "/src",
  "pattern": "TODO",
  "total_files_matched": 1,
  "total_files_searched": 87,
  "total_matches": 1,
  "truncated": false
}

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

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

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

{
  "success": false,
  "error": "Too many concurrent searches; retry 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. 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 -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/realpath/src/../lib/index.ts" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.realpath('src/../lib/index.ts');

{
  "path": "/src/../lib/index.ts",
  "real_path": "/lib/index.ts"
}

{
  "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	Provide a valid path without traversal characters
`ELOOP`	Symlink loop	Too many levels of symbolic links (circular chain)	Break the symlink cycle in the chain
`OPERATION_CONFLICT`	Operation conflict	Cannot combine realpath with other query operations	Call realpath without additional operations

{
  "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	Request access from the administrator
`PATH_ESCAPE`	Path escapes root	Resolved canonical path is outside the serve root	Use a path that stays within the serve root

{
  "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://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/stat/data/report.pdf" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.stat('data/report.pdf');

{
  "group": "users",
  "is_symlink": false,
  "mtime": 1722388800000,
  "name": "report.pdf",
  "owner": "alex",
  "path": "/data/report.pdf",
  "path_type": "File",
  "permissions": "644",
  "revisions": 4,
  "size": 184230,
  "symlink_target": null
}

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

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`

On-the-fly image processing with format conversion, resizing, and effects. Supports JPEG, PNG, WebP, GIF, and BMP input and output. Works for both local files and remote cloud storage backends. The response carries Cache-Control: public, max-age=3600.

Parameters

Name	In	Type	Required	Description
`image`	path	string	Yes	Path to image file
`thumbnail`	query	string	Yes	Enable image processing. Literal empty value `""`
`format`	query	string	No	Output format. Default: `"jpeg"`. Allowed: `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. Literal empty value `""`
`bg`	query	string	No	Background color for transparency (hex RGB, e.g. `ffffff` for white)

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/assets/hero.png?thumbnail=&format=webp&width=800&q=80" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.images.process('assets/hero.png', { thumbnail: '', format: 'webp', width: 800, q: 80 });

Returns the processed image as a binary stream with Content-Type set to one of image/jpeg, image/png, image/webp, image/gif, image/bmp.

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

File Operations (POST)

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

Multi-purpose endpoint that performs one of: create directory (?mkdir=), extract archive (?extract=), download from URL (?download_from=), move (?move_to=), or copy (?copy_to=). The operation is selected by which query flag is provided.

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	Source path or destination directory
`backend`	query	string	No	Backend ID for remote operation
`mkdir`	query	string	No	Create directory. Literal empty value `""`
`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: `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). Applies to `mkdir`/`extract`/`download_from`/`copy_to`

curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/projects/2025?mkdir=" \
  -H "Authorization: Bearer $HOODY_TOKEN"

curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/downloads/release.tar.gz?extract=&dest=release" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.operate('projects/2025', { mkdir: '' });

await client.files.operate('downloads/release.tar.gz', { extract: '', dest: 'release' });

{
  "source": "/drafts/post.md",
  "destination": "/published/post.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": "Failed to set create-owner on newly-created inode; operation rolled back"
}

`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`). Allowed: `true`, `false`
`owner`	query	string	No	Create-time owner (`user[:group]`/`uid[:gid]`) for newly-created copies. Requires `--allow-chown` plus allowlist; refuses root. Overwritten existing files preserve their owner. Absent uses the server default

curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/copy/drafts/post.md?copy_to=%2Fpublished%2Fpost.md" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.copy('drafts/post.md', { copy_to: '/published/post.md' });

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

{
  "success": false,
  "error": "Copy is not allowed (upload flag required)"
}

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

curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/move/drafts/post.md?move_to=%2Fpublished%2Fpost.md" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.move('drafts/post.md', { move_to: '/published/post.md' });

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

{
  "success": false,
  "error": "Move is not allowed (upload and delete flags required)"
}

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 and Write

`PUT /{path}`

Upload a file to the server. Creates new files or overwrites existing ones. The body is sent as application/octet-stream.

Parameters

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

Request Body

Binary file contents (application/octet-stream).

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/assets/logo.svg" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @logo.svg

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.upload('assets/logo.svg', fileBuffer);

{
  "success": false,
  "error": "Upload is 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 empty value `""`

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/var/log/app.log?touch=" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.touch('var/log/app.log', { touch: '' });

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

{
  "success": false,
  "error": "Touch is 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 (creating it if missing).

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

Request Body

Binary file contents (application/octet-stream).

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/assets/logo.svg" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @logo.svg

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/var/log/app.log?append=" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @new-lines.log

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.put('assets/logo.svg', fileBuffer);

await client.files.put('var/log/app.log', newLines, { append: '' });

{
  "success": true,
  "path": "/var/log/app.log",
  "new_size": 1048576
}

{
  "success": true,
  "path": "/assets/logo.svg",
  "size": 18423,
  "message": "File uploaded"
}

{
  "success": false,
  "error": "Upload is 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 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` plus allowlist; refuses root. Absent uses the server default

Request Body

Binary data to append (application/octet-stream).

curl -X PUT "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/append/var/log/app.log" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @new-lines.log

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.append('var/log/app.log', newLines);

{
  "success": true,
  "path": "/var/log/app.log",
  "new_size": 1048576
}

{
  "success": false,
  "error": "Upload is 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 Properties

`PATCH /{path}`

Resumable upload and append to files, change file permissions (Unix only), change file ownership (Unix only), or rename a file or directory. For incremental writes, set the X-Update-Range: append header to append data to the end of the file.

Parameters

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

Request Body

Either a JSON object matching one of ChmodRequest, ChownRequest, or RenameRequest, or an application/octet-stream binary payload when using the X-Update-Range: append header.

ChmodRequest — { "mode": "755" } (required)
ChownRequest — { "owner": "user", "group": "users" }
RenameRequest — { "name": "new-filename.txt" } (required; cannot contain path separators)

curl -X PATCH "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/notes/old.txt" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"new.txt"}'

curl -X PATCH "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/var/log/app.log" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "X-Update-Range: append" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @new-lines.log

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

await client.files.patch('var/log/app.log', newLines, { 'X-Update-Range': 'append' });

{
  "success": false,
  "error": "Invalid chmod mode '999' (must be octal)"
}

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 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 variant of file modification. Supports ?chmod=755, ?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` plus `--allowed-create-owners`; cannot be root. The moved item keeps its own owner. Absent uses the 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

A JSON object matching one of MoveRequest or RenameRequest.

MoveRequest — { "move_to": "/new/dir/file.txt" } (required)
RenameRequest — { "name": "new-filename.txt" } (required; cannot contain path separators)

curl -X PATCH "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/scripts/run.sh?chmod=755" \
  -H "Authorization: Bearer $HOODY_TOKEN"

curl -X PATCH "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/drafts/post.md" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"move_to":"/published/post.md"}'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

await client.files.patchApi('drafts/post.md', { move_to: '/published/post.md' });

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

{
  "success": false,
  "error": "Invalid chmod mode '999' (must be octal)"
}

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

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

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

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

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

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

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://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/chmod/scripts/run.sh?chmod=755" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

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

{
  "success": false,
  "error": "Invalid chmod mode '999' (must be octal)"
}

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

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

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

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

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

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://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/chown/data/report.pdf?chown=alex:users" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.chown('data/report.pdf', { chown: 'alex:users' });

{
  "success": true,
  "path": "/data/report.pdf",
  "owner": "alex",
  "group": "users"
}

{
  "success": false,
  "error": "User 'alex' not found"
}

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

{
  "success": false,
  "error": "chown is 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

{
  "success": false,
  "error": "File 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://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/tmp/scratch.txt" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.deleteRecursive('tmp/scratch.txt');

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

{
  "success": false,
  "error": "Delete is 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

{
  "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	File or directory path
`backend`	query	string	No	Backend ID for remote file deletion

curl -X DELETE "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/tmp/scratch.txt" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.delete('tmp/scratch.txt');

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

{
  "success": false,
  "error": "Delete is 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

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