The Files API handles file uploads and downloads for tools that work with files. It’s automatically used when autoUploadDownloadFiles is enabled (default).
Automatic File Handling
By default, Composio automatically handles file uploads and downloads:
const composio = new Composio ({
apiKey: 'your-key' ,
autoUploadDownloadFiles: true // Default
});
// Files are automatically uploaded before tool execution
const result = await composio . tools . execute ( 'GOOGLE_DRIVE_UPLOAD' , {
userId: 'default' ,
arguments: {
file: '/path/to/document.pdf' , // Automatically uploaded
folderId: 'folder_123'
}
});
// Files are automatically downloaded after tool execution
console . log ( result . data . downloadedFile ); // Local file path
Manual File Upload
upload()
Manually upload a file:
const fileData = await composio . files . upload ({
file: '/path/to/document.pdf' , // Local file path or File object
toolSlug: 'GOOGLE_DRIVE_UPLOAD' ,
toolkitSlug: 'google_drive'
});
console . log ( 'Uploaded:' , fileData );
// {
// url: 's3://...',
// name: 'document.pdf',
// mimeType: 'application/pdf',
// size: 1024000
// }
File object or path to local file
Tool that will use the file
Toolkit the tool belongs to
Manual File Download
download()
Manually download a file:
const fileData = await composio . files . download ({
s3Url: 's3://bucket/key' ,
toolSlug: 'GOOGLE_DRIVE_DOWNLOAD' ,
mimeType: 'application/pdf'
});
console . log ( 'Downloaded:' , fileData );
// {
// path: '/tmp/downloaded-file.pdf',
// content: Buffer,
// mimeType: 'application/pdf'
// }
S3 URL of the file to download
Tool that downloaded the file
Disabling Automatic Handling
Disable automatic file handling for manual control:
const composio = new Composio ({
apiKey: 'your-key' ,
autoUploadDownloadFiles: false
});
// Now you must manually handle files
const fileData = await composio . files . upload ({
file: '/path/to/file.pdf' ,
toolSlug: 'GOOGLE_DRIVE_UPLOAD' ,
toolkitSlug: 'google_drive'
});
const result = await composio . tools . execute ( 'GOOGLE_DRIVE_UPLOAD' , {
userId: 'default' ,
arguments: {
fileUrl: fileData . url , // Use uploaded file URL
folderId: 'folder_123'
}
});
Complete Example
import { Composio } from '@composio/core' ;
import { readFileSync } from 'fs' ;
const composio = new Composio ({
apiKey: process . env . COMPOSIO_API_KEY ! ,
autoUploadDownloadFiles: true
});
async function uploadAndShare () {
// Automatic upload
const uploadResult = await composio . tools . execute (
'GOOGLE_DRIVE_UPLOAD' ,
{
userId: 'default' ,
arguments: {
file: './report.pdf' , // Automatically uploaded
folderId: 'root'
}
}
);
console . log ( 'Uploaded file ID:' , uploadResult . data . fileId );
// Download a file
const downloadResult = await composio . tools . execute (
'GOOGLE_DRIVE_DOWNLOAD' ,
{
userId: 'default' ,
arguments: {
fileId: uploadResult . data . fileId
}
}
);
// File is automatically downloaded
console . log ( 'Downloaded to:' , downloadResult . data . filePath );
}
awaituploadAndShare ();
Supported File Operations
GOOGLE_DRIVE_UPLOAD
DROPBOX_UPLOAD_FILE
SLACK_UPLOAD_FILE
GMAIL_SEND_EMAIL (with attachments)
GOOGLE_DRIVE_DOWNLOAD
DROPBOX_DOWNLOAD_FILE
SLACK_GET_FILE
GMAIL_GET_ATTACHMENT
File Types
FileUploadData
interface FileUploadData {
url : string ; // S3 URL
name : string ; // File name
mimeType : string ; // MIME type
size : number ; // Size in bytes
}
FileDownloadData
interface FileDownloadData {
path : string ; // Local file path
content : Buffer ; // File content
mimeType : string ; // MIME type
}
Best Practices
Auto Handling : Use automatic file handling for simplicity
File Cleanup : Clean up downloaded files after use
Error Handling : Handle upload/download failures
Size Limits : Be aware of file size limits
Temporary Files : Use temp directories for downloads
File operations are supported in:
✅ Node.js
✅ Bun
❌ Browser (use File objects)
❌ Cloudflare Workers (no filesystem)
⚠️ Deno (with —allow-read/—allow-write)
Next Steps
Tools API Learn about tools
Platform Support Runtime compatibility
Composio Class Main SDK reference