Breadcrumbs

4. Folder Navigation and Discovery

Folder Navigation and Discovery

This scenario demonstrates how to navigate and discover folders within the Circularo platform. Effective folder navigation is essential for traversing complex folder hierarchies and locating the organizational structures where your documents are stored.

Key features:

  • Discover folders at different levels of the folder hierarchy

  • Navigate through nested folder structures

  • Find subfolders within specific parent folders

  • Efficiently traverse complex organizational structures

Prerequisites

Before navigating folder structures, you need:

  • A valid authentication token (see the "Authentication & Security" section for details)

  • Appropriate permissions to access the folders you want to discover

Folder navigation is particularly important in organizations with complex document hierarchies. Understanding how to traverse these structures enables efficient document management and retrieval.

Step 1 - Discover root-level folders

This endpoint searches for folders at the root level of the folder hierarchy. Root-level folders are the top-level organizational containers in your Circularo instance.

  • The type: "folder" parameter restricts the search to only folder objects

  • The folder.folder: null parameter specifies to search at the root level

  • The allowFolders: true parameter is required when searching for folders

  • The response includes all root-level folders the user has access to

Root-level folders are the starting point for navigating your folder hierarchy.

Endpoint

POST /search

Request

JSON
POST /search?token=jdSbgXG4fR1b24iuuyIBd7gNwOcc2DAWEbpVeXIfmVPMalqOknWhv31L6myZBzLy

Content-Type: application/json

{
  "allowFolders": true,
  "type": "folder",  //Search folders only
  "folder": {
    "folder": null  //Search at the root level
  },
  "from": 0,
  "size": 100
}

Response

JSON
{
  "results": [
    {
      "document": {
        "isFolder": true,
        "folderId": "e05ce4ec-3aff-442c-94a2-987e62fb87f1",
        "type": "folder",
        "documentTitle": "Completed Documents",
        "folder": {
          "user": {  //Either \"user\" or \"global\" object
            "level": 0,
            "parentFolderId": null,
            ...
          }
        },
        ...
      }
    },
    ...
  ],
  "total": 12,
  ...
}

The response includes root-level folders that the user has access to.

  • Each folder in the results includes its metadata and hierarchical information

  • The folder.user.level field indicates the folder's depth in the hierarchy (0 for root level)

  • The folder.user.parentFolderId field is null for root-level folders

  • The total count indicates how many root-level folders are available

Use the folder IDs from this response to navigate deeper into the folder hierarchy or to place documents in specific folders.

Step 2 - Discover subfolders within a parent folder

This endpoint searches for subfolders within a specific parent folder. This allows you to navigate down the folder hierarchy and discover nested organizational structures.

  • The type: "folder" parameter restricts the search to only folder objects

  • The folder.folder parameter specifies which parent folder to search within

  • The allowFolders: true parameter is required when searching for folders

  • The response includes all subfolders within the specified parent folder

Traversing folder hierarchies is essential for navigating complex organizational structures. This endpoint allows you to "drill down" into nested folders to find the exact location you need.

Endpoint

POST /search

Request

JSON
POST /search?token=jdSbgXG4fR1b24iuuyIBd7gNwOcc2DAWEbpVeXIfmVPMalqOknWhv31L6myZBzLy

Content-Type: application/json

{
  "allowFolders": true,
  "type": "folder",  //Search folders only
  "folder": {
    "folder": "e05ce4ec-3aff-442c-94a2-987e62fb87f1"  //Search inside the specified folder
  },
  "from": 0,
  "size": 100
}

Response

JSON
{
  "results": [
    {
      "document": {
        "isFolder": true,
        "folderId": "2d70d8c8-2c32-42df-9f98-96f6298aa457",
        "type": "folder",
        "documentTitle": "Invoices",
        "folder": {
          "user": {  //Either \"user\" or \"global\" object
            "level": 1,
            "parentFolderId": "e05ce4ec-3aff-442c-94a2-987e62fb87f1",
            ...
          }
        },
        ...
      }
    },
    ...
  ],
  "total": 9,
  ...
}

The response includes all subfolders within the specified parent folder.

  • Each subfolder in the results includes its metadata and hierarchical information

  • The folder.user.level field indicates the folder's depth in the hierarchy

  • The folder.user.parentFolderId field shows which folder contains this subfolder

  • The total count indicates how many subfolders exist within the parent folder

You can continue traversing the folder hierarchy by using the folder IDs from this response in subsequent requests, allowing you to navigate to any depth in your folder structure.

Folder Navigation Summary

You have successfully learned how to navigate and discover folders within the Circularo system.

Key Concepts

  • Folder Hierarchy: A tree-like structure of folders organized in parent-child relationships

  • Root-Level Folders: Top-level folders that serve as the starting point for navigation

  • Subfolders: Nested folders contained within parent folders

  • Folder Discovery: The process of finding folders at different levels of the hierarchy

  • Top-Down Navigation: Start at the root level and drill down into specific subfolders

  • Direct Access: Jump directly to a specific folder using its ID

  • Breadcrumb Navigation: Use parent folder IDs to navigate up the hierarchy

  • Folder Filtering: Combine folder navigation with search criteria to find specific content

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 navigation example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key

async function navigateFolderHierarchy() {
    try {
        // Step 1: Discover root-level folders
        const rootFoldersResponse = await fetch(`${URL}${API_PATH}/search?token=${TOKEN}`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                allowFolders: true,
                type: "folder",
                folder: {
                    folder: null  // null indicates root level
                },
                from: 0,
                size: 100
            })
        });
        if (!rootFoldersResponse.ok) {
            throw new Error(`Failed to retrieve root folders: ${rootFoldersResponse.status} ${rootFoldersResponse.statusText}`);
        }

        const rootFoldersData = await rootFoldersResponse.json();
        console.log(`Found ${rootFoldersData.total} root-level folders`);

        // Display root folders
        rootFoldersData.results.forEach(result => {
            console.log(`Root Folder: ${result.document.documentTitle} (ID: ${result.document.folderId})`);
        });

        // Step 2: Select a root folder and discover its subfolders
        if (rootFoldersData.results.length > 0) {
            const selectedRootFolder = rootFoldersData.results[0].document.folderId;

            const subFoldersResponse = await fetch(`${URL}${API_PATH}/search?token=${TOKEN}`, {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    allowFolders: true,
                    type: "folder",
                    folder: {
                        folder: selectedRootFolder
                    },
                    from: 0,
                    size: 100
                })
            });
            if (!subFoldersResponse.ok) {
                throw new Error(`Failed to retrieve subfolders: ${subFoldersResponse.status} ${subFoldersResponse.statusText}`);
            }

            const subFoldersData = await subFoldersResponse.json();
            console.log(`Found ${subFoldersData.total} subfolders in the selected root folder`);

            // Display subfolders
            subFoldersData.results.forEach(result => {
                console.log(`  Subfolder: ${result.document.documentTitle} (ID: ${result.document.folderId})`);
            });

            // Continue traversing deeper if needed
            if (subFoldersData.results.length > 0) {
                const selectedSubFolder = subFoldersData.results[0].document.folderId;

                // You can continue the pattern to navigate to any depth
                // by using the folder ID in subsequent requests
            }
        }
    } catch (error) {
        console.error('Error navigating folder hierarchy:', error.message);
    }
}