Quick Start
Section titled “Quick Start”The Hoody Files service exposes a flat HTTP surface for working with files and directories on a container’s filesystem. Every operation is path-addressed under /api/v1/files and takes an absolute filesystem path. There are no project, container, or workspace identifiers in the URL — the service is rooted directly in the container’s filesystem, so a request to /api/v1/files/home/user/notes.txt operates on the literal path /home/user/notes.txt.
This page groups the available operations into four families and links to the detailed references for each.
Reading Files
Section titled “Reading Files”Two HTTP verbs on the path cover reading and listing:
GET /api/v1/files/{path}— read a file’s contents, or list a directory’s entries when the path points to a directory.GET /api/v1/files/stat/{path}— retrieve metadata (size, mode, mtime, type) without reading the contents.GET /api/v1/files/realpath/{path}— resolve symlinks and return the canonical absolute path.
For full request and response details, see Reading Files.
Writing and Updating Files
Section titled “Writing and Updating Files”Three verbs mutate file contents:
PUT /api/v1/files/{path}— create or replace a file with the request body.PATCH /api/v1/files/{path}— apply a partial update to a file.PUT /api/v1/files/append/{path}— append the request body to an existing file.
For full request and response details, see File Operations.
Organizing the Filesystem
Section titled “Organizing the Filesystem”Five verbs restructure paths and permissions:
POST /api/v1/files/copy/{path}— duplicate a file or directory to a new location.POST /api/v1/files/move/{path}— relocate a file or directory.DELETE /api/v1/files/{path}— remove a file or directory.PATCH /api/v1/files/chmod/{path}— change POSIX permissions.PATCH /api/v1/files/chown/{path}— change owner and group.
For full request and response details, see File Operations.
Searching the Filesystem
Section titled “Searching the Filesystem”Two read-only verbs traverse the tree:
GET /api/v1/files/glob/{path}— list paths matching a glob pattern such as**/*.ts.GET /api/v1/files/grep/{path}— search file contents for a regular expression and return matching lines with their paths.
For full request and response details, see File Operations.
URL Shape Summary
Section titled “URL Shape Summary”Every endpoint on this service follows one of two shapes:
/api/v1/files/{path}— a plain verb on the path (GET,PUT,PATCH,DELETE)./api/v1/files/{operation}/{path}— a named operation followed by the path (glob,grep,append,copy,move,chmod,chown,stat,realpath).
There is no read, list, write, or delete segment in the URL — those are expressed as HTTP verbs on the path itself. For example, reading /home/user/notes.txt is GET /api/v1/files/home/user/notes.txt, not GET /api/v1/files/read/home/user/notes.txt.
Path Encoding
Section titled “Path Encoding”Paths are absolute and resolved against the container’s filesystem root. Each segment of {path} is URL-encoded individually; / separates segments and is not encoded. Special characters in path segments (spaces, parentheses, non-ASCII bytes) must be percent-encoded per RFC 3986.