Skip to main content
Create a new folder to organize your files. You can optionally add existing files to the folder during creation and set it as a child of another folder.

​
Endpoint

POST /api/user/folders

​
Authentication

Requires authentication via API token in the Authorization header.

​
Rate Limiting

This endpoint is rate limited to 2 requests per second.

​
Request Body

​
name
string
required
The name of the folder. Must be at least 1 character after trimming whitespace.
​
isPublic
boolean
default:"false"
Whether the folder should be publicly accessible.
​
files
array
Array of file IDs to add to the folder during creation.
​
parentId
string
ID of the parent folder. If provided, this folder will be created as a child of the specified parent.

​
Response

Returns the created folder object with all its properties.
​
id
string
required
Unique identifier for the folder
​
name
string
required
The folder name
​
public
boolean
required
Whether the folder is publicly accessible
​
allowUploads
boolean
required
Whether uploads are allowed to this folder (defaults to false)
​
createdAt
string
required
ISO 8601 timestamp of when the folder was created
​
updatedAt
string
required
ISO 8601 timestamp of when the folder was last updated
​
userId
string
required
ID of the user who owns this folder
​
parentId
string | null
ID of the parent folder, or null if this is a root folder
​
files
array
Array of file objects in this folder
​
_count
object
Counts of related entities
​
parent
object | null
Parent folder information, or null if this is a root folder

​
Example Request

Create basic folder
curl -X POST "https://your-zipline-instance.com/api/user/folders" \
  -H "Authorization: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Screenshots"
  }'
Create public folder
curl -X POST "https://your-zipline-instance.com/api/user/folders" \
  -H "Authorization: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Public Gallery",
    "isPublic": true
  }'
Create folder with files
curl -X POST "https://your-zipline-instance.com/api/user/folders" \
  -H "Authorization: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Assets",
    "files": ["file123", "file456"]
  }'
Create nested folder
curl -X POST "https://your-zipline-instance.com/api/user/folders" \
  -H "Authorization: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2024",
    "parentId": "parent_folder_id"
  }'

​
Example Response

200 OK
{
  "id": "clx1234567890",
  "name": "Screenshots",
  "public": false,
  "allowUploads": false,
  "createdAt": "2024-03-01T10:30:00.000Z",
  "updatedAt": "2024-03-01T10:30:00.000Z",
  "userId": "user123",
  "parentId": null,
  "files": [],
  "_count": {
    "children": 0,
    "files": 0
  },
  "parent": null
}
400 Bad Request - No files found
{
  "error": "Bad Request",
  "message": "No files found, with given request",
  "statusCode": 400
}
403 Forbidden - Parent folder not owned
{
  "error": "Forbidden",
  "message": "Parent folder does not belong to you",
  "statusCode": 403
}
404 Not Found - Invalid parent
{
  "error": "Not Found",
  "message": "Parent folder not found",
  "statusCode": 404
}

​
Notes

  • Folder names are trimmed of whitespace before being saved
  • If you provide file IDs that don’t exist, the request will fail
  • Files must exist and be accessible before they can be added to a folder
  • Parent folders must belong to the authenticated user

Build docs developers (and LLMs) love

Get started for freeTalk to us