Documentation # Flowdrive docs

    # 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`)

### Archives

- ZIP (`application/zip`)

- GZIP (`application/gzip`)

### Media

- MP4 (`video/mp4`)

- MP3 (`audio/mpeg`)

[View full list of supported types](https://tryflowdrive.com/docs/api-reference#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