Chunked Uploads

OxiCloud exposes resumable chunked uploads under /api/uploads. The protocol is TUS-like in spirit, but the concrete API is OxiCloud-specific: create a session, stream chunks with PATCH, inspect progress with HEAD, then finalize the assembled file.

Upload Flow

1. Create an upload session with POST /api/uploads
2. Upload each chunk with PATCH /api/uploads/{upload_id}?chunk_index=N
3. Optionally inspect progress with HEAD /api/uploads/{upload_id}
4. Finalize with POST /api/uploads/{upload_id}/complete
5. Cancel an in-flight upload with DELETE /api/uploads/{upload_id} if needed

API Endpoints

Create upload session

POST /api/uploads
Content-Type: application/json

{
  "filename": "large-video.mp4",
  "folder_id": "folder-uuid",
  "content_type": "video/mp4",
  "total_size": 524288000,
  "chunk_size": 8388608
}

Typical response:

{
  "upload_id": "uuid",
  "chunk_size": 8388608,
  "total_chunks": 63,
  "expires_at": 86400
}

Upload a chunk

Chunks are sent as raw bytes, not multipart form uploads.

PATCH /api/uploads/{upload_id}?chunk_index=0&checksum=md5-hex
Content-Type: application/octet-stream
Content-MD5: md5-hex

<binary chunk bytes>

Notes:

• chunk_index is required and zero-based
• checksum is optional and can also be supplied with the Content-MD5 header
• Successful responses include progress headers such as Upload-Offset, Upload-Progress, and Upload-Complete

Inspect upload status

HEAD /api/uploads/{upload_id}

The response includes upload metadata in headers such as:

• Upload-Offset
• Upload-Length
• Upload-Progress
• Upload-Chunks-Total
• Upload-Chunks-Complete

Finalize upload

POST /api/uploads/{upload_id}/complete

Successful responses return the created file metadata:

{
  "file_id": "uuid",
  "filename": "large-video.mp4",
  "size": 524288000,
  "path": "/Videos/large-video.mp4"
}

Cancel upload

DELETE /api/uploads/{upload_id}

This removes the in-progress session and temporary chunk data.

Validation Rules

• filename is required
• total_size must be greater than zero
• chunk_size must be at least 1 MB when provided
• Storage quota checks can reject the session before upload starts

Frontend Behavior

The OxiCloud web UI can switch to chunked uploads for larger files, track aggregate progress, and retry individual chunks without restarting the full transfer.