Documentation

Delete File

Delete a file from your organization's storage

Delete File

Delete a file from your organization's storage. This operation permanently removes the file from both the database and storage. This action cannot be undone.

Endpoint

DELETE /api/uploads/files/{fileId}

Note: When using API key authentication, the organizationId query parameter is optional. The API automatically uses the organization associated with your API key.

Path Parameters

ParameterTypeRequiredDescription
fileIdstringYesUnique identifier of the file to delete

Request Example

curl -X DELETE "https://api.swiftia.io/api/uploads/files/file_123"

Response

Success Response (200)

{
  "id": "file_123",
  "deleted": true
}

Error Response (500)

If the deletion fails, the response includes error details:

{
  "id": "file_123",
  "deleted": false,
  "error": "Failed to delete file from storage"
}

Response Fields

FieldTypeDescription
idstringUnique identifier of the file that was attempted to be deleted
deletedbooleantrue if the file was successfully deleted, false otherwise
errorstring | undefinedError message if deletion failed (only present when deleted is false)

Error Responses

400 Bad Request

{
  "message": "Organization ID is required"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "message": "Organization ID mismatch. API key is bound to a different organization."
}

404 Not Found

{
  "message": "File not found"
}

This error occurs when:

  • The file ID doesn't exist
  • The file belongs to a different organization
  • The file has already been deleted

500 Internal Server Error

If the deletion fails (e.g., storage error), the response includes the error details:

{
  "id": "file_123",
  "deleted": false,
  "error": "Failed to delete file from storage"
}

Example Use Cases

Delete a Single File

async function deleteFile(apiKey, fileId) {
  const response = await fetch(
    `https://api.swiftia.io/api/uploads/files/${fileId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  const result = await response.json();
  
  if (result.deleted) {
    console.log(`File ${fileId} deleted successfully`);
    return true;
  } else {
    console.error(`Failed to delete file: ${result.error}`);
    return false;
  }
}

Delete Multiple Files

async function deleteMultipleFiles(apiKey, fileIds) {
  const results = await Promise.all(
    fileIds.map(fileId => deleteFile(apiKey, fileId))
  );
  
  const successCount = results.filter(r => r === true).length;
  console.log(`Deleted ${successCount} out of ${fileIds.length} files`);
  
  return results;
}

Delete Files by Tag

async function deleteFilesByTag(apiKey, tag) {
  // First, get all files with the tag
  const response = await fetch(
    `https://api.swiftia.io/api/uploads/files?tags=${tag}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  const data = await response.json();
  const fileIds = data.files.map(file => file.id);
  
  // Then delete all files with that tag
  return await deleteMultipleFiles(apiKey, fileIds);
}

Clean Up Old Files

async function cleanupOldFiles(apiKey, daysOld = 30) {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);
  
  // Get all files
  const response = await fetch(
    `https://api.swiftia.io/api/uploads/files?limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  const data = await response.json();
  
  // Filter files older than cutoff date
  const oldFiles = data.files.filter(file => {
    const fileDate = new Date(file.createdAt);
    return fileDate < cutoffDate;
  });
  
  // Delete old files
  const fileIds = oldFiles.map(file => file.id);
  return await deleteMultipleFiles(apiKey, fileIds);
}

Important Notes

Permanent Deletion

  • This action cannot be undone. Once a file is deleted, it is permanently removed from both the database and storage.
  • Make sure you have a backup or don't need the file before deleting it.

Storage Impact

  • Deleting files will free up storage space in your organization
  • The freed space will be reflected in the storage statistics on the next file list request

Organization Isolation

  • API keys are bound to specific organizations
  • You can only delete files belonging to your organization
  • Attempting to delete files from other organizations will result in a 404 error

Error Handling

  • Always check the deleted field in the response
  • If deleted is false, check the error field for details
  • Handle 404 errors gracefully (file may have already been deleted)
  • Retry failed deletions if appropriate for your use case

Rate Limiting

This endpoint is subject to rate limiting based on your subscription plan. Please refer to the Rate Limiting documentation for details.

  • Get Files - List all files with pagination
  • Get File - Get details of a specific file