Update an existing folder’s properties such as name, visibility, upload permissions, or parent folder.
Endpoint
PATCH /api/user/folders/:id
Authentication
Requires authentication via API token in the Authorization header.
Path Parameters
The ID of the folder to update
Request Body
All fields are optional. Only include the fields you want to update.
New name for the folder (will be trimmed of whitespace)
Set folder visibility. When true, the folder is publicly accessible.
Whether to allow uploads to this folder
ID of the new parent folder. Set to null to make it a root folder. Cannot move a folder to itself or its descendants.
Response
Returns the updated folder object.
Unique identifier for the folder
Whether the folder is publicly accessible
Whether uploads are allowed to this folder
ISO 8601 timestamp of when the folder was created
ISO 8601 timestamp of when the folder was last updated
ID of the user who owns this folder
ID of the parent folder, or null if this is a root folder
Array of file objects in this folder
Counts of related entities
Number of files in this folder
Parent folder information
ID of the parent’s parent folder
Example Request
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"name": "New Folder Name"
}'
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"isPublic": true
}'
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"allowUploads": true
}'
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"parentId": "parent_folder_id"
}'
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"parentId": null
}'
Update multiple properties
curl -X PATCH "https://your-zipline-instance.com/api/user/folders/clx123" \
-H "Authorization: your-api-token" \
-H "Content-Type: application/json" \
-d '{
"name": "Public Gallery",
"isPublic": true,
"allowUploads": true
}'
Example Response
{
"id": "clx1234567890",
"name": "New Folder Name",
"public": false,
"allowUploads": true,
"createdAt": "2024-03-01T10:30:00.000Z",
"updatedAt": "2024-03-01T14:45:00.000Z",
"userId": "user123",
"parentId": "parent123",
"files": [],
"_count": {
"children": 2,
"files": 5
},
"parent": {
"id": "parent123",
"name": "Parent Folder",
"parentId": null
}
}
400 Bad Request - Circular reference
{
"error": "Bad Request",
"message": "A folder cannot be its own parent",
"statusCode": 400
}
400 Bad Request - Moving to descendant
{
"error": "Bad Request",
"message": "Cannot move folder into one of its descendants",
"statusCode": 400
}
{
"error": "Forbidden",
"message": "Parent folder does not belong to you",
"statusCode": 403
}
{
"error": "Not Found",
"message": "Folder not found",
"statusCode": 404
}
Notes
- You can only update folders you own (unless you’re an admin)
- The API prevents circular references - you cannot move a folder into itself or its descendants
- Setting
parentId to null moves the folder to the root level
- All property updates are atomic - either all succeed or none do