TuzzleTuzzle Docs

Upload Overview

All the ways to upload files to Tuzzle.

Tuzzle provides multiple upload methods to suit different use cases, from simple authenticated uploads to client-side unsigned uploads.

Upload Methods

MethodAuth RequiredUse Case
Direct UploadBearer tokenServer-side uploads from your backend
Signed UploadSigned URLTime-limited client-side uploads
Unsigned UploadNonePublic upload widgets, UGC
Presigned URLsBearer tokenLarge files uploaded directly to cloud storage

How Upload Works

  1. Your application sends a file to the Tuzzle API
  2. The API validates the file against the active upload config
  3. The file is stored in cloud storage with a generated name
  4. A database record is created with metadata
  5. Post-upload jobs run: metadata extraction, blurhash generation, eager transforms, webhooks

File Naming

Uploaded files receive a generated name using the pattern {prefix}-{ulid}:

  • Images: image-01HQ...
  • Videos: video-01HQ...
  • Audio: audio-01HQ...
  • Documents: doc-01HQ...
  • Other: file-01HQ...

The original filename is preserved in the original_name field.

File Size Limits

  • Default maximum: 50 MB per file
  • Configurable per upload config via config.validation.max_file_size
  • Empty files are rejected

Supported Formats

By default, all safe file types are accepted. Dangerous extensions are blocked, including executable files (.exe, .bat, .sh), server scripts (.php, .asp, .jsp), and double extensions (e.g., photo.jpg.php).

You can restrict allowed formats per upload config using the config.validation.allowed_formats field.

Multi-File Upload

The direct upload endpoint accepts either a single file or an array of files:

# Single file
curl -X POST https://api.tzzl.io/api/v1/upload \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -F "[email protected]" \
  -F "space=a1b2c3"

# Multiple files
curl -X POST https://api.tzzl.io/api/v1/upload \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -F "files[][email protected]" \
  -F "files[][email protected]" \
  -F "space=a1b2c3"

Post-Upload Processing

After a successful upload, Tuzzle automatically:

  1. Extracts metadata: dimensions, EXIF data
  2. Generates blurhash: compact placeholder string (after ~5s)
  3. Processes eager transforms: pre-defined transformations from the upload config (after ~10s)
  4. Validates integrity: confirms the upload is complete
  5. Sends webhooks: notifies your configured URL (if set)
PreviousAuthenticationNextDirect Upload