Quick Start

The Hoody Files API provides direct access to the filesystem through a path-addressed REST interface. All endpoints are rooted at /api/v1/files and operate on absolute filesystem paths. This page is an overview — see the linked detail pages for full parameter and response coverage of each operation.

URL shape

Every operation follows one of two URL patterns:

• Path-addressed verbs: an HTTP method on /api/v1/files/{path}. The HTTP method selects the operation. For example, GET /api/v1/files/home/user/notes.txt reads a file, while PUT /api/v1/files/home/user/notes.txt writes to it. The path segment never contains a verb like read or list.
• Explicit operation verbs: a few operations use /api/v1/files/{operation}/{path} with a specific method — for example 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}.

Note

Paths are absolute filesystem paths. Pass them as the trailing segments of the URL — for example, the path /home/user/notes.txt becomes /api/v1/files/home/user/notes.txt.

Operation groups

The Files API is organized into four functional groups. Each group is documented in detail on its own page.

Reading files and listing directories

Inspect the contents of the filesystem — read file bodies, list directory entries, resolve absolute paths, and inspect metadata.

• GET /api/v1/files/{path} — read a file or list a directory
• GET /api/v1/files/stat/{path} — file or directory metadata
• GET /api/v1/files/realpath/{path} — resolve symlinks to an absolute path

See Reading Files for full coverage.

Writing and updating files

Create, overwrite, append, and patch file contents.

• PUT /api/v1/files/{path} — write or overwrite a file
• PATCH /api/v1/files/{path} — apply a partial update
• PUT /api/v1/files/append/{path} — append to an existing file

See File Operations for full coverage.

Organizing the filesystem

Move, copy, delete, and change permissions or ownership of files and directories.

• POST /api/v1/files/copy/{path} — copy a file or directory
• POST /api/v1/files/move/{path} — move or rename a file or directory
• DELETE /api/v1/files/{path} — delete a file or directory
• PATCH /api/v1/files/chmod/{path} — change POSIX permissions
• PATCH /api/v1/files/chown/{path} — change owner and group

Searching the filesystem

Locate files by pattern and search file contents across the tree.

• GET /api/v1/files/glob/{path} — match files by glob pattern (e.g. GET /api/v1/files/glob/src?pattern=**/*.ts)
• GET /api/v1/files/grep/{path} — search file contents by regular expression

Authentication

All Files endpoints require a valid bearer token passed in the Authorization header as Bearer <token>. Tokens are scoped to the authenticated identity and inherit its filesystem permissions.

Choosing the right endpoint

If you need to…	Use
Read a file’s contents	GET /api/v1/files/{path}
List a directory	GET /api/v1/files/{path} (path is a directory)
Get size, mtime, or type	GET /api/v1/files/stat/{path}
Resolve symlinks	GET /api/v1/files/realpath/{path}
Create or overwrite a file	PUT /api/v1/files/{path}
Partially update a file	PATCH /api/v1/files/{path}
Append to a file	PUT /api/v1/files/append/{path}
Copy a file or directory	POST /api/v1/files/copy/{path}
Move or rename	POST /api/v1/files/move/{path}
Delete a file or directory	DELETE /api/v1/files/{path}
Change permissions	PATCH /api/v1/files/chmod/{path}
Change owner or group	PATCH /api/v1/files/chown/{path}
Find files by pattern	GET /api/v1/files/glob/{path}
Search file contents	GET /api/v1/files/grep/{path}

Tip

Start with Reading Files if you are integrating for the first time — it covers the most common operations (GET, stat, realpath) and demonstrates the path-encoding conventions used across the rest of the API.