List All User Files and Folders — GET /api/files

Returns a list of files and folders belonging to the currently authenticated Clerk user. Pass a parentId to browse inside a specific folder, or omit it to retrieve root-level items where parentId IS NULL.

Request

Method: GET
Path: /api/files
Auth: Clerk session cookie required. The userId query parameter must match the authenticated session’s user ID — mismatches return 401.

Query Parameters

userId

string

required

The Clerk user ID of the authenticated user. Must exactly match the session’s userId; used to scope the database query and prevent cross-user data access.

parentId

string

UUID of the parent folder whose direct children you want to list. When omitted, only root-level items (where parentId IS NULL) are returned. Must be a valid UUID referencing an existing folder owned by the user.

Response

200 — Success

Returns a JSON object containing a files array. Each element is a FileItem record.

{
  "files": [
    {
      "id": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "vacation-photo.jpg",
      "path": "/storex/user_abc123/3f7a1b2c.jpg",
      "size": 2048576,
      "type": "image/jpeg",
      "fileUrl": "https://ik.imagekit.io/your_id/storex/user_abc123/3f7a1b2c.jpg",
      "thumbnailUrl": "https://ik.imagekit.io/your_id/tr:n-ik_ml_thumbnail/storex/user_abc123/3f7a1b2c.jpg",
      "userId": "user_abc123",
      "parentId": null,
      "isFolder": false,
      "isStarred": false,
      "isTrash": false,
      "createdAt": "2024-11-01T10:30:00.000Z",
      "updatedAt": "2024-11-01T10:30:00.000Z"
    }
  ]
}

files

FileItem[]

required

Array of file and folder records owned by the user. Empty array [] when no items exist at the requested level.

Show FileItem fields

string

UUID primary key of the file or folder record.

name

string

Original display name of the file or folder (e.g. "vacation-photo.jpg").

path

string

ImageKit storage path of the file (e.g. /storex/user_abc123/uuid.jpg).

size

number

File size in bytes. For folders this value is 0.

type

string

MIME type of the file (e.g. "image/jpeg", "application/pdf"). Folders use "folder".

fileUrl

string

Public ImageKit CDN URL to access or stream the file.

thumbnailUrl

string

ImageKit-generated thumbnail URL. May be null for PDF files or folders.

userId

string

Clerk user ID of the file owner.

parentId

string

UUID of the parent folder, or null if the item is at the root level.

isFolder

boolean

true if the record represents a folder; false for regular files.

isStarred

boolean

true if the user has starred this file.

isTrash

boolean

true if the file has been soft-deleted (moved to trash).

createdAt

string

ISO 8601 timestamp of when the record was created.

updatedAt

string

ISO 8601 timestamp of the most recent update.

Error Responses

Status	Error message	Cause
`401`	`"unauthorized"`	No active Clerk session, `userId` param is missing, or it doesn’t match the session user.
`500`	`"error fetching files"`	Unexpected database error while querying the `files` table.

Examples

curl -G https://your-app.vercel.app/api/files \
  -H "Cookie: __session=<clerk_session_token>" \
  --data-urlencode "userId=user_abc123"

Files API

Folders & Storage API

List All User Files and Folders — GET /api/files

Request

Query Parameters

Response

200 — Success

Error Responses

Examples

Build docs developers (and LLMs) love

Files API

Folders & Storage API

Documentation Index

​Request

​Query Parameters

​Response

​200 — Success

​Error Responses

​Examples

Build docs developers (and LLMs) love

Request

Query Parameters

Response

200 — Success

Error Responses

Examples