Download API

Download files, folders as archives, and stream content

copyparty provides flexible download capabilities including direct file downloads, folder archives, thumbnails, and streaming.

Download Files

Direct Download

Download a file directly:

curl -H "PW: your-password" \
  http://server:3923/path/to/file.txt

Force Download (Don’t Display in Browser)

Add ?dl to force download instead of browser display:

curl http://server:3923/path/to/file.txt?dl

dl · boolean

Force download with Content-Disposition: attachment header

Partial Downloads (Range Requests)

copyparty supports HTTP range requests for resumable downloads:

curl -H "Range: bytes=0-1023" \
  http://server:3923/large-file.bin

Archive Downloads

Download entire folders as compressed archives.

TAR Archives

Download folder as tar file:

curl "http://server:3923/folder/?tar" -o folder.tar

tar · string · default: "gnu"

Archive format. Options:

• (empty) - Plain GNU tar
• pax - PAX format (futureproof)
• gz or gz:N - Gzip compressed (level 0-9, default 3)
• xz or xz:N - XZ/LZMA compressed (level 0-9, default 1)
• bz2 or bz2:N - Bzip2 compressed (level 1-9, default 2)

Examples

# Plain tar (fast, streamable)
curl "http://server:3923/music/?tar" -o music.tar

# Gzip compressed tar (level 3)
curl "http://server:3923/music/?tar=gz" -o music.tgz

# Gzip compressed tar (level 9 = best compression)
curl "http://server:3923/music/?tar=gz:9" -o music.tgz

# XZ compressed tar (level 9)
curl "http://server:3923/music/?tar=xz:9" -o music.txz

# PAX format tar
curl "http://server:3923/music/?tar=pax" -o music.tar

ZIP Archives

Download folder as zip file:

curl "http://server:3923/folder/?zip" -o folder.zip

zip · string · default: "utf8"

ZIP format variant:

• (empty) - Modern UTF-8 filenames
• dos - CP437 encoding (Windows XP compatibility)
• crc - CP437 with early CRC32 (MS-DOS PKZIP v2.04g compatibility)

Selective Archives

Download only selected files/folders as archive:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '["file1.txt", "subfolder/file2.txt"]' \
  "http://server:3923/folder/?tar" -o selected.tar

Archive Modifiers

Transcode Audio

Convert audio files on-the-fly while archiving:

# Convert to Opus
curl "http://server:3923/music/?tar&opus" -o music.tar

# Convert to MP3  
curl "http://server:3923/music/?tar&mp3" -o music.tar

opus · boolean

Transcode all audio (except aac/m4a/mp3/ogg/opus/wma) to 128kbps Opus

mp3 · boolean

Transcode all audio (except aac/m4a/mp3/ogg/opus/wma) to MP3

Generate Thumbnails

Replace media files with thumbnails:

# JPEG thumbnails
curl "http://server:3923/photos/?tar&j" -o thumbnails.tar

# WebM video thumbnails
curl "http://server:3923/videos/?tar&w" -o thumbnails.tar

# Audio waveforms (PNG)
curl "http://server:3923/music/?tar&p" -o waveforms.tar

j · boolean

Include JPEG thumbnails instead of original images/videos

w · boolean

Include WebM thumbnails for videos

p · boolean

Include PNG waveforms for audio files

Exclude Dotfiles

curl "http://server:3923/folder/?tar&nodot" -o folder.tar

nodot · boolean

Exclude dotfiles and dotfolders from archive

File Listings

Get folder contents as structured data.

JSON Listing

curl "http://server:3923/folder/?ls" | jq

dirs · array

List of subdirectories with metadata

files · array

List of files with size, modification time, and permissions

Plaintext Listing

curl "http://server:3923/folder/?ls=t"

ls · string

Listing format:

• (empty) - JSON format
• t - Plaintext (one per line)
• v - Terminal-formatted (with colors)

Include Dotfiles in Listings

curl "http://server:3923/folder/?ls&dots"

dots · boolean

Include dotfiles in listing (requires dot permission)

Symlink Timestamps

curl "http://server:3923/folder/?ls&lt"

lt · boolean

Use symlink timestamps instead of target file timestamps

Directory Tree

Get nested directory structure:

# One level of subdirectories
curl "http://server:3923/folder/?tree=."

# Full tree up to current location
curl "http://server:3923/folder/subfolder/?tree"

tree · string

Tree depth:

• . - One level of subdirectories
• (empty) - Full tree from root to current path

Thumbnails

Get image/video thumbnails:

# Auto-sized thumbnail
curl "http://server:3923/photo.jpg?th" -o thumb.jpg

# Specific width
curl "http://server:3923/photo.jpg?th=w256" -o thumb.jpg

# Specific height  
curl "http://server:3923/photo.jpg?th=h256" -o thumb.jpg

th · string

Thumbnail size:

• (empty) - Auto size
• w{N} - Width in pixels (e.g., w256)
• h{N} - Height in pixels (e.g., h256)

Audio Transcoding

Transcode audio files:

# Transcode to Opus
curl "http://server:3923/song.flac?th=opus" -o song.opus

# Transcode to iOS-compatible CAF
curl "http://server:3923/song.flac?th=caf" -o song.caf

th · string

Audio transcoding:

• opus - 128kbps Opus in WebM container
• caf - Opus in iOS CAF container
• mp3 - MP3 format

Text File Streaming

Stream growing log files:

# Stream from beginning
curl "http://server:3923/app.log?tail"

# Stream from byte 1024
curl "http://server:3923/app.log?tail=1024"

# Stream last 128 bytes
curl "http://server:3923/app.log?tail=-128"

tail · integer

Stream file continuously:

• (empty) - Start from beginning
• Positive number - Start from byte offset
• Negative number - Start N bytes from end

View Text Files

Get text files with specific encoding:

# Default UTF-8
curl "http://server:3923/file.txt?txt"

# Specific encoding
curl "http://server:3923/file.txt?txt=iso-8859-1"

txt · string · default: "utf-8"

Text encoding (e.g., iso-8859-1, cp1252, shift-jis)

ZIP File Access

Access files inside ZIP archives without extracting:

# List ZIP contents
curl "http://server:3923/archive.zip?zls"

# Extract specific file from ZIP
curl "http://server:3923/archive.zip?zget=folder/file.txt"

zls · boolean

List contents of ZIP file

zget · string

Extract and download specific file from ZIP

Markdown Rendering

Render markdown files as HTML:

curl "http://server:3923/README.md?v"

v · boolean

Render markdown as HTML, or open media files in player

Media Player

Open media in browser player:

# Open in audio/video player
curl "http://server:3923/song.mp3?v"

# Open in image gallery
curl "http://server:3923/photo.jpg?v"

MIME Type Override

Force specific MIME type:

curl "http://server:3923/file.bin?mime=application/json"

mime · string

Override MIME type in response headers

Recent Uploads

List recent uploads:

# Your uploads
curl "http://server:3923/?ups"

# All uploads (requires admin permission)
curl "http://server:3923/?ru"

# Filter by path
curl "http://server:3923/?ru&filter=photos"

# JSON format
curl "http://server:3923/?ru&j"

ups · boolean

Show recent uploads from your IP

ru · boolean

Show all recent uploads (requires admin permission)

filter · string

Filter uploads by path substring

Shares

List your shared files/folders:

curl "http://server:3923/?shares"

shares · boolean

List temporary share links you’ve created

Active Downloads

View active downloads (admin only):

curl "http://server:3923/?dls"

dls · boolean

Show currently active downloads (requires admin permission)

Response Headers

Common response headers:

Content-Type: application/octet-stream
Content-Length: 1048576
Content-Disposition: inline; filename="file.txt"
Last-Modified: Mon, 03 Mar 2024 12:00:00 GMT
ETag: "abc123"
Accept-Ranges: bytes

Performance Notes

• Use ?tar instead of ?zip for files > 4 GiB
• Plain ?tar is fastest for large archives (no compression)
• ?tar=gz:3 is good balance of speed and compression
• Range requests support resumable downloads
• Streaming tar works with curl | tar -xv for extraction on-the-fly

• ?zip=crc requires reading each file twice (slower)
• Dotfiles excluded from archives unless you have dot permission
• up2k.db and dir.txt always excluded from archives
• Audio transcoding requires FFmpeg on server