File Management in Brightsy AI provides capabilities for storing, organizing, and accessing documents and media. The File Manager is accessible through the main navigation and integrates seamlessly with AI agents through specialized tools.
Features & Capabilities
- Hierarchical Storage: Unlimited folder structures with drag-and-drop organization
- Full-Text Search: Search across file names, content, and metadata
- Permission System: Public/private access control with signed URLs
- Version History: Automatic versioning with rollback capabilities
- CDN Integration: Global content delivery for optimal performance
- AI-Powered Organization: Smart file categorization and tagging
- Batch Operations: Bulk upload, move, and delete operations
- Format Support: All common document, image, video, and archive formats
- Integration APIs: REST APIs, SDK methods, CLI commands, and MCP tools
AI Integration & MCP Tools
Brightsy files integrate seamlessly with AI agents through comprehensive MCP (Model Context Protocol) tools.
MCP File Tools
Brightsy provides extensive file management through MCP servers:
Cloud File Tools (Brightsy Platform)
list_files: Browse account file storage with search and filteringupload_file: Upload files with automatic type detectionget_file_content: Retrieve file content and metadataget_signed_url: Generate secure temporary access linksmove_file: Move/rename files and foldersdelete_file: Remove files with confirmationcreate_folder: Create organized folder structures
Local File Tools (Development Workspace)
local_read_file: Read project files (no authentication required)local_write_file: Write to project fileslocal_list_files: Browse project directory structurelocal_search_files: Search file contents with regex patternslocal_grep: Advanced text search with contextlocal_run_command: Execute terminal commands in project directory
Configuring File Tools for Agents
- Navigate to Agents → Select your agent → Edit
- In the Tools section, enable file management tools
- Configure file access permissions and allowed paths
- Save and test the agent with file operations
Example AI Interactions
Listing and Searching Files:
User: Find all PDF files in my documents AI: [calls list_files with search filter] AI: Found 5 PDF files in documents/: • report_2024.pdf (2.3 MB, Modified: 2024-01-15) • proposal.pdf (1.1 MB, Modified: 2024-01-10) • contract_final.pdf (892 KB, Modified: 2024-01-08) • meeting_notes.pdf (456 KB, Modified: 2024-01-05) • invoice_march.pdf (234 KB, Modified: 2024-01-03)
Content Analysis:
User: Search for files containing "budget" in their content AI: [calls local_grep or searches file content] AI: Found 3 files mentioning "budget": • financial_plan.docx (line 45: "Q4 budget allocation") • project_proposal.pdf (page 12: "budget constraints") • meeting_notes.txt (line 23: "discuss budget approval")
File Management:
User: Upload this image and create a gallery post AI: [calls upload_file, then create_record] AI: Uploaded image.jpg to images/ (1.2 MB) Created gallery post "Sunset View" with the uploaded image
Batch Operations:
User: Move all files from temp/ to archive/ and clean up AI: [calls list_files, move_file in batch] AI: Moved 12 files from temp/ to archive/2024-q1/ Deleted empty temp/ folder
How to Use
File Operations
Listing Files: Browse directory contents
list_files(path="files")
Creating Folders: Organize files in a logical structure
create_folder(folder_name="project_documents", path="files")
Uploading Files: Add new files to the system
upload_file(file_name="report.pdf", content_base64="...", path="files/project_documents")
Accessing File Content: Retrieve file information or content
get_file_content(file_path="files/project_documents/report.pdf")
Moving or Renaming: Reorganize your file structure
move_file(source_path="files/old_name.pdf", destination_path="files/new_name.pdf", is_folder=false)
Deleting Files: Remove files or folders
delete_file(file_path="files/project_documents/old_file.pdf", is_folder=false)
Programmatic Access
BrightsyClient SDK
The SDK provides comprehensive file management with automatic error handling and TypeScript support:
import { BrightsyClient } from '@brightsy/client';
const client = new BrightsyClient({
api_key: 'bsy_...',
account_id: 'account-uuid'
});
// Upload with progress and metadata
const upload = await client.files().upload('report.pdf', fileBuffer, {
folder: 'documents/quarterly',
metadata: { category: 'finance', quarter: 'Q4' }
});
// List with filtering and pagination
const files = await client.files().list('documents/', {
search: 'budget',
limit: 20,
sortBy: 'modified',
sortOrder: 'desc'
});
// Get signed URL for secure access
const signedUrl = await client.files().getSignedUrl('private/document.pdf', {
expiresIn: 3600 // 1 hour
});
// Stream large files
const stream = await client.files().downloadStream('large-video.mp4');
stream.pipe(fs.createWriteStream('local-copy.mp4'));
// Batch operations
await client.files().moveMultiple([
{ from: 'temp/file1.pdf', to: 'archive/file1.pdf' },
{ from: 'temp/file2.pdf', to: 'archive/file2.pdf' }
]);
// Create organized folder structure
await client.files().createFolder('documents/2024/projects');
Best Practices
Organization & Structure
- Hierarchical Design: Use clear folder structures like
documents/contracts/,images/products/,assets/branding/ - Consistent Naming: Use kebab-case for folders (
user-uploads) and descriptive filenames - Metadata Strategy: Leverage file metadata for categorization and search
- Version Control: Use meaningful version names when manually versioning files
Performance & Scalability
- File Size Limits: Be aware of 100MB per file limit; compress large files when possible
- Batch Operations: Use bulk operations for multiple files to reduce API calls
- CDN Optimization: Public files automatically use global CDN for fast delivery
- Lazy Loading: Load file previews and thumbnails on demand
Security & Access Control
- Public vs Private: Store user-generated content as private by default
- Signed URLs: Always use signed URLs for private file access (they expire automatically)
- Permission Levels: Configure appropriate access for different user roles
- Audit Trails: File operations are logged for security monitoring
Integration Patterns
- Record Attachments: Link files to records using file reference fields
- Component Assets: Store component images and assets in organized folders
- Template Resources: Keep reusable assets in dedicated template folders
- Backup Strategy: Important files have automatic version history
AI & Automation
- Smart Organization: Let AI agents help categorize and organize files
- Content Analysis: Use AI to generate descriptions and tags for uploaded files
- Duplicate Detection: Implement checks to prevent duplicate file uploads
- Auto-tagging: Configure rules for automatic metadata assignment
Development Workflow
- Local Development: Use local MCP tools for project file operations
- Version Sync: Keep local development files in sync with platform storage
- Build Assets: Automate upload of build artifacts and assets
- Environment Separation: Use different folders for dev/staging/production assets
Monitoring & Maintenance
- Usage Tracking: Monitor storage usage and set up alerts for limits
- Regular Cleanup: Schedule automated cleanup of temporary and old files
- Backup Verification: Regularly verify backup integrity and accessibility
- Performance Monitoring: Track file access patterns and optimize hot paths