Upload API

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

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 "[email protected]" \
  -F "[email protected]" \
  http://server:3923/destination/folder/

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

boolean

Return JSON response with upload metadata

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

integer

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

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

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

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

Client splits file into chunks (1-32 MiB each, max 256-4096 chunks)
Client hashes each chunk with SHA-512
Handshake: Client sends hashlist to server
Server creates wark (upload identifier) and sparse file
Client uploads chunks (can be parallel, non-sequential)
Server validates each chunk hash
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.

HTTP API

Upload Methods

Simple PUT Upload

Multipart POST Upload

Upload Modifiers

URL Parameters

HTTP Headers

up2k Resumable Upload Protocol

How up2k Works

Chunk Size Calculation

Step 1: Handshake (Initial)

Step 2: Upload Chunks

Step 3: Final Handshake

Response Examples

Successful Upload (JSON)

up2k Handshake Response

Upload Features

Deduplication

Resume Support

Parallel Uploads

Write-Only Folders

Error Handling

Best Practices

Example: Complete up2k Upload

Build docs developers (and LLMs) love

HTTP API

​Upload Methods

​Simple PUT Upload

​Multipart POST Upload

​Upload Modifiers

​URL Parameters

​HTTP Headers

​up2k Resumable Upload Protocol

​How up2k Works

​Chunk Size Calculation

​Step 1: Handshake (Initial)

​Step 2: Upload Chunks

​Step 3: Final Handshake

​Response Examples

​Successful Upload (JSON)

​up2k Handshake Response

​Upload Features

​Deduplication

​Resume Support

​Parallel Uploads

​Write-Only Folders

​Error Handling

​Best Practices

​Example: Complete up2k Upload

Build docs developers (and LLMs) love

Upload Methods

Simple PUT Upload

Multipart POST Upload

Upload Modifiers

URL Parameters

HTTP Headers

up2k Resumable Upload Protocol

How up2k Works

Chunk Size Calculation

Step 1: Handshake (Initial)

Step 2: Upload Chunks

Step 3: Final Handshake

Response Examples

Successful Upload (JSON)

up2k Handshake Response

Upload Features

Deduplication

Resume Support

Parallel Uploads

Write-Only Folders

Error Handling

Best Practices

Example: Complete up2k Upload