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.

Reads the current isTrash value of the specified file and atomically flips it (false → true to trash, true → false to restore). This is a soft-delete operation — no data is removed from ImageKit CDN and the database record remains intact and fully recoverable.
Toggling isTrash back to false fully restores the file — it reappears in the user’s file browser as if it was never trashed. To permanently delete a file and remove it from ImageKit CDN, use DELETE /api/files/[fileId] instead.

​
Request

Method: PATCH
Path: /api/files/{fileId}/trash
Content-Type: application/json
Auth: Clerk session cookie required. The userId body field must match the session’s user ID.

​
Path Parameters

​
fileId
string
required
UUID of the file or folder whose trash status should be toggled. Must belong to the authenticated user; otherwise a 404 is returned.

​
Request Body

​
userId
string
required
The Clerk user ID of the authenticated user. Must match the session’s userId exactly. Checked before any database operation is performed. The desired trash state is not accepted as a parameter — the endpoint always toggles the current database value.
{
  "userId": "user_abc123"
}

​
Response

​
200 — Success

Returns the full updated FileItem object with the toggled isTrash value applied. The response is the raw record, not wrapped in a container object. 
{
  "id": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "name": "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": true,
  "createdAt": "2024-11-01T10:30:00.000Z",
  "updatedAt": "2024-11-05T14:00:00.000Z"
}
​
id
string
UUID primary key of the file or folder.
​
name
string
Display name of the file or folder.
​
path
string
ImageKit storage path. Unchanged by this operation.
​
size
number
File size in bytes (0 for folders).
​
type
string
MIME type of the file (e.g. "image/jpeg", "application/pdf").
​
fileUrl
string
Public ImageKit CDN URL. The file remains accessible via this URL even while trashed — the flag only controls UI visibility.
​
thumbnailUrl
string
ImageKit-generated thumbnail URL. May be null.
​
userId
string
Clerk user ID of the file owner.
​
parentId
string
UUID of the parent folder, or null if at root.
​
isFolder
boolean
true if the record represents a folder.
​
isStarred
boolean
Current star status, unchanged by this endpoint.
​
isTrash
boolean
The toggled trash status — the new persisted value after the PATCH. true means the file is in the trash; false means it has been restored.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 timestamp of the most recent update.

​
Error Responses

StatusError messageCause
400"File id is required"The fileId path parameter is missing or empty.
401"Unauthorized"No active Clerk session, or userId body field doesn’t match the session user.
404"File not found"No file with that UUID exists for this user.
500"Failed to mark file as trash"Unexpected database error during the update.

​
Examples

curl -X PATCH https://your-app.vercel.app/api/files/3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c/trash \
  -H "Cookie: __session=<clerk_session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc123" }'
Because the endpoint toggles the current database value, trashing and restoring a file both use the exact same request — no separate restore endpoint is needed. Just call PATCH /api/files/{fileId}/trash again to undo.

Build docs developers (and LLMs) love

Get started for freeTalk to us