Upload API

Upload files using PUT, multipart POST, or the resumable up2k protocol

copyparty provides multiple upload methods to suit different use cases, from simple PUT uploads to the advanced up2k resumable upload protocol.

Upload Methods

Simple PUT Upload

Upload a file directly to a specific path:

curl -X PUT \
  -H "PW: your-password" \
  --data-binary @file.txt \
  http://server:3923/path/to/file.txt

path · string · required

Destination path for the file

Content-Length · integer · required

Size of the file in bytes

PW · string

Authentication password (alternative to ?pw= parameter)

Multipart POST Upload

Upload files using standard HTML form multipart encoding:

curl -X POST \
  -H "PW: your-password" \
  -F "f=@file1.txt" \
  -F "f=@file2.txt" \
  http://server:3923/destination/folder/

f · file · required

File to upload. Multiple files can be included with multiple f parameters

Upload Modifiers

Both PUT and POST uploads support these modifiers:

URL Parameters

j · boolean

Return JSON response with upload metadata

ck · string · default: "sha512"

Checksum algorithm. Options: no (disable), md5, sha1, sha256, b2 (blake2b), b2s (blake2s)

replace · boolean

Overwrite existing files (requires delete permission)

apnd · boolean

Append to existing file instead of overwriting

gz · integer

Compress with gzip. Optional compression level 0-9 (default: 9)

xz · integer

Compress with xz/lzma. Optional compression level 0-9 (default: 1)

rand · integer

Generate random filename with specified number of characters

life · integer

Auto-delete file after specified seconds (requires volume lifetime setting)

HTTP Headers

Accept · string

Response format: url (just URL), json (full metadata)

Rand · integer

Same as ?rand= parameter - generate random filename

Life · integer

Same as ?life= parameter - file lifetime in seconds

Replace · boolean

Same as ?replace parameter - overwrite existing files

CK · string

Same as ?ck= parameter - checksum algorithm

up2k Resumable Upload Protocol

The up2k protocol provides resumable, chunked uploads with integrity verification. It’s the most reliable method for large files.

How up2k Works

1. Client splits file into chunks (1-32 MiB each, max 256-4096 chunks)
2. Client hashes each chunk with SHA-512
3. Handshake: Client sends hashlist to server
4. Server creates wark (upload identifier) and sparse file
5. Client uploads chunks (can be parallel, non-sequential)
6. Server validates each chunk hash
7. Final handshake: Server confirms all chunks received

Chunk Size Calculation

Chunk sizes are automatically determined by file size:

File Size	Chunk Size	Max Chunks
≤ 256 MiB	1.0 MiB	256
≤ 384 MiB	1.5 MiB	256
≤ 512 MiB	2.0 MiB	256
≤ 1 GiB	4.0 MiB	256
≤ 4 GiB	16 MiB	256
≤ 128 GiB	32 MiB	4096
≤ 1 TiB	256 MiB	4096
> 1 TiB	up to 8 GiB	4096

Step 1: Handshake (Initial)

Send file metadata and chunk hashes:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "PW: your-password" \
  -d '{
    "name": "file.bin",
    "size": 10485760,
    "lmod": 1234567890,
    "hash": [
      "base64-encoded-sha512-chunk1-hash",
      "base64-encoded-sha512-chunk2-hash"
    ]
  }' \
  http://server:3923/destination/folder/

wark · string

Upload identifier - unique ID for this upload session

purl · string

URL where file will be accessible after upload

need · array

List of chunk hashes that need to be uploaded (empty if file already exists)

Step 2: Upload Chunks

Upload each required chunk:

curl -X POST \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Length: 1048576" \
  -H "X-Up2k-Hash: chunk-hash-1,chunk-hash-2" \
  -H "X-Up2k-Wark: wark-from-handshake" \
  -H "PW: your-password" \
  --data-binary @chunk-data \
  http://server:3923/destination/folder/

X-Up2k-Hash · string · required

Comma-separated list of chunk hashes being uploaded. Can upload multiple consecutive chunks in one request

X-Up2k-Wark · string · required

The wark identifier from the initial handshake

X-Up2k-Subc · integer

For partial chunk uploads - byte offset within the chunk (resumable even within a chunk)

Step 3: Final Handshake

Confirm upload completion:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "PW: your-password" \
  -d '{
    "name": "file.bin",
    "size": 10485760,
    "hash": [
      "base64-encoded-sha512-chunk1-hash",
      "base64-encoded-sha512-chunk2-hash"
    ]
  }' \
  http://server:3923/destination/folder/

Server responds with:

• need: [] if all chunks received
• need: ["hash1", "hash2"] if chunks are missing (re-upload them)

Response Examples

Successful Upload (JSON)

{
  "url": "/files/document.pdf",
  "size": 1048576,
  "sha512": "base64-encoded-sha512-hash",
  "upload_time": 1234567890
}

up2k Handshake Response

{
  "wark": "abcd1234-upload-identifier",
  "purl": "/uploads/2024-03-03/file.bin",
  "need": [
    "hash-of-chunk-3",
    "hash-of-chunk-7"
  ]
}

Upload Features

Deduplication

up2k automatically detects duplicate files:

• If file with same content exists, returns existing file URL
• Can create symlinks to duplicates (if enabled with --dedup)
• Content-based matching via SHA-512 hashes

Resume Support

• up2k uploads resume automatically if interrupted
• Re-upload same file - server skips already-received chunks
• Works even after browser/client restart
• Subchunk resume supported with X-Up2k-Subc header

Parallel Uploads

• up2k chunks can be uploaded in parallel
• Non-sequential upload order supported
• Improves performance on fast connections

Write-Only Folders

With g or G permission:

• Users can upload but not browse
• g: Cannot see file URLs
• G: Receive file URL/key after upload

Error Handling

400 · error

Bad request - invalid parameters, missing headers, or chunk mismatch

401 · error

Authentication required - missing or invalid credentials

403 · error

Insufficient permissions - user lacks write access

413 · error

File too large - exceeds volume size limits

500 · error

Server error - disk full, permissions issue, or corruption detected

Best Practices

• Use up2k for files > 10 MiB for automatic resume capability
• Enable ?j parameter to get structured JSON responses
• Use ?ck=no for faster uploads if integrity is not critical
• Set ?life= for temporary files that should auto-delete

• up2k requires JavaScript client or manual implementation
• Chunk hashes must be URL-safe base64 encoded
• Maximum 4096 chunks per file
• Wark expires if upload is abandoned (server cleans up automatically)

Example: Complete up2k Upload

See the official Python client for a complete implementation of the up2k protocol.