Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

File operations

Section titled “File operations”

These endpoints upload, modify, move, copy, search, and delete files inside a Hoody container. Use them to build file browsers, sync agents, code search tools, and image pipelines. All requests are scoped to a single container, addressed through that container’s files subdomain.

Search and discovery

Section titled “Search and discovery”

GET /{directory}?q

Section titled “GET /{directory}?q”

Search a directory for files whose name matches a case-insensitive query. Returns HTML by default, or JSON when ?json is present. Results are filtered to what the calling account may read.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
directorypathstringYesDirectory to search.
qquerystringYesSearch query (case-insensitive filename match). Maximum 512 bytes of UTF-8, measured both before and after Unicode lowercasing. Longer queries are rejected with 400.
jsonquerystringNoReturn JSON instead of HTML.
themequerystringNoColour theme of the HTML page. One of oc-1, aura, ayu, carbonfox, catppuccin, dracula, gruvbox, monokai, nightowl, nord, onedarkpro, shadesofpurple, solarized, tokyonight, vesper. Default oc-1.
colorSchemequerystringNoLight or dark colour scheme. Without it the page follows the system setting.
fontquerystringNoMonospace font of the editor and listing. One of ibm-plex-mono, cascadia-code, fira-code, hack, inconsolata, intel-one-mono, iosevka, jetbrains-mono, meslo-lgs, roboto-mono, source-code-pro, ubuntu-mono.
fontSizequeryintegerNoEditor font size in pixels. Default 14.
embedderOriginquerystringNoOrigin of the embedding page. Only https origins are accepted.
chromelessquerybooleanNoHide the header, sidebar, preview, footer, and borders at once.
borderlessquerybooleanNoHide the page borders.
hideHeaderquerybooleanNoHide the header bar.
hideSidebarquerybooleanNoHide the sidebar.
hidePreviewquerybooleanNoHide the preview pane.
hideFooterquerybooleanNoHide the footer.
embedBgquerystringNotransparent lets the background of the embedding page show through.

Response

Section titled “Response”

The response is HTML by default. When ?json is set, the response is a directory listing with the entries that match the query and the permissions of the calling account.

{
  "allow_archive": true,
  "allow_delete": true,
  "allow_remote": false,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/",
  "kind": "Index",
  "paths": [
    {
      "mtime": 1700000000000,
      "name": "README.md",
      "path_type": "File",
      "revisions": 3,
      "size": 1024
    },
    {
      "mtime": 1700000001000,
      "name": "src",
      "path_type": "Dir",
      "revisions": null,
      "size": 12
    }
  ],
  "remote_mounts": null,
  "uri_prefix": "",
  "user": "alice"
}
FieldTypeRequiredDescription
allow_archivebooleanNoWhether the deployment allows downloading folders as archives.
allow_deletebooleanNoWhether the deployment allows deletes.
allow_remotebooleanNoWhether the deployment allows remote backends and mounts.
allow_searchbooleanNoWhether the deployment allows search.
allow_uploadbooleanNoWhether the deployment allows uploads.
authbooleanNoWhether authentication is configured on this server.
dir_existsbooleanNoWhether the searched directory exists.
hrefstringNoThe path that was searched.
kindstringNoAlways Index.
pathsarrayNoMatching entries.
paths[].mtimeintegerNoUnix timestamp in milliseconds.
paths[].namestringNoEntry name.
paths[].path_typestringNoFile, Dir, SymlinkFile, or SymlinkDir.
paths[].revisionsintegerNoJournal revisions for this entry, if any.
paths[].sizeintegerNoFile size in bytes, or the number of items in a directory.
remote_mountsobjectNoThe mount directory when remote backends are allowed and a folder mounted there can be browsed through this server.
remote_mounts.dirstringYesThe mount directory as an absolute path.
remote_mounts.pathstringYesThe mount directory relative to the served root.
uri_prefixstringNoURI prefix for the request.
userstringNoThe authenticated user, if any.
Terminal window
curl -G \
  --data-urlencode "q=readme" \
  --data-urlencode "json=" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/"

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

Section titled “GET /api/v1/files/glob/{path}”

Find files and directories whose path matches a glob pattern. Supports recursive patterns (**/*.rs), brace expansion ({ts,tsx}), character classes ([a-z]), and standard wildcards. Results respect .gitignore by default.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDirectory path to search within.
patternquerystringYesGlob pattern (for example **/*.rs, src/**/*.{ts,tsx}, *.md).
max_resultsqueryintegerNoMaximum entries to return. Default 1000.
max_depthqueryintegerNoMaximum directory recursion depth. Default 50.
max_files_scannedqueryintegerNoMaximum filesystem entries to scan. Default 100000.
timeoutqueryintegerNoSearch timeout in seconds. Default 30.
no_ignorequerybooleanNoAlso search files excluded by .gitignore, .ignore, .git/info/exclude, and the global git excludes. Default false.
hiddenquerybooleanNoAlso search names starting with ., which are otherwise skipped unless an ignore file whitelists them. .git folders found inside the searched folder are still skipped. Refused with 403 for an account that may only list this path. Default false.
sortquerystringNoSort results by mtime (default), name, or size.
orderquerystringNoSort order: asc or desc. Default desc for mtime, asc for name and size.

Response

Section titled “Response”

Matching files and directories sorted as requested.

{
  "count": 1,
  "duration_ms": 12,
  "entries": [
    {
      "is_dir": false,
      "modified": 1700000000,
      "name": "src/main.ts",
      "size": 2048
    }
  ],
  "path": "/",
  "pattern": "**/*.ts",
  "total_scanned": 100,
  "truncated": false
}
FieldTypeRequiredDescription
countintegerYesNumber of entries returned.
duration_msintegerYesSearch duration in milliseconds.
entriesarrayYesMatching files and directories.
entries[].is_dirbooleanYesWhether the entry is a directory.
entries[].modifiedintegerNoLast modification time as Unix timestamp in seconds.
entries[].namestringYesAPI path of the matched file or directory.
entries[].sizeintegerYesFile size in bytes, or 0 for directories.
pathstringYesRoot directory that was searched.
patternstringYesThe glob pattern used.
total_scannedintegerYesTotal filesystem entries scanned.
truncatedbooleanYesTrue if results were limited by budget or timeout.
Terminal window
curl -G \
  --data-urlencode "pattern=**/*.ts" \
  --data-urlencode "max_results=100" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/glob/"

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path to search.
patternquerystringYesSearch pattern. Regex by default, literal when fixed_string=true.
ignore_casequerybooleanNoCase-insensitive matching. Default false.
fixed_stringquerybooleanNoTreat the pattern as a literal string, not regex. Default false.
globquerystringNoOnly search files matching this glob (ripgrep -g syntax, one pattern per request, at most 1024 bytes). Use *.rs to match any depth, src/**/*.go to anchor, !*_test.go to exclude. Matching is case-sensitive whatever ignore_case says. Not applied when the path is a single file.
contextqueryintegerNoNumber of context lines before and after each match. Default 0.
max_countqueryintegerNoMaximum matches per file. Default 50.
max_matchesqueryintegerNoTotal maximum matches across all files. Default 500.
max_depthqueryintegerNoMaximum directory recursion depth. Default 50.
max_filesizequeryintegerNoSkip files larger than this in bytes. Default 10485760.
timeoutqueryintegerNoSearch timeout in seconds. Default 30.
no_ignorequerybooleanNoAlso search files excluded by .gitignore, .ignore, .git/info/exclude, and the global git excludes. Default false.
hiddenquerybooleanNoAlso search names starting with .. Refused with 403 for an account that may only list this path. Default false.

Response

Section titled “Response”

Matching lines with optional context.

{
  "duration_ms": 8,
  "matches": [
    {
      "column_byte": 5,
      "context_after": [],
      "context_before": [],
      "line": "const foo = 1;",
      "line_number": 3,
      "path": "/src/main.ts"
    }
  ],
  "path": "/",
  "pattern": "foo",
  "total_files_matched": 1,
  "total_files_searched": 50,
  "total_matches": 1,
  "truncated": false
}
FieldTypeRequiredDescription
duration_msintegerYesSearch duration in milliseconds.
matchesarrayYesMatching lines.
matches[].column_byteintegerYesByte offset of the match start within the line.
matches[].context_afterarrayNoLines after the match, when context > 0.
matches[].context_beforearrayNoLines before the match, when context > 0.
matches[].linestringYesThe matched line content, truncated at 4096 characters.
matches[].line_numberintegerYes1-based line number.
matches[].pathstringYesAPI path of the matched file.
pathstringYesRoot path that was searched.
patternstringYesThe search pattern used.
total_files_matchedintegerYesNumber of files containing matches.
total_files_searchedintegerYesTotal files scanned.
total_matchesintegerYesNumber of matching lines returned.
truncatedbooleanYesTrue if results were limited by budget or timeout.
Terminal window
curl -G \
  --data-urlencode "pattern=foo" \
  --data-urlencode "ignore_case=true" \
  --data-urlencode "context=2" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/grep/src"

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

Section titled “GET /api/v1/files/realpath/{path}”

Resolve a file or directory path to its canonical form by following symbolic links. The returned real_path is relative to the serve root. Input traversal components such as .. are rejected with 400.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path to resolve.

Response

Section titled “Response”

The canonical path is returned relative to the serve root.

{
  "path": "/example.txt",
  "real_path": "/canonical/example.txt"
}
FieldTypeRequiredDescription
pathstringYesNormalized input path.
real_pathstringYesCanonical path relative to the serve root.
Terminal window
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/realpath/example.txt"

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

Section titled “GET /api/v1/files/stat/{path}”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path.
backendquerystringNoBackend ID: the metadata of the path on that remote backend instead of a local path

Response

Section titled “Response”

File or directory metadata.

{
  "group": "users",
  "is_symlink": false,
  "mtime": 1700000000000,
  "name": "example.txt",
  "owner": "alice",
  "path": "/example.txt",
  "path_type": "File",
  "permissions": "644",
  "revisions": 3,
  "size": 1024,
  "symlink_target": null
}
FieldTypeRequiredDescription
groupstringYesGroup name or GID.
is_symlinkbooleanYesWhether the entry is a symbolic link.
mtimeintegerYesUnix timestamp in milliseconds.
namestringYesEntry name.
ownerstringYesOwner name or UID.
pathstringYesAPI path of the file.
path_typestringYesWhat the path is: File, Dir, SymlinkFile, SymlinkDir, Fifo, Socket, CharDevice, or BlockDevice. A named pipe (Fifo), a socket or a device has no content to read: reading one is refused with 403.
permissionsstringYesOctal permission mode (for example 755).
revisionsintegerNoJournal revisions for this entry, if any.
sizeintegerYesFile size in bytes.
symlink_targetstringYesSymlink target path, or null if not a symlink.
Terminal window
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/stat/example.txt"

Image processing

Section titled “Image processing”

GET /{image}?thumbnail

Section titled “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 local files and for remote files named with remote connection parameters. The REST v1 ?thumbnail answers 501 for a backend.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
imagepathstringYesPath to the image file.
thumbnailquerystringYesEnable image processing.
formatquerystringNoOutput format. Default jpeg.
sizequerystringNoTarget box in pixels: WIDTHxHEIGHT, or a single N for an N×N box (max 2000×2000).
widthqueryintegerNoWidth in pixels. Height is auto-calculated.
heightqueryintegerNoHeight in pixels. Width is auto-calculated.
resizequerystringNoHow the image meets the target box. fit (default) fits inside, fill covers and centre-crops, cover covers, exact forces the box and may distort.
qualityquerystringNoResampling filter for resizing: low (box), medium (bilinear, default), or high (Lanczos3). Does not set compression; use q for JPEG quality.
qqueryintegerNoJPEG quality 1 to 100. Default 85. Only JPEG output uses it.
blurquerynumberNoGaussian blur radius 0 to 50.
grayscalequerystringNoConvert to grayscale.
bgquerystringNoBackground colour for transparency as hex RGB (for example ffffff for white).

Response

Section titled “Response”

The processed image bytes in the requested format. The Content-Type header is one of image/jpeg, image/png, image/webp, image/gif, or image/bmp. A Cache-Control: public, max-age=3600 header is set.

The body is binary image data and is not JSON.
Terminal window
curl -G \
  --data-urlencode "thumbnail=" \
  --data-urlencode "format=webp" \
  --data-urlencode "size=256" \
  --data-urlencode "q=80" \
  --output output.webp \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/photo.jpg"

Create, move, and copy

Section titled “Create, move, and copy”

POST /api/v1/files/{path}

Section titled “POST /api/v1/files/{path}”

Perform a write-time file operation: create a directory, extract an archive, download a file from a URL, or move or copy a file or directory. The operation is selected by a query parameter.

A download started with download_from keeps running if the client stops waiting: it runs to its end and its outcome is recorded in the download history.

The SDK exposes these operations through:

  • client.files.downloads.create(directory, options) for downloads on this REST endpoint (?download_from). The method sets nothing additional; pass download, filename, timeout, and owner in options.
  • client.files.mkdir(path, options?) for ?mkdir on this REST endpoint. The method sets mkdir=""; the caller does not pass mkdir.
  • client.files.archives.extract(archive, options) for extraction on this REST endpoint (?extract). The method sets nothing additional; pass the relevant parameters in options.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDestination or source path.
backendquerystringNoBackend ID, for mkdir only: create the directory on that remote backend. Any other operation with backend is refused with 400 INVALID_PARAMETER.
mkdirquerystringNoCreate a directory at the path.
extractquerystringNoExtract an archive. Empty value extracts all; a non-empty value is a selective path to extract (for example src/).
destquerystringNoDestination directory name for extraction. Default: archive name without extension.
download_fromquerystringNoDownload the file at this URL into the directory named by the path.
filenamequerystringNoWith download_from: the name to save the download as.
timeoutqueryintegerNoWith download_from: the most seconds the download may take, capped by the server’s own limit. Default and maximum: 43200 (12 hours).
move_toquerystringNoMove the file or directory to the destination path.
copy_toquerystringNoCopy the file or directory to the destination path.
overwritequerystringNoAllow overwriting an existing destination for copy.
ownerquerystringNoCreate-time owner for newly-created inodes as user[:group] or uid[:gid]. Requires the deployment to have enabled chown, and must resolve to one of the owners it permits. Refuses root. Applies to mkdir, extract, download_from, and copy_to.

Response

Section titled “Response”

A move or copy returns success, source, destination, and, for a directory copy, skipped and skipped_count. The body matches either files_MoveResponse or files_CopyResponse.

{
  "destination": "/new/path.txt",
  "source": "/old/path.txt",
  "success": true
}
FieldTypeRequiredDescription
destinationstringNoDestination path.
sourcestringNoSource path.
successbooleanNoWhether the operation succeeded.
skippedarrayNoEntries of a directory copy that were left out because they cannot be copied (a pipe, a socket, a device), at most 1000; empty for a file copy.
skipped[].pathstringYesPath of the source entry that was left out.
skipped[].reasonstringYesWhy it was left out.
skipped_countintegerNoHow many entries were left out, including any beyond those listed in skipped.
Terminal window
# Create a directory
curl -X POST \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/new-folder?mkdir="


# Download a file into a directory
curl -X POST -G \
  --data-urlencode "download_from=https://example.com/data.csv" \
  --data-urlencode "filename=data.csv" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/inbox"


# Move a file
curl -X POST -G \
  --data-urlencode "move_to=/archive/old.txt" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/old.txt"

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesSource file or directory path.
copy_toquerystringYesDestination path to copy the file or directory to.
overwritequerystringNoAllow overwriting the existing destination. Default false.
ownerquerystringNoCreate-time owner (user[:group] or uid[:gid]) for newly-created copies. Requires the deployment to have enabled chown and to permit the owner you name. Refuses root. Overwritten files preserve their owner.

Response

Section titled “Response”

The copy succeeded.

{
  "destination": "/new/path.txt",
  "source": "/old/path.txt",
  "success": true
}
FieldTypeRequiredDescription
destinationstringNoDestination path.
skippedarray of objectNoEntries of a directory copy that were left out because they cannot be copied (a pipe, a socket, a device), at most 1000; empty for a file copy. Each item has path (string, required) and reason (string, required).
skipped_countintegerNoHow many entries were left out, including any beyond those listed in skipped.
sourcestringNoSource path.
successbooleanNoWhether the operation succeeded.
Terminal window
curl -X POST -G \
  --data-urlencode "copy_to=/backup/file.txt" \
  --data-urlencode "overwrite=true" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/copy/file.txt"

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesSource file or directory path.
move_toquerystringYesDestination path to move the file or directory to.
ownerquerystringNoCreate-time owner for newly-created destination parent directories. Requires the deployment to have enabled chown and to permit the owner you name. The moved inode itself preserves its existing owner.

Response

Section titled “Response”

The move succeeded.

{
  "destination": "/new/path.txt",
  "source": "/old/path.txt",
  "success": true
}
FieldTypeRequiredDescription
destinationstringNoDestination path.
sourcestringNoSource path.
successbooleanNoWhether the operation succeeded.
Terminal window
curl -X POST -G \
  --data-urlencode "move_to=/archive/old.txt" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/move/old.txt"

Upload, append, and touch

Section titled “Upload, append, and touch”

PUT /{path}

Section titled “PUT /{path}”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDestination file path.
If-MatchheaderstringNoWrite only if the file has this ETag (the one a download of it answers with; a weak ETag never matches), or with ’*’ only if a file exists at the path. Otherwise 412 and nothing is written or created.
If-None-MatchheaderstringNo’*’ writes only if nothing exists at the path (create only); a tag writes only if the file does not have that ETag. Otherwise 412 and nothing is written.
If-Unmodified-SinceheaderstringNoWithout If-Match, write only if the file has not changed since this HTTP date. Otherwise 412 and nothing is written.

Request body

Section titled “Request body”

The request body is the raw file bytes. Set the Content-Type header to application/octet-stream.

Response

Section titled “Response”

The file was uploaded successfully.
Terminal window
curl -X PUT \
  --data-binary @local-file.txt \
  -H "Content-Type: application/octet-stream" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/remote-file.txt"

PUT /{path}?touch

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile path to touch.
touchquerystringYesFlag to indicate a touch operation.

Response

Section titled “Response”

The file did not exist and was created.
Terminal window
curl -X PUT \
  -G \
  --data-urlencode "touch=" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/empty.txt"

PUT /api/v1/files/{path}

Section titled “PUT /api/v1/files/{path}”

Upload a file to the server or to a remote backend, with optional append and optional chmod. Use ?append to append to an existing file instead of overwriting, and ?chmod to set exact permission bits on the local file. Servers that accept ?chmod list put_chmod in the features of GET /api/v1/version.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesDestination file path.
backendquerystringNoBackend ID for remote upload.
appendquerystringNoAppend the body to the end of an existing file (creating it if missing) instead of overwriting.
chmodquerystringNoPermission bits the local file ends with, in octal (644, 0600, 0o755, 000), whatever the server’s umask; the response echoes them in mode. Requires both upload and chmod to be enabled (403 otherwise). setuid, setgid and sticky bits are refused, as are values above 777. Refused with 400 together with backend or append, and when the path names something other than a regular file (a directory, a pipe, a device, a socket). Every refusal comes before the body is read: nothing is created or changed.
ownerquerystringNoCreate-time owner (user[:group] or uid[:gid]) for a newly-created file. Requires the deployment to have enabled chown and to permit the owner you name. Refuses root. Overwrites and appends preserve the existing file’s owner.
If-MatchheaderstringNoLocal files only; with backend it is refused with 400. Write only if the file has this ETag (the one a download of it answers with; a weak ETag never matches), or with ’*’ only if a file exists at the path. Otherwise 412 and nothing is written or created.
If-None-MatchheaderstringNoLocal files only; with backend it is refused with 400. ’*’ writes only if nothing exists at the path (create only); a tag writes only if the file does not have that ETag. Otherwise 412 and nothing is written.
If-Unmodified-SinceheaderstringNoLocal files only; with backend it is refused with 400. Without If-Match, write only if the file has not changed since this HTTP date. Otherwise 412 and nothing is written.
X-Expected-LengthheaderstringNoThe length of the whole body in bytes, for a body streamed without Content-Length. A body that ends before this many bytes, or runs past them, is refused with 400 and nothing is written or appended: the file stays as it was. Send it whenever the length is known: some HTTP/2 clients end a request’s body normally when they are aborted, so without it a cut-off body can look complete. Over the upload size limit it is refused with 413 before the body is read.

Request body

Section titled “Request body”

The request body is the raw file bytes. Set the Content-Type header to application/octet-stream.

Response

Section titled “Response”

The data was appended (when ?append was used).

{
  "new_size": 2048,
  "path": "/example.txt",
  "success": true
}
FieldTypeRequiredDescription
new_sizeintegerNoNew total file size after the append.
pathstringNoThe file path.
successbooleanNoWhether the operation succeeded.
Terminal window
# Upload
curl -X PUT \
  --data-binary @local-file.txt \
  -H "Content-Type: application/octet-stream" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"


# Upload with permissions
curl -X PUT \
  --data-binary @local-file.txt \
  -H "Content-Type: application/octet-stream" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt?chmod=600"


# Append
curl -X PUT \
  --data-binary @chunk.bin \
  -H "Content-Type: application/octet-stream" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt?append="

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile path.
ownerquerystringNoCreate-time owner (user[:group] or uid[:gid]) when this append creates a new file. Requires the deployment to have enabled chown and to permit the owner you name. Refuses root.
If-MatchheaderstringNoWrite only if the file has this ETag (the one a download of it answers with; a weak ETag never matches), or with ’*’ only if a file exists at the path. Otherwise 412 and nothing is written or created.
If-None-MatchheaderstringNo’*’ writes only if nothing exists at the path (create only); a tag writes only if the file does not have that ETag. Otherwise 412 and nothing is written.
If-Unmodified-SinceheaderstringNoWithout If-Match, write only if the file has not changed since this HTTP date. Otherwise 412 and nothing is written.

Request body

Section titled “Request body”

The request body is the raw bytes to append. Set the Content-Type header to application/octet-stream.

Response

Section titled “Response”

The data was appended.

{
  "new_size": 2048,
  "path": "/example.txt",
  "success": true
}
FieldTypeRequiredDescription
new_sizeintegerNoNew total file size after the append.
pathstringNoThe file path.
successbooleanNoWhether the operation succeeded.
Terminal window
curl -X PUT \
  --data-binary @chunk.bin \
  -H "Content-Type: application/octet-stream" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/append/example.txt"

Modify properties

Section titled “Modify properties”

PATCH /{path}

Section titled “PATCH /{path}”

Change file permissions (Unix only), change file ownership (Unix only), rename, or perform a resumable append. The shape of the body selects the operation.

For permission and ownership changes, send a JSON body. For a resumable append, send the raw bytes as application/octet-stream and set the X-Update-Range header to append.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path.
X-Update-RangeheaderstringNoSet to append to append the body to the end of the file.
If-MatchheaderstringNoWrites of content (X-Update-Range) only. Write only if the file has this ETag (the one a download of it answers with; a weak ETag never matches), or with ’*’ only if a file exists at the path. Otherwise 412 and nothing is written or created.
If-None-MatchheaderstringNoWrites of content (X-Update-Range) only. ’*’ writes only if nothing exists at the path (create only); a tag writes only if the file does not have that ETag. Otherwise 412 and nothing is written.
If-Unmodified-SinceheaderstringNoWrites of content (X-Update-Range) only. Without If-Match, write only if the file has not changed since this HTTP date. Otherwise 412 and nothing is written.

Request body

Section titled “Request body”

The body is one of three JSON shapes for property changes, or raw bytes for an append.

{
  "mode": "755"
}
FieldTypeRequiredDescription
modestringYesOctal permission mode (for example 755, 644).

Response

Section titled “Response”

The operation succeeded. The response carries no body.
Terminal window
# chmod
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"mode":"755"}' \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/example.txt"


# chown
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"owner":"alice","group":"users"}' \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/example.txt"


# rename
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"name":"renamed.txt"}' \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/example.txt"


# resumable append
curl -X PATCH \
  -H "X-Update-Range: append" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @chunk.bin \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/example.txt"

PATCH /api/v1/files/{path}

Section titled “PATCH /api/v1/files/{path}”

Modify file properties (chmod, chown), rename, or move to a new directory. The operation is selected by a query parameter or the body shape.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile path.
ownerquerystringNoCreate-time owner for newly-created destination parent directories on a JSON-body move_to. Requires the deployment to have enabled chown and to permit the owner you name. Cannot be root. The moved item keeps its own owner.
chmodquerystringNoSet file permissions using an octal mode value (for example ?chmod=755).
chownquerystringNoSet file ownership (for example ?chown=user:group or ?chown=user).

Request body

Section titled “Request body”

The body is a JSON object for rename or cross-directory move.

{
  "move_to": "/new/dir/file.txt"
}
FieldTypeRequiredDescription
move_tostringYesFull destination path.

Response

Section titled “Response”

The operation succeeded. The body matches one of three shapes: files_ChmodResponse, files_ChownResponse, or files_MoveResponse. The example below shows a chmod result.

{
  "mode": "755",
  "path": "/example.txt",
  "success": true
}
FieldTypeRequiredDescription
modestringNoApplied octal mode (chmod result).
pathstringNoThe file path.
successbooleanNoWhether the operation succeeded.
groupstringNoApplied group (chown result).
ownerstringNoApplied owner (chown result).
destinationstringNoDestination path (move result).
sourcestringNoSource path (move result).
Terminal window
# chmod
curl -X PATCH -G \
  --data-urlencode "chmod=755" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"


# chown
curl -X PATCH -G \
  --data-urlencode "chown=alice:users" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"


# move (cross-directory)
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"move_to":"/archive/example.txt"}' \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"


# rename
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"name":"renamed.txt"}' \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"

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

Section titled “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, for example ?chmod=755.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path.
chmodquerystringYesOctal permission mode (for example 755, 644, 0755).

Response

Section titled “Response”

The permissions were changed.

{
  "mode": "755",
  "path": "/example.txt",
  "success": true
}
FieldTypeRequiredDescription
modestringNoApplied octal mode.
pathstringNoThe file path.
successbooleanNoWhether the operation succeeded.
Terminal window
curl -X PATCH -G \
  --data-urlencode "chmod=755" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/chmod/example.txt"

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

Section titled “PATCH /api/v1/files/chown/{path}”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path.
chownquerystringYesOwner and optional group (for example user:group, user, :group, or UID:GID).

Response

Section titled “Response”

The ownership was changed.

{
  "group": "users",
  "owner": "alice",
  "path": "/example.txt",
  "success": true
}
FieldTypeRequiredDescription
groupstringNoApplied group.
ownerstringNoApplied owner.
pathstringNoThe file path.
successbooleanNoWhether the operation succeeded.
Terminal window
curl -X PATCH -G \
  --data-urlencode "chown=alice:users" \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/chown/example.txt"

Delete

Section titled “Delete”

DELETE /{path}

Section titled “DELETE /{path}”

Permanently delete a file or directory.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesPath to the file or directory to delete.

Response

Section titled “Response”

The file or directory was deleted. The response carries no body.
Terminal window
curl -X DELETE \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/example.txt"

DELETE /api/v1/files/{path}

Section titled “DELETE /api/v1/files/{path}”

Delete a file or directory from the server, or from a remote backend when ?backend is set.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesPath to the file or directory to delete.
backendquerystringNoBackend ID for remote file deletion.

Response

Section titled “Response”

The file or directory was deleted. The response carries no body.
Terminal window
curl -X DELETE \
  "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/files/example.txt"