Quick Start

Hoody Files is a plain filesystem service. Every endpoint is rooted at /api/v1/files and operates on absolute filesystem paths, so the URL itself names the file or directory you want to reach. There is no workspace scope, no project identifier, and no resource container: you point at a path and the service acts on it.

This page gives a one-page tour of the verbs available, the URL shapes they use, and which subpages cover them in depth. Use it as a map before reading the detailed references.

URL shape at a glance

The Hoody Files API has two URL conventions:

• Path-addressed verbs for the everyday operations: GET /api/v1/files/{path} to read a file or list a directory, PUT /api/v1/files/{path} to write a file, PATCH /api/v1/files/{path} to update a file in place, and DELETE /api/v1/files/{path} to delete a file or directory. There is no read or list segment in the URL; the HTTP method carries that meaning.
• Operation-addressed verbs for the specialized operations, each with its own HTTP method and an explicit operation segment: PUT /api/v1/files/append/{path}, POST /api/v1/files/copy/{path}, POST /api/v1/files/move/{path}, PATCH /api/v1/files/chmod/{path}, PATCH /api/v1/files/chown/{path}, GET /api/v1/files/glob/{path}, GET /api/v1/files/grep/{path}, GET /api/v1/files/realpath/{path}, and GET /api/v1/files/stat/{path}.

For example, to read the file /home/user/notes.txt you send GET /api/v1/files/home/user/notes.txt. To match every TypeScript file under /src you send GET /api/v1/files/glob/src?pattern=**/*.ts.

Read and list

A single GET /api/v1/files/{path} endpoint serves both reads and listings. When {path} resolves to a regular file the response is the file contents. When it resolves to a directory the response is a listing of its entries.

Note

Path-addressed reads return the body directly, with no JSON envelope wrapping file contents. Listings, on the other hand, do return JSON because the response carries structured metadata per entry.

See Reading Files for the full request and response shapes, content negotiation options, and listing parameters.

Write, update, append, and delete

Four HTTP methods cover day-to-day writes:

• PUT /api/v1/files/{path} writes a file, replacing any existing content.
• PATCH /api/v1/files/{path} updates a file in place, useful for partial edits.
• PUT /api/v1/files/append/{path} appends data to an existing file without rewriting it.
• DELETE /api/v1/files/{path} removes a file or, when the path is a directory, removes the directory and its contents.

See File Operations for body formats, idempotency behavior, and the flags that control overwrite and recursive delete.

Organize: copy, move, chmod, chown

Reorganizing a filesystem is its own group of operations, each with a dedicated verb:

• POST /api/v1/files/copy/{path} copies a file or directory tree to a new location.
• POST /api/v1/files/move/{path} moves a file or directory, renaming it in the process.
• PATCH /api/v1/files/chmod/{path} changes POSIX permissions on a path.
• PATCH /api/v1/files/chown/{path} changes the owning user and group of a path.

See File Operations for the body fields each verb accepts, including destination paths and the user/group identifiers accepted by chown.

Inspect: stat and realpath

Two read-only inspection endpoints resolve metadata about a path without reading its contents:

• GET /api/v1/files/stat/{path} returns file metadata: size, mode, mtime, and similar POSIX attributes.
• GET /api/v1/files/realpath/{path} resolves a path through any symlinks and returns the canonical absolute path.

Search: glob and grep

Two search endpoints cover the common ways of finding files by name and by content:

• GET /api/v1/files/glob/{path} lists every path under {path} matching a glob pattern supplied via the pattern query parameter.
• GET /api/v1/files/grep/{path} searches file contents under {path} for a regex supplied via the pattern query parameter, returning matching lines and the files that contained them.

Tip

Both search endpoints stream results as the search progresses, so large trees return the first matches without waiting for the full scan to finish.

Choosing a verb

When you are unsure which endpoint to reach for, narrow the question to two things:

1. What do you want to do with the path? Reading, writing, updating, deleting, copying, moving, changing permissions, changing ownership, inspecting, or searching.
2. Does that action live on the path, or on an operation segment? Most actions are HTTP methods on /api/v1/files/{path}. Copy, move, chmod, chown, append, glob, grep, realpath, and stat each have their own operation segment in the path.

The matching subpage covers the parameter table, body schema, and response shape for each verb.