Folders in Zipline help you organize your uploaded files into logical groups. They support nested hierarchies, public sharing, and controlled upload access.
Creating folders Via the dashboard
Navigate to the Files section
Click “New Folder”
Enter a folder name
Optionally configure:
Public visibility
Allow uploads from others
Parent folder (for nesting)
Via the API Create a folder with the API:
curl -X POST https://your-zipline.com/api/user/folders \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Screenshots", "isPublic": false }'
Response:
{ "id" : "folder_abc123" , "name" : "Screenshots" , "public" : false , "allowUploads" : false , "createdAt" : "2026-03-03T10:00:00.000Z" , "count" : { "files" : 0 , "children" : 0 } }
Folder structure Each folder in the database contains:
{ id : string // Unique folder ID name : string // Folder name public : boolean // Public visibility allowUploads : boolean // Allow anonymous uploads parentId : string | null // Parent folder for nesting userId : string // Owner user ID files : File [] // Files in this folder children : Folder [] // Nested subfolders }
See the Prisma schema at prisma/schema.prisma:310-327.
Nested folders Folders support unlimited nesting depth:
Projects/ ├── Client A/ │ ├── Designs/ │ └── Documents/ └── Client B/ └── Assets/
Creating nested folders curl -X POST https://your-zipline.com/api/user/folders \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Designs", "parentId": "parent_folder_id" }'
You cannot move a folder into one of its own descendants. Zipline prevents circular references by checking the parent chain.
Viewing folder hierarchy Get a folder with its parent chain:
curl https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN"
Response includes:
{ "id" : "folder_abc123" , "name" : "Designs" , "parent" : { "id" : "parent_folder_id" , "name" : "Client A" , "parentId" : "root_folder_id" }, "children" : [ ... ], "files" : [ ... ] }
The parent chain is built recursively in src/lib/db/models/folder/buildParentChain.
Adding files to folders During upload Upload directly to a folder:
curl -X POST https://your-zipline.com/api/upload \ -H "Authorization: YOUR_TOKEN" \ -H "X-Zipline-Folder: folder_id_here" \ -F "[email protected] "
The file is immediately added to the folder.
After upload Move an existing file to a folder:
curl -X PUT https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id": "file_id"}'
Creating folder with files Create a folder and add files in one request:
curl -X POST https://your-zipline.com/api/user/folders \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New Folder", "files": ["file_id_1", "file_id_2"] }'
Public folders Public folders can be shared with others:
curl -X PATCH https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"isPublic": true}'
Public folders show their contents to anyone with the link, but users must still be authenticated to view individual files unless the files themselves are public.
Upload permissions Allowing uploads Enable anonymous uploads to a folder:
curl -X PATCH https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"allowUploads": true}'
Now anyone can upload to this folder without authentication:
curl -X POST https://your-zipline.com/api/upload \ -H "X-Zipline-Folder: folder_id" \ -F "[email protected] "
Files uploaded anonymously to a folder are owned by the folder owner and count toward their quota.
See the implementation in src/server/routes/api/upload/index.ts:51-60.
Managing folders Updating folder properties curl -X PATCH https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Name", "isPublic": false, "allowUploads": false, "parentId": "new_parent_id" }'
All fields are optional - only include what you want to change.
Moving folders Change the parent folder:
curl -X PATCH https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"parentId": "new_parent_id"}'
To move to root level:
curl -X PATCH https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"parentId": null}'
Deleting folders When deleting a folder, you must specify what happens to its contents:
Move to root Move all files and subfolders to the root level:
curl -X DELETE https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "delete": "folder", "childrenAction": "root" }'
Move to another folder Move contents to a different folder:
curl -X DELETE https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "delete": "folder", "childrenAction": "folder", "targetFolderId": "destination_folder_id" }'
Cascade delete Delete the folder and all its contents recursively:
curl -X DELETE https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "delete": "folder", "childrenAction": "cascade" }'
Cascade delete permanently removes all files and subfolders. This action cannot be undone.
See the implementation in src/server/routes/api/user/folders/[id]/index.ts:242-328.
Removing files from folders Remove a file without deleting it:
curl -X DELETE https://your-zipline.com/api/user/folders/folder_id \ -H "Authorization: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "delete": "file", "id": "file_id" }'
The file remains in your library but is no longer in the folder.
Querying folders List all folders curl https://your-zipline.com/api/user/folders \ -H "Authorization: YOUR_TOKEN"
List root folders only curl "https://your-zipline.com/api/user/folders?root=true" \ -H "Authorization: YOUR_TOKEN"
List folders by parent curl "https://your-zipline.com/api/user/folders?parentId=parent_folder_id" \ -H "Authorization: YOUR_TOKEN"
Get folder without files For performance, exclude file details:
curl "https://your-zipline.com/api/user/folders/folder_id?noincl=true" \ -H "Authorization: YOUR_TOKEN"
Exporting folders Zipline supports exporting entire folders as ZIP archives:
curl -X POST https://your-zipline.com/api/user/folders/folder_id/export \ -H "Authorization: YOUR_TOKEN"
The export is processed asynchronously and includes all files in the folder.
See src/server/routes/api/user/folders/[id]/export.ts for implementation.
Folder statistics Each folder response includes file and subfolder counts:
{ "id" : "folder_abc123" , "name" : "Projects" , "count" : { "files" : 42 , "children" : 3 } }
This is computed using Prisma’s _count feature.
FAQs
What's the maximum folder nesting depth?
There’s no hard limit, but very deep nesting (>10 levels) may impact performance when building parent chains. Keep your folder structure reasonable for best performance.
Can multiple users share a folder?
No, folders are owned by a single user. However, you can make a folder public or enable uploads to allow others to contribute.
What happens to folder files when I reach my quota?
Files in folders count toward your quota. If you exceed your quota, you won’t be able to upload new files to any folder until you free up space.
Can I move files between folders?
Yes, you can add files to folders or remove them at any time. A file can only be in one folder at a time.
How do I prevent a folder from being moved into itself?
Zipline automatically prevents circular references. When updating a folder’s parent, the system checks the entire parent chain to ensure the folder isn’t being moved into one of its descendants.
See also
Uploads - Learn about uploading filesStorage - Understand where files are stored