Upload Configs

Configure validation rules, transformations, and upload behaviors.

Upload configs define how files are validated, processed, and stored when uploaded to a space. Each space has at least one config (the auto-created "starter" config).

Creating an Upload Config

curl -X POST https://api.tzzl.io/api/v1/upload-configs \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-images",
    "description": "Config for product catalog images",
    "space_id": "01HQ...",
    "delivery_type": "upload",
    "config": {
      "validation": {
        "allowed_formats": "jpg,png,webp",
        "max_file_size": 10485760
      },
      "transformations": {
        "upload_quality": "auto",
        "upload_format": "original"
      }
    }
  }'

Config Structure

The config field is a JSON object with these sections:

Storage

{
  "storage": {
    "folder": "products/images",
    "generate_filename": true,
    "unique_filename": true
  }
}

Field	Type	Description
`folder`	string	Target folder path for uploads
`generate_filename`	boolean	Auto-generate filenames
`unique_filename`	boolean	Ensure filename uniqueness

Validation

{
  "validation": {
    "allowed_formats": "jpg,png,webp,avif",
    "max_file_size": 10485760,
    "min_image_width": 200,
    "min_image_height": 200,
    "max_image_width": 4000,
    "max_image_height": 4000
  }
}

Field	Type	Description
`allowed_formats`	string	Comma-separated list of allowed extensions
`max_file_size`	integer	Maximum file size in bytes (default: 50 MB)
`min_image_width`	integer	Minimum image width in pixels
`min_image_height`	integer	Minimum image height in pixels
`max_image_width`	integer	Maximum image width in pixels
`max_image_height`	integer	Maximum image height in pixels

Transformations

{
  "transformations": {
    "upload_quality": "auto",
    "upload_format": "original",
    "progressive": true,
    "strip_metadata": true,
    "eager": [
      { "width": 200, "height": 200, "crop": "thumb" },
      { "width": 800, "height": 600, "crop": "fill" }
    ]
  }
}

Field	Type	Description
`upload_quality`	string	`auto`, `original`, or `1-100`
`upload_format`	string	`original`, `auto`, `jpeg`, `png`, `webp`, `avif`, `tiff`, `gif`, `pdf`
`progressive`	boolean	Enable progressive JPEG encoding
`strip_metadata`	boolean	Remove EXIF/metadata on upload
`eager`	array	Pre-generate these transformations on upload

Eager transforms run automatically after upload (~10s delay). Each transform specifies width, height, and crop mode (fill, fit, crop, thumb, scale).

Metadata

{
  "metadata": {
    "tags": ["product", "catalog"],
    "auto_tagging": true
  }
}

Field	Type	Description
`tags`	array	Tags auto-applied to uploaded files
`auto_tagging`	boolean	Enable automatic tag generation

Notifications

{
  "notifications": {
    "webhook_url": "https://your-app.com/webhooks/tuzzle"
  }
}

Delivery Types

The delivery_type field controls file access after upload:

Type	Behavior
`upload`	Public access, no authentication needed for delivery
`private`	Signed URL required for URL generation, public delivery after
`authenticated`	Signed URL required for all access, no CDN caching

Unsigned Upload Support

To enable unsigned uploads, set allow_unsigned: true and provide unsigned_restrictions:

{
  "allow_unsigned": true,
  "unsigned_restrictions": {
    "allowed_referrers": ["example.com"],
    "require_https": true,
    "max_uploads_per_hour": 50
  }
}

Managing Configs

List All Configs

curl https://api.tzzl.io/api/v1/upload-configs/all \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Update a Config

curl -X POST https://api.tzzl.io/api/v1/upload-configs/update \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01HQ...",
    "name": "updated-config",
    "config": { ... }
  }'

Delete a Config

curl -X DELETE https://api.tzzl.io/api/v1/upload-configs \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "id": "01HQ..." }'

Setting the Active Config

Each space has an active upload config used as the default when uploading files without specifying a config. You can set the active config from the Tuzzle dashboard in your space settings.

PreviousPresigned URLs NextWebhooks