file

The File submodule handles the full lifecycle of binary assets: upload, metadata persistence, secure URL generation, and controlled access delivery. Files are received via multipart/form-data, stored in the configured storage backend (local disk or a cloud object storage provider), and a metadata record is written containing the original filename, MIME type, file size, storage path, and a unique identifier. The optional destination parameter lets callers specify a sub-path for organizational purposes.

Files are never served via raw storage paths. Instead, an admin generates a time-limited signed token via PUT /file/open/:id for inline viewing or PUT /file/download/:id for attachment download. The token encodes the file ID, an expiry timestamp, and a server-side secret. Public endpoints decode and validate the token before streaming the file, preventing storage path enumeration and enforcing per-request expiry without maintaining a session.

The File submodule is used as a shared infrastructure layer by several other Core submodules. The User submodule stores avatars as File records. The Dashboard submodule stores widget component preview screenshots through the same pipeline. The Setting submodule's import workflow accepts JSON files via multipart upload. The AI submodule accepts a file_id to include document content as LLM context. This centralization means all binary assets go through a single, consistent storage and access-control pipeline regardless of which feature uploads them.

Deletion via DELETE /file removes file records and the underlying stored files. Callers are responsible for ensuring no other records hold references to the deleted file IDs before calling this endpoint, as HedHog does not automatically cascade deletes across foreign-key references.