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.

Permanently removes a file record from the database and its corresponding asset from ImageKit CDN. The endpoint validates the Clerk session, verifies ownership, purges the file from storage, then deletes the database record. This action cannot be undone.
This is a permanent, irreversible deletion. The file is removed from both the Storx database and the ImageKit CDN simultaneously. There is no recovery path after a successful response. If you want a reversible soft-delete, use PATCH /api/files/[fileId]/trash instead.
The CDN deletion call passes the database record’s UUID (fileId) directly to imagekit.deleteFile(). ImageKit’s delete API expects its own internal file ID (stored in the imagekitFileId column), not the Storx database UUID. If these values differ, the CDN asset may not be fully purged even though the database record is removed.

​
Request

Method: DELETE
Path: /api/files/{fileId}
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 to delete. Must reference a file that exists in the database and is owned by 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; mismatches return 401 before any database or CDN operations occur.
{
  "userId": "user_abc123"
}

​
Response

​
200 — Success

Returns a confirmation message and the snapshot of the deleted FileItem record as it existed immediately before deletion. 
{
  "message": "File deleted successfully",
  "deletedFile": {
    "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": false,
    "createdAt": "2024-11-01T10:30:00.000Z",
    "updatedAt": "2024-11-05T14:00:00.000Z"
  }
}
​
message
string
required
Human-readable confirmation string. Always "File deleted successfully" on success.
​
deletedFile
FileItem
required
A snapshot of the deleted file’s database record, returned by the RETURNING clause before the row is dropped.

​
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 or you don't have permission to delete it"No file with that UUID exists for this user.
500"Internal server error"Unexpected server, database, or ImageKit error during deletion.

​
Examples

curl -X DELETE https://your-app.vercel.app/api/files/3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Cookie: __session=<clerk_session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc123" }'
The deletion sequence is: ImageKit CDN first, then the database record. If the ImageKit call succeeds but the database deletion fails, a 500 is returned — the CDN asset will already have been removed in that case.

Build docs developers (and LLMs) love

Get started for freeTalk to us