Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nayalsaurav/Storx/llms.txt

Use this file to discover all available pages before exploring further.

POST /api/folders/create creates a new folder record in the Storx database for the authenticated user. Folders share the same files table as regular files, distinguished by the isFolder: true flag. No file is uploaded to storage — only a database record is created.

​
Request

PropertyValue
MethodPOST
Path/api/folders/create
AuthClerk session required
Content-Typeapplication/json

​
Body Parameters

​
name
string
required
Display name for the folder. Must be a non-empty string. Leading and trailing whitespace is trimmed before the record is saved.
​
userId
string
required
The Clerk user ID of the requesting user. Must exactly match the authenticated session’s user ID — a mismatch returns 401 Unauthorized.
​
parentId
string | null
UUID of the parent folder to nest this folder under. Pass null (or omit the field) to create a root-level folder. When provided, the API verifies that the parent exists, belongs to the authenticated user, and is itself a folder.

​
Behavior

  1. Authentication check — Reads the Clerk session. Returns 401 if no session is present.
  2. User ID validation — Compares body.userId against the session userId. Returns 401 if they do not match.
  3. Name validation — Verifies that name is a non-empty string after trimming. Returns 400 if the check fails.
  4. Parent folder verification — When parentId is provided, queries the files table for a record matching id = parentId, userId = userId, and isFolder = true. Returns 404 if no such record is found.
  5. Record creation — Inserts a row into the files table with the following fixed values:
    • isFolder: true
    • size: 0
    • type: "folder"
    • fileUrl: ""
    • thumbnailUrl: null
    • imagekitFileId: null
    • isStarred: false
    • isTrash: false
    • A path of the form /folder/<userId>/<uuid>.

​
Response

​
200 — Success

{
  "success": true,
  "message": "folder created successfully",
  "folder": { ... }
}
​
success
boolean
Always true on a successful response.
​
message
string
Human-readable confirmation string: "folder created successfully".
​
folder
object
The newly created folder record returned directly from the database.

​
Error Responses

StatusError messageCause
400folder name is requiredname is missing, not a string, or is an empty / whitespace-only string.
401unauthorizedNo active Clerk session, or body.userId does not match the authenticated session ID.
404Parent folder not foundparentId was provided but no matching folder exists for this user.
500Internal Server ErrorAn unexpected database or runtime error occurred.

​
Examples

curl -X POST https://your-app.vercel.app/api/folders/create \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk_session_token>" \
  -d '{"name": "My Project", "userId": "user_xxx", "parentId": null}'

​
Creating a nested folder

To create a folder inside an existing folder, pass the parent folder’s UUID as parentId: 
const response = await fetch('/api/folders/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Design Assets',
    userId: 'user_xxx',
    parentId: '3f1e2d4c-abcd-1234-efgh-000000000000',
  }),
});
Folders can be nested to any depth. The API only validates the immediate parent — it does not traverse the full ancestor chain.

Build docs developers (and LLMs) love

Get started for freeTalk to us