Skip to main content
POST
/
files
/
upload
Upload File
curl --request POST \
  --url https://api.example.com/files/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "folder_id": "<string>",
  "name": "<string>",
  "overwrite": true
}
'
{
  "success": false,
  "error": {
    "code": "file_too_large",
    "message": "File exceeds maximum size limit for your plan",
    "details": {
      "file_size": 6000000000,
      "max_size": 5000000000,
      "plan": "pro"
    }
  }
}

​
Overview

Upload a new file to your Hubsy Cloud storage. Supports multipart/form-data for file uploads.

​
Request Body

​
file
file
required
The file to upload (binary data)
​
folder_id
string
ID of the folder to upload to. Omit to upload to root directory.
​
name
string
Custom filename (optional). If not provided, uses the original filename.
​
overwrite
boolean
default:"false"
If true and a file with the same name exists, it will be overwritten. Otherwise, a new file with a numbered suffix is created.

​
Example Request

curl -X POST https://api.hubsy.cloud/v1/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "folder_id=folder_123" \
  -F "name=my-document.pdf"

​
Response

​
success
boolean
Indicates if the upload was successful
​
data
object
Uploaded file information

​
Example Response

{
  "success": true,
  "data": {
    "id": "file_xyz789",
    "name": "my-document.pdf",
    "size": 2458624,
    "type": "application/pdf",
    "category": "document",
    "folder_id": "folder_123",
    "created_at": "2024-01-15T14:30:00Z",
    "modified_at": "2024-01-15T14:30:00Z",
    "thumbnail_url": "https://cdn.hubsy.cloud/thumbs/file_xyz789.jpg",
    "download_url": "https://cdn.hubsy.cloud/download/file_xyz789?token=abc123",
    "md5_hash": "5d41402abc4b2a76b9719d911017c592"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "file_too_large",
    "message": "File exceeds maximum size limit for your plan",
    "details": {
      "file_size": 6000000000,
      "max_size": 5000000000,
      "plan": "pro"
    }
  }
}

​
File Size Limits

Maximum file size varies by plan:
PlanMax File Size
Free100 MB
Pro5 GB
Enterprise10 GB

​
Upload Best Practices

For files larger than 100 MB:
  • Use chunked upload (coming soon)
  • Implement retry logic
  • Show progress to users
  • Handle network interruptions
Verify upload success:
  • Check response status code (200)
  • Verify success: true in response
  • Compare MD5 hash if critical
  • Store file ID for future reference
Handle common errors:
  • Storage exceeded → Notify user to upgrade
  • File too large → Compress or split file
  • Invalid folder → Verify folder exists
  • Rate limit → Implement exponential backoff

​
Notes

  • Supported file types: All types accepted
  • Files are scanned for viruses automatically
  • Duplicate filenames are handled based on overwrite parameter
  • Upload progress tracking available via chunked upload API (coming soon)
  • MD5 hash can be used to verify file integrity