Skip to content

Folder API

The Folder API manages the hierarchical organization of content in the Unique AI knowledge base.

Overview

Organize content into folder structures with:

  • Folder creation and management
  • Access control
  • Ingestion configuration
  • Path-based or ID-based operations

Methods

unique_sdk.Folder.get_info - Get folder information

Get folder information by scope ID or path.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)

Returns:

Returns a FolderInfo object.

Example - By Scope ID:

1
2
3
4
5
folder = unique_sdk.Folder.get_info(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_w78wfn114va9o22s13r03yq"
)

By Path:

1
2
3
4
5
folder = unique_sdk.Folder.get_info(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/Atlas/Due Diligence/Arch"
)
unique_sdk.Folder.get_folder_path - Get folder path

Compatibility

Compatible with release >.48

Get the complete folder path for a scope ID.

Parameters:

  • scope_id (str, required) - Folder scope ID

Returns:

Returns a FolderPathResponse object.

Example:

1
2
3
4
5
6
7
path = unique_sdk.Folder.get_folder_path(
    user_id=user_id,
    company_id=company_id,
    scope_id="scope_w78wfn114va9o22s13r03yq"
)

print(path)  # "/company/subfolder1/subfolder2"
unique_sdk.Folder.get_infos - Get paginated folders list

Get paginated list of folders, optionally filtered by parent.

Parameters:

  • parentId (str, optional) - Parent folder ID (if not provided, returns root folders)
  • skip (int, optional) - Number of folders to skip (default: 0)
  • take (int, optional) - Number of folders to return

Returns:

Returns a FolderInfos object.

Example - Get All Root Folders:

1
2
3
4
5
6
folders = unique_sdk.Folder.get_infos(
    user_id=user_id,
    company_id=company_id,
    take=10,
    skip=0
)

Get Subfolders:

1
2
3
4
5
6
7
subfolders = unique_sdk.Folder.get_infos(
    user_id=user_id,
    company_id=company_id,
    parentId="scope_s18seqpnltf35niydg77xgyp",
    take=10,
    skip=0
)
unique_sdk.Folder.create_paths - Create folder paths

Create multiple folder paths at once. Creates missing folders in the path.

Parameters:

  • paths (List[str], required) - List of folder paths to create
  • inheritAccess (bool, optional) - Whether to inherit access permissions from parent folders (default: True)

Returns:

Returns a CreateFolderStructureResponse object.

Example - Basic Creation:

1
2
3
4
5
6
7
8
9
unique_sdk.Folder.create_paths(
    user_id=user_id,
    company_id=company_id,
    paths=[
        "/Company/Reports/Q1",
        "/Company/Reports/Q2",
        "/Company/Policies"
    ]
)

Without Inheriting Access:

1
2
3
4
5
6
7
8
9
unique_sdk.Folder.create_paths(
    user_id=user_id,
    company_id=company_id,
    paths=[
        "/Company/Reports/Q1",
        "/Company/Reports/Q2"
    ],
    inheritAccess=False
)
unique_sdk.Folder.update - Update folder properties

Update folder properties: name or parent folder.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)
  • name (str, optional) - New folder name
  • parentId (str | None, optional) - New parent folder ID (use None to move to root)
  • parentFolderPath (str, optional) - New parent folder path

Returns:

Returns a Folder object.

Example - Move to New Parent by Path:

1
2
3
4
5
6
unique_sdk.Folder.update(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_dwekjnf3330woioppm",
    parentFolderPath="/Company/folder1/folder2"
)

Move and Rename:

1
2
3
4
5
6
7
unique_sdk.Folder.update(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/folder1",
    parentId="scope_dweekjrfhirtuhgroppm",
    name="January"
)

Move to Root:

1
2
3
4
5
6
7
unique_sdk.Folder.update(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/folder1",
    parentId=None,  # Move to root
    name="January"
)
unique_sdk.Folder.delete - Delete folder

Compatibility

Compatible with release >.36

Delete a folder by scope ID or path.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)
  • recursive (bool, optional) - Delete subfolders and contents (like rm -rf)

Returns:

Returns a DeleteResponse object.

Example - Non-Recursive Delete (Empty Folders Only):

1
2
3
4
5
unique_sdk.Folder.delete(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/Atlas/Due Diligence/Arch"
)

Recursive Delete:

1
2
3
4
5
6
7
8
9
result = unique_sdk.Folder.delete(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_w78wfn114va9o22s13r03yq",
    recursive=True
)

print(f"Deleted: {result.successFolders}")
print(f"Failed: {result.failedFolders}")
unique_sdk.Folder.update_ingestion_config - Update ingestion config

Update ingestion configuration for a folder and optionally its subfolders.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)
  • ingestionConfig (IngestionConfig, required) - Ingestion configuration. See Folder.IngestionConfig for structure.
  • applyToSubScopes (bool, required) - Whether to apply config to subfolders

Returns:

Returns a Folder object.

Example - By Scope ID:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
unique_sdk.Folder.update_ingestion_config(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_qbnkde820dbmuw2900",
    ingestionConfig={
        "uniqueIngestionMode": "INGESTION",
        "chunkStrategy": "UNIQUE_DEFAULT_CHUNKING",
        "chunkMaxTokens": 1000
    },
    applyToSubScopes=True
)

By Path:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
unique_sdk.Folder.update_ingestion_config(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/folder1/folder2",
    ingestionConfig={
        "uniqueIngestionMode": "INGESTION",
        "chunkStrategy": "UNIQUE_DEFAULT_CHUNKING"
    },
    applyToSubScopes=True
)
unique_sdk.Folder.add_access - Grant access permissions

Grant access permissions to a folder.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)
  • scopeAccesses (List[ScopeAccess], required) - List of access permissions. See Folder.ScopeAccess for structure.
  • applyToSubScopes (bool, required) - Whether to apply access to subfolders

Returns:

Returns a Folder object.

Example - Add Group Access:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
unique_sdk.Folder.add_access(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_231e4kjn4foffww34",
    scopeAccesses=[
        {
            "entityId": "group_id",
            "type": "WRITE",  # or "READ"
            "entityType": "GROUP"  # or "USER"
        }
    ],
    applyToSubScopes=True
)

By Path:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
unique_sdk.Folder.add_access(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/folder1/folder2",
    scopeAccesses=[
        {
            "entityId": "group_id",
            "type": "WRITE",
            "entityType": "GROUP"
        }
    ],
    applyToSubScopes=True
)
unique_sdk.Folder.remove_access - Revoke access permissions

Revoke access permissions from a folder.

Parameters:

  • scopeId (str, optional) - Folder scope ID (required if folderPath not provided)
  • folderPath (str, optional) - Folder path (required if scopeId not provided)
  • scopeAccesses (List[ScopeAccess], required) - List of access permissions to remove. See Folder.ScopeAccess for structure.
  • applyToSubScopes (bool, required) - Whether to remove access from subfolders

Returns:

Returns a Folder object or dict.

Example - By Scope ID:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
unique_sdk.Folder.remove_access(
    user_id=user_id,
    company_id=company_id,
    scopeId="scope_dwekjnf3330woioppm",
    scopeAccesses=[
        {
            "entityId": "group_id",
            "type": "WRITE",
            "entityType": "GROUP"
        }
    ],
    applyToSubScopes=True
)

By Path:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
unique_sdk.Folder.remove_access(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/folder1/folder2",
    scopeAccesses=[
        {
            "entityId": "group_id",
            "type": "WRITE",
            "entityType": "GROUP"
        }
    ],
    applyToSubScopes=True
)

Use Cases

Organize Knowledge Base 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Create department structure
departments = [
    "/Company/Engineering/Backend",
    "/Company/Engineering/Frontend",
    "/Company/Sales/NA",
    "/Company/Sales/EU",
    "/Company/HR/Policies"
]

unique_sdk.Folder.create_paths(
    user_id=user_id,
    company_id=company_id,
    paths=departments
)

# Configure ingestion for engineering docs
unique_sdk.Folder.update_ingestion_config(
    user_id=user_id,
    company_id=company_id,
    folderPath="/Company/Engineering",
    ingestionConfig={
        "uniqueIngestionMode": "INGESTION",
        "chunkStrategy": "UNIQUE_DEFAULT_CHUNKING",
        "chunkMaxTokens": 1500  # Larger chunks for technical docs
    },
    applyToSubScopes=True
)
Bulk Permission Management 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def grant_team_access(team_id, folder_paths):
    """Grant team access to multiple folders."""
    for path in folder_paths:
        try:
            unique_sdk.Folder.add_access(
                user_id=user_id,
                company_id=company_id,
                folderPath=path,
                scopeAccesses=[{
                    "entityId": team_id,
                    "type": "READ",
                    "entityType": "GROUP"
                }],
                applyToSubScopes=True
            )
            print(f"✓ Access granted: {path}")
        except Exception as e:
            print(f"✗ Failed: {path} - {e}")

grant_team_access("group_sales_team", [
    "/Company/Sales",
    "/Company/Marketing"
])
Navigate Folder Tree 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
def list_folder_tree(parent_id=None, indent=0):
    """Recursively list folder structure."""
    folders = unique_sdk.Folder.get_infos(
        user_id=user_id,
        company_id=company_id,
        parentId=parent_id,
        take=100
    )

    for folder in folders.folderInfos:
        print("  " * indent + f"📁 {folder.name}")
        # Recursively list subfolders
        list_folder_tree(folder.id, indent + 1)

# Print entire tree
list_folder_tree()

Best Practices

Use Paths for Readability 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# More readable and maintainable
unique_sdk.Folder.update(
    folderPath="/Company/Q1_Reports",
    parentFolderPath="/Company/Archive/2024"
)

# vs scope IDs (harder to read)
unique_sdk.Folder.update(
    scopeId="scope_abc123",
    parentId="scope_def456"
)
Apply Configs to Subfolders 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Set config once at parent level
unique_sdk.Folder.update_ingestion_config(
    folderPath="/Company/Legal",
    ingestionConfig={
        "uniqueIngestionMode": "INGESTION",
        "chunkStrategy": "UNIQUE_DEFAULT_CHUNKING",
        "chunkMaxTokens": 2000  # Legal docs need larger chunks
    },
    applyToSubScopes=True  # Applies to all subfolders
)
Handle Deletion Failures 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
result = unique_sdk.Folder.delete(
    user_id=user_id,
    company_id=company_id,
    scopeId=scope_id,
    recursive=True
)

if result.failedFolders:
    print("Failed to delete (no write access):")
    for folder in result.failedFolders:
        print(f"  - {folder}")

Input Types

Folder.ScopeAccess

The Folder.ScopeAccess type defines access permissions for a folder

Fields:

  • entityId (str, required) - User or group ID
  • type (Literal["READ", "WRITE"], required) - Access type
  • entityType (Literal["USER", "GROUP"], required) - Entity type
  • createdAt (str, optional) - Creation timestamp (ISO 8601)

Used in: Folder.add_access(), Folder.remove_access()

Folder.IngestionConfig

The Folder.IngestionConfig type defines ingestion configuration for a folder

Fields:

  • uniqueIngestionMode (str, required) - Ingestion mode (e.g., "standard")
  • chunkStrategy (str, optional) - Chunking strategy (e.g., "default")
  • chunkMaxTokens (int, optional) - Maximum tokens per chunk
  • chunkMaxTokensOnePager (int, optional) - Maximum tokens for one-page documents
  • chunkMinTokens (int, optional) - Minimum tokens per chunk
  • documentMinTokens (int, optional) - Minimum tokens per document
  • excelReadMode (str, optional) - Excel reading mode
  • jpgReadMode (str, optional) - JPG reading mode
  • pdfReadMode (str, optional) - PDF reading mode
  • pptReadMode (str, optional) - PowerPoint reading mode
  • wordReadMode (str, optional) - Word document reading mode
  • customApiOptions (List[CustomApiOptions], optional) - Custom API options
  • vttConfig (VttConfig, optional) - VTT configuration

Used in: Folder.update_ingestion_config()

Return Types

Folder

The Folder object represents a folder in the knowledge base

Fields:

  • id (str) - Unique folder identifier (scope ID)
  • name (str) - Folder name
  • scopeAccess (List[ScopeAccess]) - List of access permissions. See Folder.ScopeAccess for structure.
  • children (List[Children]) - List of child folders. See Folder.Children for structure.

Returned by: Folder.update(), Folder.update_ingestion_config(), Folder.add_access(), Folder.remove_access()

Folder.Children

The Folder.Children type represents a child folder

Fields:

  • id (str) - Child folder ID
  • name (str) - Child folder name

Used in: Folder.children

Folder.FolderInfo

The FolderInfo object represents folder information

Fields:

  • id (str) - Unique folder identifier
  • name (str) - Folder name
  • ingestionConfig (IngestionConfig) - Ingestion configuration. See Folder.IngestionConfig for structure.
  • createdAt (str | None) - Creation timestamp (ISO 8601)
  • updatedAt (str | None) - Last update timestamp (ISO 8601)
  • parentId (str | None) - Parent folder ID
  • externalId (str | None) - External system identifier

Returned by: Folder.get_info()

Folder.FolderInfos

The FolderInfos object contains paginated folder information

Fields:

  • folderInfos (List[FolderInfo]) - List of folder info objects. See Folder.FolderInfo for structure.
  • totalCount (int) - Total number of matching folders

Returned by: Folder.get_infos()

Folder.FolderPathResponse

The FolderPathResponse object contains a folder path

Fields:

  • folderPath (str) - Complete folder path

Returned by: Folder.get_folder_path()

Folder.CreateFolderStructureResponse

The CreateFolderStructureResponse object contains created folder information

Fields:

  • createdFolders (List[CreatedFolder]) - List of created folders. See Folder.CreatedFolder for structure.

Returned by: Folder.create_paths()

Folder.CreatedFolder

The CreatedFolder object represents a newly created folder

Fields:

  • id (str) - Folder ID
  • object (str) - Object type identifier
  • name (str) - Folder name
  • parentId (str | None) - Parent folder ID

Used in: CreateFolderStructureResponse.createdFolders

Folder.DeleteResponse

The DeleteResponse object contains deletion results

Fields:

Returned by: Folder.delete()

Folder.DeleteFolderResponse

The DeleteFolderResponse object represents a deletion result for a single folder

Fields:

  • id (str) - Folder ID
  • name (str) - Folder name
  • path (str) - Folder path
  • failReason (str, optional) - Failure reason if deletion failed

Used in: DeleteResponse.successFolders, DeleteResponse.failedFolders