Skip to main content

​
Delete Folder

Permanently delete a folder and all its contents from your storage. This action cannot be undone.
Deleting a folder will permanently remove all files and subfolders within it. This action cannot be undone.

​
Endpoint

DELETE /folders/{folderId}

​
Path Parameters

ParameterTypeRequiredDescription
folderIdstringYesThe ID of the folder to delete

​
Query Parameters

ParameterTypeRequiredDescription
forcebooleanNoForce deletion even if folder contains files (default: false)
recursivebooleanNoDelete subfolders recursively (default: true)

​
Example Request

curl -X DELETE "https://api.astracollab.app/v1/folders/folder_1234567890abcdef" \
  -H "Authorization: Bearer your-api-key-here"

​
Response

{
  "success": true,
  "data": {
    "message": "Folder deleted successfully",
    "folderId": "folder_1234567890abcdef",
    "deletedFiles": 15,
    "deletedSubfolders": 3,
    "freedSpace": 52428800,
    "deletedAt": "2024-01-15T10:30:00Z"
  }
}

​
Error Responses

​
Folder Not Found

{
  "success": false,
  "error": {
    "code": "FOLDER_NOT_FOUND",
    "message": "Folder with ID 'folder_1234567890abcdef' not found"
  }
}

​
Folder Not Empty

{
  "success": false,
  "error": {
    "code": "FOLDER_NOT_EMPTY",
    "message": "Folder contains files and cannot be deleted",
    "details": {
      "fileCount": 15,
      "subfolderCount": 3
    }
  }
}

​
Access Denied

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You don't have permission to delete this folder"
  }
}

​
Folder in Use

{
  "success": false,
  "error": {
    "code": "FOLDER_IN_USE",
    "message": "Folder is currently being used and cannot be deleted",
    "details": {
      "reason": "Active file operations"
    }
  }
}

​
Force Delete

To delete a folder that contains files, use the force parameter: 
curl -X DELETE "https://api.astracollab.app/v1/folders/folder_1234567890abcdef?force=true" \
  -H "Authorization: Bearer your-api-key-here"

​
Non-Recursive Delete

To delete only the folder (not its contents), use recursive=false: 
curl -X DELETE "https://api.astracollab.app/v1/folders/folder_1234567890abcdef?recursive=false" \
  -H "Authorization: Bearer your-api-key-here"

​
Bulk Delete

To delete multiple folders at once:

​
Endpoint

DELETE /folders/bulk

​
Request Body

{
  "folderIds": [
    "folder_1234567890abcdef",
    "folder_0987654321fedcba",
    "folder_abcdef1234567890"
  ],
  "force": true,
  "recursive": true
}

​
Response

{
  "success": true,
  "data": {
    "deleted": [
      {
        "folderId": "folder_1234567890abcdef",
        "deletedFiles": 15,
        "deletedSubfolders": 3,
        "freedSpace": 52428800
      },
      {
        "folderId": "folder_0987654321fedcba",
        "deletedFiles": 8,
        "deletedSubfolders": 1,
        "freedSpace": 20971520
      }
    ],
    "failed": [
      {
        "folderId": "folder_abcdef1234567890",
        "reason": "Folder not found"
      }
    ],
    "totalFreedSpace": 73400320,
    "deletedAt": "2024-01-15T10:30:00Z"
  }
}

​
SDK Examples

curl -X DELETE "https://api.astracollab.app/v1/folders/folder_1234567890abcdef" \
  -H "Authorization: Bearer your-api-key-here"

​
Confirmation Dialog

Always show a confirmation dialog before deleting folders: 
const deleteFolderWithConfirmation = async (folderId, folderName, fileCount) => {
  const message = fileCount > 0 
    ? `Are you sure you want to delete "${folderName}" and all ${fileCount} files within it? This action cannot be undone.`
    : `Are you sure you want to delete "${folderName}"? This action cannot be undone.`;
  
  const confirmed = confirm(message);
  
  if (confirmed) {
    try {
      await deleteFolder(folderId, { force: true });
      console.log('Folder deleted successfully');
    } catch (error) {
      console.error('Failed to delete folder:', error);
    }
  }
};

​
Pre-deletion Check

Check folder contents before deletion: 
const checkFolderContents = async (folderId) => {
  const folder = await client.folders.get(folderId);
  const files = await client.files.list({ folderId });
  
  return {
    folder,
    fileCount: files.length,
    totalSize: files.reduce((sum, file) => sum + file.size, 0)
  };
};

​
Storage Impact

Deleting folders will immediately free up storage space and reduce your usage quota. The freed space is reported in the response.

​
Recovery

Some folders may be soft-deleted (moved to trash) instead of being permanently deleted. Check your organization settings for this behavior. Soft-deleted folders can be recovered within 30 days: 
// Recover a soft-deleted folder
await client.folders.recover('folder_1234567890abcdef');