Documentation

Folder Management

Organize your files into a hierarchical folder structure

File Organization

Folders provide a desktop-like file system structure for organizing your uploaded images, documents, and videos. Create nested folders, move files between them, and navigate with breadcrumb paths.

Async vs Sync

This page shows async examples. For sync applications, use SyncAionVision - the API is identical without async/await.

Creating Folders

Create a Folder

Create a new folder at root level or nested inside another folder

async with AionVision(api_key="aion_...") as client:
    # Create a root-level folder
    folder = await client.folders.create(name="Project Photos")

    print(f"Folder ID: {folder.id}")
    print(f"Name: {folder.name}")
    print(f"Depth: {folder.depth}")

    # Create a nested subfolder
    subfolder = await client.folders.create(
        name="Site Inspections",
        parent_id=folder.id
    )

    print(f"Subfolder depth: {subfolder.depth}")  # 1

Folder Naming Rules

Length: 1-255 characters
Forbidden characters: /, \, null bytes
Uniqueness: Names must be unique within the same parent folder
Conflict: Creating a folder with a duplicate name returns a 409 error

Navigating Folders

Get Folder Tree

Retrieve all folders as a flat list with parent relationships

# Get all folders (flat list, build tree client-side using parent_id)
tree = await client.folders.tree()

for folder in tree.folders:
    indent = "  " * folder.depth
    print(f"{indent}{folder.name} ({folder.file_count} files, {folder.subfolder_count} subfolders)")

Get Folder Contents

List subfolders and file count for a specific folder

# Get contents of a folder
contents = await client.folders.get(
    folder_id="folder_abc123",
    limit=50,
    offset=0
)

# Current folder info
print(f"Folder: {contents.folder.name}")
print(f"Total files: {contents.total_files}")
print(f"Has more: {contents.has_more_files}")

# Breadcrumb path
for crumb in contents.breadcrumbs:
    print(f"  > {crumb.name}")

# Subfolders
for sub in contents.subfolders:
    print(f"  [DIR] {sub.name} ({sub.file_count} files)")

Get Breadcrumbs

Get the ancestor chain for navigation

# Get breadcrumb path for a deeply nested folder
result = await client.folders.get_breadcrumbs(folder_id="folder_deep123")

# Prints: Root > Projects > 2024 > Site A
path = " > ".join(b.name for b in result.breadcrumbs)
print(f"Path: {path}")

Organizing Files

Move Files to Folder

Move one or more files into a folder (max 100 files per request)

# Move files into a folder
result = await client.folders.move_files(
    file_ids=["file_001", "file_002", "file_003"],
    folder_id="folder_abc123"
)

print(f"Moved: {result.moved} of {result.total_requested}")

# Move files to root (remove from folder)
result = await client.folders.move_files(
    file_ids=["file_001"],
    folder_id=None  # None means root level
)

Rename a Folder

Change the name of an existing folder

folder = await client.folders.rename(
    folder_id="folder_abc123",
    name="Updated Project Name"
)

print(f"Renamed to: {folder.name}")

Move a Folder

Move a folder to a different parent location

# Move folder to a different parent
folder = await client.folders.move(
    folder_id="folder_abc123",
    new_parent_id="folder_target456"
)

print(f"New depth: {folder.depth}")

# Move folder to root level
folder = await client.folders.move(
    folder_id="folder_abc123",
    new_parent_id=None  # None means root level
)

Circular Reference Protection

You cannot move a folder into one of its own descendants. The API returns a 422 error if the move would create a circular reference.

Deleting Folders

Delete a Folder

Remove a folder with two deletion modes

# Mode 1: Move contents to parent (default)
# Files and subfolders are moved up one level
result = await client.folders.delete(
    folder_id="folder_abc123",
    mode="move_to_parent"
)

print(f"Deleted folder, moved {result.files_affected} files")
print(f"Subfolders moved: {result.subfolders_affected}")

# Mode 2: Delete everything
# Folder, all subfolders, and all contained files are removed
result = await client.folders.delete(
    folder_id="folder_abc123",
    mode="delete_all"
)

print(f"Deleted folder with {result.files_affected} files")

Chat Integration

Organize via Chat

Use natural language in the agentic chat to organize files

async with client.chat_session() as session:
    # The AI's folder agent can organize files for you
    response = await session.send(
        "Create a folder called 'Damaged Equipment' and move all "
        "images showing damage into it"
    )

    print(response.content)  # Confirms what was organized

What's Next?

FoldersResource Reference

Complete method signatures and return types

Folder Types

Folder, FolderBreadcrumb, FolderBreadcrumbs, FolderTree, FolderContents, DeleteFolderResult, MoveFilesResult

Managing Files

List, search, and manage uploaded files

Agentic Chat

Use AI to organize and query your files