Quick Start

Hoody Files is a flat, path-addressed file service that exposes common filesystem operations over HTTP. Every operation targets an absolute filesystem path under /api/v1/files, with the verb (HTTP method) describing the action rather than a named URL segment. This page walks through the core operation groups so you can pick the right endpoint for the task at hand.

URL shape

The path you want to read, write, list, or modify is encoded directly in the URL after /api/v1/files. The HTTP method selects the action:

• GET /api/v1/files/{path} — read a file or list a directory
• PUT /api/v1/files/{path} — create or fully replace a file
• PATCH /api/v1/files/{path} — partial update of a file
• DELETE /api/v1/files/{path} — delete a file or directory

For example, to read /home/user/notes.txt, send GET /api/v1/files/home/user/notes.txt. There is no /read/ or /list/ segment in the URL — the method and path alone identify the operation.

A smaller set of endpoints use an explicit operation segment for actions that don’t map to a standard CRUD verb:

Method	Path	Purpose
PUT	/api/v1/files/append/{path}	Append content to an existing file
POST	/api/v1/files/copy/{path}	Copy a file or directory
POST	/api/v1/files/move/{path}	Move or rename a file or directory
PATCH	/api/v1/files/chmod/{path}	Change POSIX permissions
PATCH	/api/v1/files/chown/{path}	Change ownership
GET	/api/v1/files/glob/{path}	Pattern-match files under a directory
GET	/api/v1/files/grep/{path}	Search file contents with a regex
GET	/api/v1/files/realpath/{path}	Resolve symlinks and normalize a path
GET	/api/v1/files/stat/{path}	Retrieve metadata for a file or directory

Operation groups

The rest of the Hoody Files reference is organized around four groups, each covered in detail on its own page.

Reading Files

Reading file contents, listing directories, resolving paths, and retrieving metadata. Covers GET /api/v1/files/{path} for both files and directories, plus stat and realpath.

Read the Reading Files guide for parameters, response shapes, and examples.

File Operations

Creating, updating, appending, copying, moving, and deleting files and directories. Also covers permission and ownership changes via chmod and chown.

Read the File Operations guide for the full request and response details.

Searching Files

Pattern matching with glob and content search with grep. Both are scoped to a directory path you provide.

Read the Searching Files guide for pattern syntax and result formatting.

Error Handling

Standard error responses, status codes, and recovery guidance for the Hoody Files service.

Read the Error Handling guide for the complete reference.

Authentication

All Hoody Files requests must include a bearer token in the Authorization header:

Authorization: Bearer <token>

Caution

Treat filesystem paths as untrusted input. Always validate and canonicalize user-supplied paths on the server side before forwarding them to the Hoody Files API, and never expose the service to requests that could escape an intended root directory.

Choosing the right endpoint

Use this quick decision table when you’re not sure which operation to reach for:

You want to…	Use
Read a file’s contents	GET /api/v1/files/{path}
List a directory	GET /api/v1/files/{path} (path points to a directory)
Create or replace a file	PUT /api/v1/files/{path}
Modify part of 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}
Change permissions	PATCH /api/v1/files/chmod/{path}
Change owner or group	PATCH /api/v1/files/chown/{path}
Delete a file or directory	DELETE /api/v1/files/{path}
Find files by name pattern	GET /api/v1/files/glob/{path}
Search file contents	GET /api/v1/files/grep/{path}
Resolve a symlink	GET /api/v1/files/realpath/{path}
Get file metadata	GET /api/v1/files/stat/{path}

Tip

If you’re new to the service, start with Reading Files to understand how GET /api/v1/files/{path} behaves differently for files versus directories, then move on to File Operations for write-side workflows.