Upload API
Learn how to upload files using the FlowDrive API
Last updated: March 15, 2024
Upload API
File Upload
Upload one or multiple files to FlowDrive.
Endpoint
http
POST /v1/files/upload
Content-Type: multipart/form-data
X-API-Key: YOUR_API_KEYRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Yes | The file(s) to upload |
folder | String | No | Target folder path |
metadata | Object | No | Custom metadata for the file |
Example Requests
Basic Upload:
bash
curl -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/file.jpg" \
https://api.tryflowdrive.com/v1/files/uploadUpload to Folder:
bash
curl -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/file.jpg" \
-F "folder=images/profile" \
https://api.tryflowdrive.com/v1/files/uploadUpload with Metadata:
javascript
const formData = new FormData();
formData.append('file', file);
formData.append('folder', 'images/profile');
formData.append('metadata', JSON.stringify({
userId: '123',
type: 'avatar'
}));
fetch('https://api.tryflowdrive.com/v1/files/upload', {
method: 'POST',
headers: {
'X-API-Key': apiKey
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data));Success Response
json
{
"message": "File uploaded successfully",
"fileId": "file-123456",
"originalName": "profile.jpg",
"storagePath": "images/profile/file-123456_profile.jpg",
"fileUrl": "https://files.tryflowdrive.com/id/file-123456_profile.jpg",
"metadata": {
"userId": "123",
"type": "avatar"
}
}Error Responses
json
{
"error": "Storage limit exceeded",
"code": "STORAGE_LIMIT_EXCEEDED",
"limit": "10GB"
}json
{
"error": "Invalid file type",
"code": "INVALID_FILE_TYPE",
"allowedTypes": ["image/jpeg", "image/png", "..."]
}Supported File Types
FlowDrive supports a wide range of file types including:
Images
- JPEG (
image/jpeg) - PNG (
image/png) - WebP (
image/webp) - GIF (
image/gif) - AVIF (
image/avif) - SVG (
image/svg+xml)
Documents
- PDF (
application/pdf) - Plain Text (
text/plain) - CSV (
text/csv)
Archives
- ZIP (
application/zip) - GZIP (
application/gzip)
Media
- MP4 (
video/mp4) - MP3 (
audio/mpeg)
View full list of supported types
Best Practices
File Size
- Keep files under the plan limits
- Consider compression for large files
- Use chunked upload for large files (coming soon)
Folders
- Use descriptive folder names
- Organize files logically
- Don't create deeply nested structures
Error Handling
- Always handle upload errors
- Implement retry logic for failed uploads
- Check file type before uploading
Security
- The upload key is upload-only and safe to expose publicly — no need to hide it
- Browsers can upload with the key only from the domains on it, so add your site's domain first (Webflow sites get theirs automatically through the Flowdrive app)
- File size, type, and storage limits are enforced server-side on every upload
Upload from URL
Upload files directly from a URL without downloading them to your server first.
Endpoint
http
POST /v1/files/upload-url
Content-Type: application/json
X-API-Key: YOUR_API_KEYRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
url | String | Yes | The URL of the file to upload |
fileName | String | No | Custom filename (defaults to URL filename) |
folderId | String | No | Target folder ID |
metadata | Object | No | Custom metadata for the file |
Example Requests
Basic URL Upload:
bash
curl -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/image.jpg"}' \
https://api.tryflowdrive.com/v1/files/upload-urlURL Upload with Custom Name:
bash
curl -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/image.jpg",
"fileName": "my-custom-image.jpg",
"folderId": "folder-123"
}' \
https://api.tryflowdrive.com/v1/files/upload-urlURL Upload with Metadata:
javascript
const response = await fetch('https://api.tryflowdrive.com/v1/files/upload-url', {
method: 'POST',
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://example.com/document.pdf',
fileName: 'important-document.pdf',
folderId: 'documents',
metadata: {
source: 'external',
category: 'legal',
tags: ['contract', '2024']
}
})
});
const result = await response.json();
console.log(result);Success Response
json
{
"id": "file-123456",
"org_id": "org-789",
"original_name": "image.jpg",
"storage_path": "file-123456",
"file_size": 1024000,
"content_type": "image/jpeg",
"file_url": "https://files.tryflowdrive.com/file-123456",
"folder_id": "folder-123",
"upload_date": "2024-03-15T10:30:00Z"
}Error Responses
json
{
"code": "MISSING_URL",
"message": "URL is required"
}json
{
"code": "INVALID_URL",
"message": "Invalid URL format"
}json
{
"code": "URL_NOT_ACCESSIBLE",
"message": "Could not access the provided URL"
}json
{
"code": "DOWNLOAD_FAILED",
"message": "Failed to download file from URL"
}URL Upload Best Practices
URL Validation
- Ensure URLs are publicly accessible
- Use HTTPS URLs when possible
- Avoid URLs that require authentication
File Size Considerations
- Large files may take longer to process
- Consider the source server's bandwidth
- Monitor for timeout issues
Error Handling
- Always handle URL accessibility errors
- Implement retry logic for failed downloads
- Validate file types before processing
Security
- Only use trusted URLs
- Be cautious with user-provided URLs
- Validate file content when possible