REST API Endpoints for Folders

Folders in Vaulx are hierarchical containers that map directly to logical groupings in the file browser. Every folder tracks its owner and, optionally, a parent folder — enabling arbitrarily deep nesting. Deletions cascade automatically through child folders and their files at the database level. All folder endpoints require an active session cookie.

Data models

File

Field	Type	Notes
`id`	`UUID`	Primary key, auto-generated.
`folder_id`	`UUID \| null`	Parent folder. `null` means root.
`name`	`text`	Display name of the file.
`s3_key`	`text`	Object key in the S3-compatible bucket.
`size_bytes`	`bigint`	File size in bytes.
`mime_type`	`text \| null`	MIME type detected at upload time (e.g., `image/png`).
`uploaded_by`	`UUID`	References `users.id`.
`status`	`text`	Enum: `pending`, `active`, `deleted`.
`created_at`	`timestamptz`	UTC timestamp set on insert.

Folder

Field	Type	Notes
`id`	`UUID`	Primary key, auto-generated.
`parent_id`	`UUID \| null`	Parent folder. `null` means root.
`name`	`text`	Display name of the folder.
`owner_id`	`UUID`	References `users.id`. Set to the creating user.
`created_at`	`timestamptz`	UTC timestamp set on insert.

The folders table uses ON DELETE CASCADE on the parent_id foreign key. Deleting a folder automatically removes all of its descendant folders and their associated files from the database. Files’ S3 objects are not cleaned up automatically on a cascade — use the admin trash/hard-delete flow for full cleanup.

Create a folder

POST /files/folders

Creates a new folder. The authenticated user becomes the folder’s owner_id. Optionally supply a parent_id to nest the folder inside an existing one; omit it to create a root-level folder. Authentication: Required (editor+) Request body (application/x-www-form-urlencoded):

name

string

required

Display name of the new folder. Cannot be empty.

parent_id

string

UUID of the parent folder. Omit (or leave blank) to create a root-level folder.

# Create a root-level folder
curl -b cookies.txt -X POST http://localhost:8080/files/folders \
  -d "name=Marketing"

# Create a nested folder
curl -b cookies.txt -X POST http://localhost:8080/files/folders \
  -d "name=Campaigns" \
  -d "parent_id=018e2c1a-dead-beef-a0b0-000000000001"

Success response: 302 Found — redirects to /files/{parent_id} when parent_id was supplied, or /files for a root folder. The response also sets:

HX-Trigger: {"showToast": {"message": "Folder created", "type": "success"}}

Error responses:

Status	Condition
`400 Bad Request`	Form parse error or `name` is empty.
`403 Forbidden`	User is not at least an editor.
`500 Internal Server Error`	Database insert failed.

Delete a folder

DELETE /files/folders/{folderID}

Permanently deletes a folder and, via the database cascade, all child folders. The S3 objects for any files contained within the deleted tree are not removed — use the admin hard-delete flow to clean them up. Authentication: Required (folder owner or admin)

folderID

string

required

UUID of the folder to delete.

curl -b cookies.txt -X DELETE \
  http://localhost:8080/files/folders/018e2c1a-dead-beef-a0b0-000000000001

Success response: 200 OK with HX-Trigger:

{"showToast": {"message": "Folder deleted", "type": "success"}}

Error responses:

Status	Condition
`400 Bad Request`	`folderID` is not a valid UUID.
`403 Forbidden`	Authenticated user is neither the folder owner nor an admin.
`404 Not Found`	No folder with that ID exists.
`500 Internal Server Error`	Database deletion failed.

Deletion cascades through all child folders at the database level. This action cannot be undone from the UI. Ensure child folders are intentionally being removed before proceeding.

Rename a folder

PATCH /files/folders/{folderID}

Updates the display name of an existing folder. Returns the refreshed FolderCard HTML partial for HTMX in-place swap. Authentication: Required (folder owner or admin)

folderID

string

required

UUID of the folder to rename.

Request body (application/x-www-form-urlencoded):

name

string

required

The new display name for the folder. Cannot be empty.

curl -b cookies.txt -X PATCH \
  http://localhost:8080/files/folders/018e2c1a-dead-beef-a0b0-000000000001 \
  -d "name=Brand Assets"

Success response: 200 OK — FolderCard HTML partial (includes updated item count) with HX-Trigger:

{"showToast": {"message": "Folder renamed", "type": "success"}}

Error responses:

Status	Condition
`400 Bad Request`	`folderID` invalid, form parse error, or `name` is empty.
`403 Forbidden`	User is neither the folder owner nor an admin.
`404 Not Found`	No folder with that ID exists.
`500 Internal Server Error`	Database update failed.

Overview

Files & Folders

Upload

Shares & Permissions

Admin

REST API Endpoints for Folders

Data models

File

Folder

Create a folder

Delete a folder

Rename a folder

Build docs developers (and LLMs) love

Overview

Files & Folders

Upload

Shares & Permissions

Admin

Documentation Index

​Data models

​File

​Folder

​Create a folder

​Delete a folder

​Rename a folder

Build docs developers (and LLMs) love

Data models

File

Folder

Create a folder

Delete a folder

Rename a folder