6. Folder Deletion

Folder Deletion

This scenario demonstrates how to delete folders and their contents in the Circularo platform. Folder deletion is a powerful operation that removes both the folder structure and all documents contained within it.

Key features:

Delete folders and all their contents in a single operation
Permanently remove folder hierarchies when no longer needed
Clean up organizational structures efficiently
Remove both the folder and all documents it contains

Prerequisites

Before deleting folders, you need:

A valid authentication token (see the "Authentication & Security" section for details)
The folder ID of the folder you want to delete
Edit permissions for the folder and all documents within it
Careful consideration, as folder deletion cannot be undone when using hard delete

Folder deletion is a permanent operation when using the hardDelete option. All documents within the folder will also be permanently deleted. Make sure you have appropriate backups before proceeding.

Step 1 - Delete a folder and its contents

This endpoint deletes a folder and all documents contained within it. In Circularo, folders are treated as special document types, so the deletion is performed using the document deletion endpoint.

The documents array contains the folder ID to delete
The hardDelete parameter set to true permanently removes the folder and its contents
All documents within the folder are also deleted in the same operation
Nested folders within the target folder are also removed recursively

The user must have edit permissions for the folder and all documents within it to successfully delete the folder.

Endpoint

CODE

DELETE /documents

Request

JSON

DELETE /documents?token=0hNekm38YxwaQpHDmLzvkUTpORatVs98BOD7HUNpgTZkQd527xPDH0VSiBAzRWzJ&___descriptionBelow225___=Set%20to%20true%20for%20permanent%20deletion&hardDelete=true

Content-Type: application/json

{
  "documents": [
    {
      "id": "6afed875-67fc-4b53-ba4c-5992d4a26e69"  //ID of the folder to delete
    }
  ]
}

Response

JSON

{
  "errors": false,
  "count": 1,
  "items": []
}

The folder and all its contents have been successfully deleted.

The folder structure has been removed from the system
All documents contained within the folder have been deleted

Folder Deletion Summary

You have successfully learned how to delete folders and their contents in the Circularo system.

Key Concepts

Folder Deletion: Removes both the folder structure and all documents it contains
Recursive Deletion: Automatically removes all nested folders and their contents
Permission Requirements: User must have edit rights to the folder and all its contents

Best Practices

Always verify the folder contents before deletion to avoid unintended data loss
Consider exporting important folder contents before deletion for backup purposes
Implement proper confirmation steps in your user interface before triggering folder deletion

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT

// Folder deletion example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key
const FOLDER_ID = "YOUR_FOLDER_ID"; // ID of the folder you want to delete

try {
    // Delete the folder and all its contents
    const deleteResponse = await fetch(`${URL}${API_PATH}/documents?token=${TOKEN}&hardDelete=true`, {
        method: 'DELETE',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            documents: [
                { id: FOLDER_ID }
            ]
        })
    });
    if (!deleteResponse.ok) {
        throw new Error(`Folder deletion failed: ${deleteResponse.status} ${deleteResponse.statusText}`);
    }

    const deleteResult = await deleteResponse.json();

    if (deleteResult.errors === false) {
        console.log(`Successfully deleted folder and ${deleteResult.count} item(s)`);
    } else {
        console.error('Some items could not be deleted:', deleteResult.items);
    }

} catch (error) {
    console.error('Error deleting folder:', error.message);
}