Compression API Documentation

Authentication

All API requests require an x-api-key header with your API key. You can find your key on the Settings page.

Cloud Storage API

Upload your original files — we compress and store them in the cloud. Download anytime — we decompress and return your original file. You never handle compressed data.

Upload a File

POST https://smallest.zip/api/{codec}/upload

Upload an uncompressed file. We compress it using the specified codec and store it securely. Returns an uploadId you use to download or manage the file.

Request

Parameter	In	Description
`{codec}`	URL	Codec to use: `dicom`, `dna`, `model-weights`, `geospatial`, `db-dumps`, `fits`, `log-files`, `text-pdf`, `dict-transport`, `audio`, `email`, `segy`
`file`	Form field	The original uncompressed file (multipart/form-data)
`format`	Query	Optional. Sub-format for codecs that support multiple types (e.g. `?format=fastq`)

Response (201 Created)

json

{
  "uploadId": "a8f3b2c1",
  "originalFilename": "reads.fastq",
  "originalBytes": 52428800,
  "compressedBytes": 2359296,
  "codec": "dna",
  "format": "fastq",
  "compressionTimeMs": 1420,
  "createdAt": "2026-03-08T12:00:00Z"
}

Example

bash

# Upload a FASTQ file for compression + storage
curl -X POST "https://smallest.zip/api/dna/upload?format=fastq" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@reads.fastq"

# Upload a PostgreSQL dump
curl -X POST "https://smallest.zip/api/db-dumps/upload?format=postgres" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@backup.sql"

# Upload a DICOM file
curl -X POST "https://smallest.zip/api/dicom/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@brain_ct.dcm"

Download a File

GET https://smallest.zip/api/files/{uploadId}/download

Retrieve your original file. We fetch the compressed version from storage, decompress it, and return the original file.

Response

The original uncompressed file as binary data with Content-Disposition header set to the original filename.

Example

bash

# Download (returns original uncompressed file)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files/a8f3b2c1/download" \
  -o reads.fastq

List Files

GET https://smallest.zip/api/files

List all your stored files, newest first. Includes total storage usage.

Parameter	Default	Description
`limit`	`50`	Number of files to return (max 200)
`offset`	`0`	Number of files to skip

Response

json

{
  "files": [
    {
      "uploadId": "a8f3b2c1",
      "originalFilename": "reads.fastq",
      "originalBytes": 52428800,
      "compressedBytes": 2359296,
      "ratio": 0.0450,
      "codec": "dna",
      "format": "fastq",
      "createdAt": "2026-03-08T12:00:00Z",
      "accessedAt": "2026-03-08T14:30:00Z"
    }
  ],
  "usage": {
    "totalFiles": 12,
    "totalOriginalBytes": 524288000,
    "totalCompressedBytes": 52428800
  }
}

Example

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files?limit=20"

Get File Metadata

GET https://smallest.zip/api/files/{uploadId}

Get detailed metadata for a specific file.

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files/a8f3b2c1"

Delete a File

DELETE https://smallest.zip/api/files/{uploadId}

Permanently delete a file from cloud storage.

bash

curl -X DELETE -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files/a8f3b2c1"

Error Responses

Status	Meaning
`400`	Bad request — missing file, empty body, invalid format
`401`	Missing or invalid API key
`402`	No credits remaining
`404`	Unknown codec or file not found
`409`	Duplicate — file already uploaded (returns existing `uploadId`)
`500`	Compression or decompression failed
`503`	Cloud storage not configured

Supported Codecs

Each codec is optimized for a specific data type. Use the codec name in the upload URL: /api/{codec}/upload

DICOM — Medical Image Compression

Codec: dicom

Input	`.dcm` DICOM file (single-frame or multi-frame)
Lossless	Yes — bitwise exact roundtrip

bash

curl -X POST "https://smallest.zip/api/dicom/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@brain_ct.dcm"

DNA — Genomic Data Compression

Codec: dna — select format via ?format= query parameter.

Format	Query Param	Input
FASTQ	`?format=fastq` (default)	`.fastq` / `.fq`
BAM	`?format=bam`	`.bam`
VCF	`?format=vcf`	`.vcf`

All formats are fully lossless — downloaded file is bit-identical to the original.

bash

# Upload FASTQ
curl -X POST "https://smallest.zip/api/dna/upload?format=fastq" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@reads.fastq"

# Upload BAM
curl -X POST "https://smallest.zip/api/dna/upload?format=bam" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@aligned.bam"

Model Weights — ML Weight Compression

Codec: model-weights

Input	`.safetensors` or `.pt` model files
Quality	Near-lossless

Parameter	Default	Description
`drop_bits`	`1`	Mantissa bits to truncate (1–4)

bash

curl -X POST "https://smallest.zip/api/model-weights/upload?drop_bits=2" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@model.safetensors"

Geospatial — Map & Satellite Data Compression

Codec: geospatial — select format via ?format= query parameter.

Format	Query Param	Input
GeoJSON	`?format=geojson` (default)	`.geojson`
GeoTIFF	`?format=geotiff`	`.tif`
Shapefile	`?format=shapefile`	`.shp`
LiDAR	`?format=lidar`	`.las`

Parameter	Default	Description
`precision`	`6`	Coordinate decimal places for GeoJSON (6 = ~11cm accuracy)
`simplify`	`0.0`	Simplification tolerance (0 = none)

bash

# Upload GeoJSON
curl -X POST "https://smallest.zip/api/geospatial/upload?format=geojson&precision=5" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@countries.geojson"

# Upload LiDAR point cloud
curl -X POST "https://smallest.zip/api/geospatial/upload?format=lidar" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@survey.las"

Database Dumps — SQL & Document Store Compression

Codec: db-dumps — select format via ?format= query parameter.

Format	Query Param	Input
PostgreSQL	`?format=postgres` (default)	`pg_dump` SQL
MySQL	`?format=mysql`	`mysqldump` SQL
MongoDB	`?format=mongodb`	BSON export
Oracle	`?format=oracle`	SQL export
SQL Server	`?format=mssql`	SQL export

bash

# Upload a PostgreSQL dump
curl -X POST "https://smallest.zip/api/db-dumps/upload?format=postgres" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@backup.sql"

# Upload MongoDB BSON
curl -X POST "https://smallest.zip/api/db-dumps/upload?format=mongodb" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@collection.bson"

FITS — Astronomical Image Compression

Codec: fits

Input	`.fits` astronomical image
Lossless	Yes

Parameter	Default	Description
`tile_size`	`256`	Tile size for tiled processing (64–1024)

bash

curl -X POST "https://smallest.zip/api/fits/upload?tile_size=128" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@galaxy.fits"

Log Files — Log Compression

Codec: log-files

Input	Plain text log data (syslog, application logs, security logs)
Lossless	Yes

Parameter	Default	Description
`level`	`balanced`	`fast`, `balanced`, or `max`

bash

curl -X POST "https://smallest.zip/api/log-files/upload?level=max" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@syslog.log"

PDF — PDF Compression

Codec: text-pdf

Input	`.pdf` text-heavy PDF
Best for	Multi-page reports, academic papers, legal documents
Lossless	Yes — all text and structure preserved

bash

curl -X POST "https://smallest.zip/api/text-pdf/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@report.pdf"

Web Assets — JS, CSS, HTML Compression

Codec: dict-transport

Input

JS, CSS, or HTML file content

Parameter	Default	Description
`type`	`js`	Asset type: `js`, `css`, or `html`

bash

curl -X POST "https://smallest.zip/api/dict-transport/upload?type=js" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@app.bundle.js"

Audio — Archival Audio Compression

Codec: audio — select quality via ?quality= query parameter.

Quality	Query Param	Description
Lossless	`?quality=lossless`	Bit-perfect reconstruction
High	`?quality=high`	Transparent quality (indistinguishable)
Medium	`?quality=medium` (default)	High quality, minor spectral differences
Low	`?quality=low`	Good quality, suitable for speech/podcasts

Input formats	`.wav`, `.flac`, `.mp3`, `.ogg`
Best for	Music archives, podcast libraries, audio production backups, call center recordings

bash

# Upload a WAV file (default medium quality)
curl -X POST "https://smallest.zip/api/audio/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@recording.wav"

# Upload with lossless quality
curl -X POST "https://smallest.zip/api/audio/upload?quality=lossless" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@master.flac"

# Upload MP3 for archival
curl -X POST "https://smallest.zip/api/audio/upload?quality=high" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@podcast.mp3"

Email — mbox Archive Compression

Codec: email

Input	`.mbox` email archive
Lossless	Yes — byte-exact roundtrip
Best for	Email archival, compliance retention, mailbox backups

Attachments are decoded from base64, deduplicated across all archives, and stored once.

bash

# Upload an mbox archive
curl -X POST "https://smallest.zip/api/email/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@inbox.mbox"

# Download (returns original mbox)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files/{uploadId}/download" \
  -o inbox_restored.mbox

SEG-Y — Seismic Data Compression

Codec: segy — select quality via ?quality= query parameter.

Quality	Description
`archive` (default)	Best fidelity
`balanced`	Good fidelity, higher compression
`streaming`	Fast preview

Input formats	`.segy`, `.sgy`
Lossy	Yes
Best for	Seismic survey archival, exploration data

bash

# Upload a SEG-Y file (default archive quality)
curl -X POST "https://smallest.zip/api/segy/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@survey_3d.segy"

# Upload with balanced quality for higher compression
curl -X POST "https://smallest.zip/api/segy/upload?quality=balanced" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@survey_3d.segy"

# Download (returns original SEG-Y)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://smallest.zip/api/files/{uploadId}/download" \
  -o survey_restored.segy

Video — AV1 Compression

POST /api/compress

Upload any video format (MP4, MOV, AVI, MKV, WebM, etc.) as multipart/form-data. Returns an AV1-encoded MP4 directly.

Input	Any video format (field name: `video`)
Output	AV1-encoded `.mp4` (returned directly)
Max size	500 MB

bash

curl -X POST https://smallest.zip/api/compress \
  -H "x-api-key: YOUR_API_KEY" \
  -F "video=@input.mp4" \
  --output compressed_av1.mp4

Image Compression

POST https://smallest.zip/api/compress

Upload a JPEG image as multipart/form-data. Returns the compressed image directly as binary data.

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	`multipart/form-data`	Yes

Multipart form data with a field named image containing the JPEG file.

bash

curl -X POST https://smallest.zip/api/compress \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  --output compressed.jpg

Python Client Library

python

import requests

API_URL = "https://smallest.zip/api"
API_KEY = "YOUR_API_KEY"

def upload(codec, file_path, **params):
    """Upload a file for compression + cloud storage. Returns uploadId."""
    qs = "&".join(f"{k}={v}" for k, v in params.items())
    url = f"{API_URL}/{codec}/upload"
    if qs:
        url += f"?{qs}"

    with open(file_path, "rb") as f:
        resp = requests.post(
            url,
            headers={"x-api-key": API_KEY},
            files={"file": (file_path, f)},
        )
    resp.raise_for_status()
    result = resp.json()

    print(f"{codec}: {result['originalBytes']:,} bytes "
          f"-> {result['compressedBytes']:,} bytes "
          f"({result['savings']}) in {result['compressionTimeMs']}ms")
    return result["uploadId"]

def download(upload_id, output_path):
    """Download and decompress a stored file."""
    resp = requests.get(
        f"{API_URL}/files/{upload_id}/download",
        headers={"x-api-key": API_KEY},
    )
    resp.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(resp.content)
    print(f"Downloaded {len(resp.content):,} bytes to {output_path}")

def list_files(limit=50):
    """List all stored files."""
    resp = requests.get(
        f"{API_URL}/files",
        headers={"x-api-key": API_KEY},
        params={"limit": limit},
    )
    resp.raise_for_status()
    return resp.json()

def delete_file(upload_id):
    """Delete a stored file."""
    resp = requests.delete(
        f"{API_URL}/files/{upload_id}",
        headers={"x-api-key": API_KEY},
    )
    resp.raise_for_status()
    return resp.json()

# Usage examples
uid = upload("dna", "reads.fastq", format="fastq")
download(uid, "reads_restored.fastq")

upload("dicom", "brain_ct.dcm")
upload("geospatial", "map.geojson", format="geojson")
upload("db-dumps", "backup.sql", format="postgres")
upload("log-files", "app.log", level="max")
upload("fits", "galaxy.fits")
upload("model-weights", "model.safetensors", drop_bits=2)
upload("text-pdf", "paper.pdf")
upload("audio", "recording.wav", quality="medium")
upload("email", "inbox.mbox")

# List and manage files
files = list_files()
for f in files["files"]:
    print(f"{f['uploadId']} - {f['originalFilename']} ({f['savings']})")