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
}
'

import requests

url = "https://api.example.com/files/upload"

payload = {
    "folder_id": "<string>",
    "name": "<string>",
    "overwrite": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({folder_id: '<string>', name: '<string>', overwrite: true})
};

fetch('https://api.example.com/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'folder_id' => '<string>',
    'name' => '<string>',
    'overwrite' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/files/upload"

	payload := strings.NewReader("{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/files/upload")
  .header("Content-Type", "application/json")
  .body("{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/files/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "storage_exceeded",
    "message": "Storage quota exceeded",
    "details": {
      "current_usage": 1073741824,
      "storage_limit": 1073741824,
      "required_space": 2458624
    }
  }
}

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Folder not found"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "No file provided in request"
  }
}

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
}
'

import requests

url = "https://api.example.com/files/upload"

payload = {
    "folder_id": "<string>",
    "name": "<string>",
    "overwrite": True
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({folder_id: '<string>', name: '<string>', overwrite: true})
};

fetch('https://api.example.com/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'folder_id' => '<string>',
    'name' => '<string>',
    'overwrite' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/files/upload"

	payload := strings.NewReader("{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/files/upload")
  .header("Content-Type", "application/json")
  .body("{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/files/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"folder_id\": \"<string>\",\n  \"name\": \"<string>\",\n  \"overwrite\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "storage_exceeded",
    "message": "Storage quota exceeded",
    "details": {
      "current_usage": 1073741824,
      "storage_limit": 1073741824,
      "required_space": 2458624
    }
  }
}

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Folder not found"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "No file provided in request"
  }
}

Overview

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

Request Body

file

required

The file to upload (binary data)

string

ID of the folder to upload to. Omit to upload to root directory.

string

Custom filename (optional). If not provided, uses the original filename.

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"

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('folder_id', 'folder_123');
formData.append('name', 'my-document.pdf');

const response = await fetch('https://api.hubsy.cloud/v1/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const data = await response.json();
console.log(data.data);

import requests

files = {'file': open('/path/to/document.pdf', 'rb')}
data = {
    'folder_id': 'folder_123',
    'name': 'my-document.pdf'
}

response = requests.post(
    'https://api.hubsy.cloud/v1/files/upload',
    files=files,
    data=data,
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

file_info = response.json()['data']

$ch = curl_init();

$file = new CURLFile('/path/to/document.pdf');
$data = [
    'file' => $file,
    'folder_id' => 'folder_123',
    'name' => 'my-document.pdf'
];

curl_setopt($ch, CURLOPT_URL, 'https://api.hubsy.cloud/v1/files/upload');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

Response

boolean

Indicates if the upload was successful

object

Uploaded file information

Show File Object

string

Unique file identifier

string

File name with extension

integer

File size in bytes

string

MIME type (e.g., “application/pdf”)

string

File category: image, video, audio, document, archive, other

string

ID of parent folder, or null if in root

string

ISO 8601 timestamp of upload

string

ISO 8601 timestamp (same as created_at for new uploads)

string

URL to file thumbnail (if available)

string

Direct download URL (expires in 1 hour)

string

MD5 hash of file contents

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"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "storage_exceeded",
    "message": "Storage quota exceeded",
    "details": {
      "current_usage": 1073741824,
      "storage_limit": 1073741824,
      "required_space": 2458624
    }
  }
}

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Folder not found"
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "No file provided in request"
  }
}

File Size Limits

Maximum file size varies by plan:

Plan	Max File Size
Free	100 MB
Pro	5 GB
Enterprise	10 GB

Upload Best Practices

Large File Uploads

For files larger than 100 MB:

Use chunked upload (coming soon)
Implement retry logic
Show progress to users
Handle network interruptions

Verify Uploads

Verify upload success:

Check response status code (200)
Verify success: true in response
Compare MD5 hash if critical
Store file ID for future reference

Error Handling

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

API Documentation

Endpoints

Upload File

Overview

Request Body

Example Request

Response

Example Response

Error Responses

File Size Limits

Upload Best Practices

Notes

​Overview

​Request Body

​Example Request

​Response

​Example Response

​Error Responses

​File Size Limits

​Upload Best Practices

​Notes

Overview

Request Body

Example Request

Response

Example Response

Error Responses

File Size Limits

Upload Best Practices

Notes