3. Folder Information and Content

Folder Information and Content

This scenario demonstrates how to retrieve folder information and search for documents within specific folders in the Circularo platform. Understanding how to access folder details and content is essential for effective document management and navigation.

Key features:

Retrieve detailed information about folders including their position in the hierarchy
Search for documents contained within specific folders
Filter folder content with additional search criteria
Navigate complex folder structures efficiently

Prerequisites

Before working with folder information and content, you need:

A valid authentication token (see the "Authentication & Security" section for details)
The folder ID of the folder you want to examine
Appropriate permissions to access the folder and its contents

Folder IDs can be obtained when creating folders or through the search endpoint (see the next scenario). Once you have a folder ID, you can retrieve its details and search for documents within it.

Step 1 - Get folder info

This endpoint retrieves detailed information about a specific folder using its folder ID. The information includes the folder's metadata, position in the folder hierarchy, and access rights.

The folderId parameter in the URL path specifies which folder to retrieve
The response includes the folder's name, type, and hierarchical position
The folder's parent-child relationships are included in the response
Access control information is provided to understand who can view or modify the folder

This endpoint only retrieves folder metadata and does not return the folder's contents. To get the documents within a folder, use the search endpoint with folder filtering as shown in the next step.

Endpoint

CODE

GET /folders/dd535701-e4de-435b-a465-d9a9ce9e27d4

Request

JSON

GET /folders/dd535701-e4de-435b-a465-d9a9ce9e27d4?token=Ovf0dztvRmvvOaVeNjIBQaQefYcSMkMFtReMS59j89gJ6b0f1dfWEZ0z5WDX6OId

Response

JSON

{
  "documentTitle": "Invoices",
  "isFolder": true,
  "folderId": "dd535701-e4de-435b-a465-d9a9ce9e27d4",
  "type": "folder",
  "folder": {
    "user": {
      "level": 1,
      "parentFolderId": "59f23abb-cec7-4098-9ac1-9d9aa4c87ff2",
      ...
    },
    ...
  },
  ...
}

The response includes comprehensive information about the requested folder.

The documentTitle field contains the folder's display name
The isFolder and type fields confirm this is a folder object
The folder.user.level indicates the depth of the folder in the hierarchy (0 for root, 1 for first level, etc.)
The folder.user.parentFolderId shows which folder contains this folder

Use the parentFolderId to navigate up the folder hierarchy, which is useful for implementing breadcrumb navigation in user interfaces.

Step 2 - Search folder content

This endpoint searches for documents within a specific folder. It uses the standard search endpoint with folder filtering to find documents that are located in the specified folder.

The folder.folder parameter specifies which folder to search in
The allowFolders parameter determines whether to include subfolders in the results
The from and size parameters control pagination of the results
Additional search criteria can be combined with folder filtering for more specific queries

This endpoint leverages the powerful search capabilities of Circularo, allowing you to combine folder filtering with other search criteria such as document type, creation date, or content keywords.

Endpoint

CODE

POST /search

Request

JSON

POST /search?token=Ovf0dztvRmvvOaVeNjIBQaQefYcSMkMFtReMS59j89gJ6b0f1dfWEZ0z5WDX6OId

Content-Type: application/json

{
  "allowFolders": false,  //True to search nested folders as well
  "folder": {
    "folder": "dd535701-e4de-435b-a465-d9a9ce9e27d4"
  },
  "from": 0,
  "size": 100
}

Response

JSON

{
  "results": [
    {
      "document": {
        "documentId": "748d5ff7-8fcc-48fd-a457-3b5aa2b46f54",
        "documentTitle": "Invoice 2023-001",
        "folder": {
          "user": {  //Either \"user\" or \"global\" object
            "level": 2,
            "parentFolderId": "dd535701-e4de-435b-a465-d9a9ce9e27d4",
            ...
          }
        },
        ...
      }
    },
    ...
  ],
  "total": 63,
  ...
}

The response includes all documents located in the specified folder that match the search criteria.

The results array contains the documents found in the folder
Each document includes its metadata and folder information
The document.folder.user.parentFolderId confirms which folder contains the document
The total number of matching documents is included for pagination purposes

To search in a folder and all its subfolders, set the allowFolders parameter to true. This is useful for finding documents in complex folder hierarchies.

Folder Information and Content Summary

You have successfully learned how to retrieve folder information and search for documents within specific folders in the Circularo system.

Key Concepts

Folder Information: Metadata about folders including their position in the hierarchy
Folder Content: Documents contained within a specific folder
Folder Hierarchy: Parent-child relationships between folders
Folder Filtering: Limiting search results to documents within specific folders

Common Use Cases

Folder Navigation: Building user interfaces that allow browsing through folder structures
Document Organization: Finding documents within specific organizational categories
Content Management: Managing related documents grouped in folders
Access Control: Understanding folder permissions and visibility

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 information and content 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 examine

try {
    // Step 1: Get folder information
    const folderInfoResponse = await fetch(`${URL}${API_PATH}/folders/${FOLDER_ID}?token=${TOKEN}`);
    if (!folderInfoResponse.ok) {
        throw new Error(`Failed to retrieve folder info: ${folderInfoResponse.status} ${folderInfoResponse.statusText}`);
    }

    const folderInfo = await folderInfoResponse.json();
    console.log(`Folder name: ${folderInfo.documentTitle}`);
    console.log(`Folder level: ${folderInfo.folder.user.level}`);

    // If this is a nested folder, you can navigate to its parent
    if (folderInfo.folder.user.parentFolderId) {
        console.log(`Parent folder ID: ${folderInfo.folder.user.parentFolderId}`);
    }

    // Step 2: Search for documents in the folder
    const searchResponse = await fetch(`${URL}${API_PATH}/search?token=${TOKEN}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            allowFolders: false, // Set to true to include subfolders
            folder: {
                folder: FOLDER_ID
            },
            from: 0,
            size: 100
            // You can add additional search criteria here
        })
    });
    if (!searchResponse.ok) {
        throw new Error(`Folder content search failed: ${searchResponse.status} ${searchResponse.statusText}`);
    }

    const searchResults = await searchResponse.json();
    console.log(`Found ${searchResults.total} documents in the folder`);

    // Process the documents in the folder
    searchResults.results.forEach(result => {
        console.log(`Document: ${result.document.documentTitle} (ID: ${result.document.documentId})`);
    });

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