File Upload

FileCodeBox provides multiple flexible file upload methods, supporting both regular upload and chunked upload to meet different scenario requirements.

Upload Methods

FileCodeBox supports the following upload methods:

Drag and Drop Upload

Drag files directly to the upload area to start uploading. This is the most convenient upload method.

Open the FileCodeBox homepage
Drag files from your file manager to the upload area
Release the mouse, file upload begins
Get the extraction code after upload completes

Tip

Drag and drop upload supports dragging multiple files simultaneously (depending on theme support).

Click Upload

Click the upload area to select files through the system file picker.

Click the "Select File" button in the upload area
Select the file to upload in the popup file picker
File upload begins after confirming selection
Get the extraction code after upload completes

Paste Upload

Supports pasting images directly from clipboard for upload (supported by some themes).

Copy an image to clipboard (screenshot or copy image)
Use Ctrl+V (Windows/Linux) or Cmd+V (macOS) to paste in the upload area
Image upload starts automatically
Get the extraction code after upload completes

Note

Paste upload only supports image formats, not other file types. Specific support depends on the theme being used.

File Size Limits

Default Limits

Setting	Default	Description
`uploadSize`	10MB	Maximum single file upload size

Modify Upload Limits

Administrators can modify upload size limits through the admin panel or configuration file:

python

# Set maximum upload size to 100MB
uploadSize = 104857600  # 100 * 1024 * 1024

Note

uploadSize is in bytes. Common conversions:

10MB = 10485760
50MB = 52428800
100MB = 104857600
500MB = 524288000
1GB = 1073741824

Exceeding Limit Handling

When an uploaded file exceeds the size limit, the system returns a 403 error:

json

{
  "detail": "Size exceeds limit, maximum is 10.00 MB"
}

Regular Upload API

File Upload Endpoint

POST /share/file/

Content-Type: multipart/form-data

Request parameters:

Parameter	Type	Required	Description
`file`	file	Yes	File to upload
`expire_value`	int	No	Expiration value, default 1
`expire_style`	string	No	Expiration method, default `day`

Expiration method options:

Value	Description
`day`	Expire by days
`hour`	Expire by hours
`minute`	Expire by minutes
`forever`	Never expire
`count`	Expire by download count

Response example:

json

{
  "code": 200,
  "detail": {
    "code": "654321",
    "name": "example.pdf"
  }
}

cURL example:

bash

curl -X POST "http://localhost:12345/share/file/" \
  -F "file=@/path/to/file.pdf" \
  -F "expire_value=7" \
  -F "expire_style=day"

Chunked Upload API

For large files, FileCodeBox supports chunked upload functionality. Chunked upload splits large files into multiple small chunks for separate uploading, supporting resume capability.

Prerequisite

Chunked upload functionality requires administrator enablement: enableChunk=1

Chunked Upload Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Initialize │ ──▶ │Upload Chunks│ ──▶ │  Complete   │
│   /init/    │     │  /chunk/    │     │ /complete/  │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌───────────┐
                    │   Loop    │
                    │each chunk │
                    └───────────┘

1. Initialize Upload

POST /chunk/upload/init/

Request parameters:

json

{
  "file_name": "large_file.zip",
  "file_size": 104857600,
  "chunk_size": 5242880,
  "file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Parameter	Type	Required	Default	Description
`file_name`	string	Yes	-	Filename
`file_size`	int	Yes	-	Total file size (bytes)
`chunk_size`	int	No	5MB	Chunk size (bytes)
`file_hash`	string	Yes	-	SHA256 hash of the file

Response example:

json

{
  "code": 200,
  "detail": {
    "existed": false,
    "upload_id": "abc123def456789",
    "chunk_size": 5242880,
    "total_chunks": 20,
    "uploaded_chunks": []
  }
}

Field	Description
`existed`	Whether file already exists (instant upload)
`upload_id`	Upload session ID
`chunk_size`	Chunk size
`total_chunks`	Total number of chunks
`uploaded_chunks`	List of already uploaded chunk indices

2. Upload Chunk

POST /chunk/upload/chunk/{upload_id}/{chunk_index}

Path parameters:

Parameter	Description
`upload_id`	Upload session ID returned during initialization
`chunk_index`	Chunk index, starting from 0

Request body:

Content-Type: multipart/form-data

Parameter	Type	Description
`chunk`	file	Chunk data

Response example:

json

{
  "code": 200,
  "detail": {
    "chunk_hash": "a1b2c3d4e5f6..."
  }
}

cURL example:

bash

# Upload first chunk (index 0)
curl -X POST "http://localhost:12345/chunk/upload/chunk/abc123def456789/0" \
  -F "chunk=@/path/to/chunk_0"

3. Complete Upload

POST /chunk/upload/complete/{upload_id}

Path parameters:

Parameter	Description
`upload_id`	Upload session ID

Request parameters:

json

{
  "expire_value": 7,
  "expire_style": "day"
}

Parameter	Type	Required	Description
`expire_value`	int	Yes	Expiration value
`expire_style`	string	Yes	Expiration method

Response example:

json

{
  "code": 200,
  "detail": {
    "code": "789012",
    "name": "large_file.zip"
  }
}

Resume Upload

Chunked upload supports resume functionality. When upload is interrupted:

Call the initialization endpoint again with the same file_hash
Server returns uploaded_chunks list containing already uploaded chunk indices
Client only needs to upload chunks not in the list
Call the complete endpoint after all chunks are uploaded

Example flow:

javascript

// 1. Initialize upload
const initResponse = await fetch('/chunk/upload/init/', {
  method: 'POST',
  body: JSON.stringify({
    file_name: 'large_file.zip',
    file_size: fileSize,
    chunk_size: 5 * 1024 * 1024,
    file_hash: fileHash
  })
});
const { upload_id, uploaded_chunks, total_chunks } = await initResponse.json();

// 2. Upload incomplete chunks
for (let i = 0; i < total_chunks; i++) {
  if (!uploaded_chunks.includes(i)) {
    const chunk = file.slice(i * chunkSize, (i + 1) * chunkSize);
    await fetch(`/chunk/upload/chunk/${upload_id}/${i}`, {
      method: 'POST',
      body: chunk
    });
  }
}

// 3. Complete upload
await fetch(`/chunk/upload/complete/${upload_id}`, {
  method: 'POST',
  body: JSON.stringify({
    expire_value: 7,
    expire_style: 'day'
  })
});

Error Handling

Common Errors

HTTP Status	Error Message	Cause	Solution
403	Size exceeds limit	File exceeds `uploadSize` limit	Reduce file size or contact administrator to adjust limit
403	Upload rate limit	Exceeded IP upload rate limit	Wait for limit time window before retrying
400	Invalid expiration type	`expire_style` value not in allowed list	Use a valid expiration method
404	Upload session not found	`upload_id` invalid or expired	Re-initialize upload
400	Invalid chunk index	`chunk_index` out of range	Check if chunk index is correct
400	Incomplete chunks	Chunk count insufficient when completing upload	Ensure all chunks are uploaded

Rate Limiting

The system has rate limits on upload operations to prevent abuse:

Setting	Default	Description
`uploadMinute`	1	Limit time window (minutes)
`uploadCount`	10	Maximum uploads within time window

When rate limit is exceeded, you need to wait for the time window to pass before continuing uploads.

Error Response Format

json

{
  "detail": "Error message description"
}

Upload Configuration

Setting	Type	Default	Description
`openUpload`	int	1	Enable upload (1=enabled, 0=disabled)
`uploadSize`	int	10485760	Maximum upload size (bytes)
`enableChunk`	int	0	Enable chunked upload (1=enabled, 0=disabled)
`uploadMinute`	int	1	Upload rate limit time window (minutes)
`uploadCount`	int	10	Maximum uploads within time window
`expireStyle`	list	["day","hour","minute","forever","count"]	Allowed expiration methods

Configuration Example

python

# Allow 100MB file uploads, enable chunked upload
uploadSize = 104857600
enableChunk = 1

# Relax upload rate limit: max 50 uploads per 5 minutes
uploadMinute = 5
uploadCount = 50

# Only allow expiration by days and count
expireStyle = ["day", "count"]

Next Steps

File Sharing - Learn the complete sharing process
Configuration Guide - Learn about all configuration options
Storage Configuration - Learn about file storage methods
Security Settings - Learn about security-related configurations

File Upload ​

Upload Methods ​

Drag and Drop Upload ​

Click Upload ​

Paste Upload ​

File Size Limits ​

Default Limits ​

Modify Upload Limits ​

Exceeding Limit Handling ​

Regular Upload API ​

File Upload Endpoint ​

Chunked Upload API ​

Chunked Upload Flow ​

1. Initialize Upload ​

2. Upload Chunk ​

3. Complete Upload ​

Resume Upload ​

Error Handling ​

Common Errors ​

Rate Limiting ​

Error Response Format ​

Upload Configuration ​

Related Settings ​

Configuration Example ​

Next Steps ​

File Upload

Upload Methods

Drag and Drop Upload

Click Upload

Paste Upload

File Size Limits

Default Limits

Modify Upload Limits

Exceeding Limit Handling

Regular Upload API

File Upload Endpoint

Chunked Upload API

Chunked Upload Flow

1. Initialize Upload

2. Upload Chunk

3. Complete Upload

Resume Upload

Error Handling

Common Errors

Rate Limiting

Error Response Format

Upload Configuration

Related Settings

Configuration Example

Next Steps