Deleting Files

deleteFile

Delete a file by its storage key. The key is returned in the UploadResult from client.upload().

import { createUploadKit } from '@uploadkitdev/core';

const client = createUploadKit({ apiKey: 'uk_live_xxxxxxxxxxxxxxxxxxxxx' });

// Upload a file and capture the result
const result = await client.upload({ file, route: 'imageUploader' });

// Later: delete it using its storage key
await client.deleteFile(result.key);

The method returns Promise<void> and resolves when the file has been permanently removed from storage.

deleteFiles

Delete multiple files in one API request. This is the recommended path for cleanup jobs, gallery removals, or replacing several generated images at once.

const result = await client.deleteFiles([
  '65f0.../imageUploader/abc123.../photo.jpg',
  '65f0.../imageUploader/def456.../avatar.webp',
]);

console.log(result.deleted, result.failed, result.reclaimedBytes);

deleteFiles() accepts 1–100 keys per request and returns per-key failures instead of throwing when only part of the batch fails.

const result = await client.deleteFiles(keys);

for (const failure of result.failures) {
  console.warn(failure.key, failure.code, failure.message);
}

Use deleteFiles() instead of calling deleteFile() in a tight loop. It avoids spending one rate-limit point per file and keeps bulk cleanup predictable.

Extracting the key from UploadResult

The key property on UploadResult is the storage path within the bucket — it uniquely identifies the file and is what you store in your database for future deletion.

// UploadResult shape:
// {
//   id: string       — UploadKit file ID
//   key: string      — storage key (e.g. 'imageUploader/abc123/photo.jpg')
//   name: string     — original filename
//   size: number     — bytes
//   type: string     — MIME type
//   url: string      — CDN URL
//   status: string   — 'completed'
//   createdAt: string
// }

// Store the key in your database alongside the CDN URL:
await db.files.create({
  key: result.key,
  url: result.url,
  userId: session.user.id,
});

// Later, when the user requests deletion:
await client.deleteFile(fileRecord.key);
await db.files.delete({ id: fileRecord.id });

Error handling

import { createUploadKit, UploadKitError } from '@uploadkitdev/core';

try {
  await client.deleteFile(key);
} catch (err) {
  if (err instanceof UploadKitError) {
    if (err.statusCode === 404) {
      console.log('File not found — may have already been deleted');
    } else {
      console.error(`Delete failed: [${err.code}] ${err.message}`);
    }
  } else {
    throw err;
  }
}

Deletion is permanent and cannot be undone. The file is removed from storage and the CDN. Any existing CDN URLs for the file will stop resolving.

Listing files before deletion

Use client.listFiles() to browse files if you do not have the key stored:

const { files } = await client.listFiles({ limit: 50 });

for (const file of files) {
  console.log(file.key, file.name, file.url);
}

// Delete selected files in one request
await client.deleteFiles(files.slice(0, 10).map((file) => file.key));

See the API reference for the full listFiles signature.