Share links let editors and admins publish read-only access to a file or folder without requiring the recipient to have a Vaulx account. Each link is identified by a 64-character cryptographically random hex slug and expires automatically after seven days. Resolving or downloading via a share link never requires authentication. Revoking a share hard-deletes the row and writes aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/noelzappy/vaulx/llms.txt
Use this file to discover all available pages before exploring further.
share.revoke entry to the audit log.
Create file share link
The UUID of the active file to share.
POST /files/{fileID}/share
Generates a 7-day public share link for a single file. If an active (non-expired) share already exists for this file, the existing share URL is returned rather than creating a duplicate.
Authentication: editor role or higher required.
Response
The slug is a 32-byte random value encoded as 64 lowercase hex characters. Combine it with your Vaulx base URL to get the full public link, e.g.
https://vault.example.com/s/<slug>.Create folder share link
The UUID of the folder to share.
POST /files/folders/{folderID}/share
Generates a 7-day public share link for an entire folder tree. Visitors can browse subfolders, preview files, and download individual assets through the public interface. If an active share already exists for this folder, the existing URL is returned.
Authentication: editor role or higher required.
Response
Resolve share
The 64-character hex slug from the share URL.
GET /s/{slug}
Public endpoint — no authentication required. Renders an HTML page for the shared resource.
- File shares → renders
SharedFilePagewith a presigned S3 preview URL. - Folder shares → renders
SharedFolderPagelisting subfolders and files. Use the?folder=<uuid>query parameter to navigate into a subfolder; navigation is strictly confined to the shared root’s tree — any UUID outside the tree returns 404.
view_count.
| Condition | Status |
|---|---|
| Slug not found | 404 Not Found |
expires_at is in the past | 410 Gone |
view_count >= max_views | 410 Gone |
Folder share only. Navigate into a subfolder within the shared tree. The UUID must be the shared root or one of its descendants (depth-capped at 64 levels).
Direct file download
The 64-character hex slug of a file share.
GET /s/{slug}/download
Forces a file-save download by redirecting to a presigned S3 GET URL with Content-Disposition: attachment. This endpoint only works for file shares — folder share slugs return 404.
No authentication required.
- Returns 302 redirect to the presigned S3 URL.
- Returns 410 Gone if the link is expired or the view limit has been reached.
- Returns 404 if the slug is a folder share or is not found.
Download file inside folder share
The 64-character hex slug of a folder share.
The UUID of the file to download. Must belong to the shared folder tree.
GET /s/{slug}/file/{fileID}
Downloads a specific file that lives inside a publicly shared folder tree. The fileID is validated against the shared root — any file outside the tree returns 404.
No authentication required.
- Returns 302 redirect to the presigned S3 GET URL.
- Returns 404 if the slug is not a folder share, the file is not found, or the file is outside the shared tree.
- Returns 410 Gone if the share has expired.
List shares
GET /shares
Renders an HTML page listing share links with their details.
Authentication: editor role or higher required. Viewer-role users are silently redirected to /files.
- Admins see all shares across every user.
- Editors see only shares they created.
Unique share identifier.
Name of the shared file or folder.
file or folder.The public slug used to construct the share URL.
Display name of the user who created the share.
Human-readable creation date (e.g.
Jan 2, 2006).Human-readable expiry date, or
Never if no expiry is set.Number of times the share page has been resolved.
Revoke share
The UUID of the share link to revoke.
DELETE /shares/{shareID}
Permanently deletes a share link. The public URL immediately becomes invalid.
Authentication: admin, or the editor who originally created the share.
- Returns 200 OK with an
HX-Triggerheader that fires a success toast:{"showToast":{"message":"Share link revoked","type":"success"}}. - Returns 403 Forbidden if the caller is not admin and does not own the share.
- Returns 404 if the share does not exist.
- Writes a
share.revokeentry to the audit log.
Share model
| Field | Type | Notes |
|---|---|---|
id | UUID | Primary key |
file_id | UUID | null | Set for file shares; null for folder shares |
folder_id | UUID | null | Set for folder shares; null for file shares |
slug | text | 64-char hex; unique |
share_type | text | Always public |
expires_at | timestamptz | null | Null means no expiry |
max_views | int | null | Null means unlimited |
view_count | int | Incremented on each resolution |
created_by | UUID | FK → users.id |
created_at | timestamptz | Row creation time |