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_KEY

Request 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/upload

Upload 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/upload

Upload 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)

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
- Keep API keys secure
- Use environment variables
- Validate file types client-side

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_KEY

Request 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-url

URL 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-url

URL 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

Flowdrive docs

Upload API

Upload API

File Upload

Endpoint

Request Parameters

Example Requests

Success Response

Error Responses

Supported File Types

Images

Documents

Archives

Media

Best Practices

Upload from URL

Endpoint

Request Parameters

Example Requests

Success Response

Error Responses

URL Upload Best Practices

Take control of your file hosting on Webflow.