Upload Config Endpoints

Complete API reference for upload configuration endpoints.

Upload config endpoints are part of the Admin API tier. All endpoints are under /api/v1/upload-configs and require API key authentication.

GET /upload-configs

List upload configs with pagination.

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

GET /upload-configs/all

List all upload configs across the user's spaces (simple pagination).

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

GET /upload-configs/:id

Get a single upload config with its full config object visible.

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

Response:

{
  "data": {
    "id": "01HQ...",
    "name": "product-images",
    "description": "Config for product catalog images",
    "space_id": "01HQ...",
    "is_signed": false,
    "allow_unsigned": false,
    "delivery_type": "upload",
    "config": {
      "storage": {
        "folder": "products",
        "generate_filename": true,
        "unique_filename": true
      },
      "validation": {
        "allowed_formats": "jpg,png,webp",
        "max_file_size": 10485760,
        "min_image_width": null,
        "min_image_height": null,
        "max_image_width": 4000,
        "max_image_height": 4000
      },
      "transformations": {
        "upload_quality": "auto",
        "upload_format": "original",
        "progressive": true,
        "strip_metadata": false,
        "eager": []
      },
      "metadata": {
        "tags": [],
        "auto_tagging": false
      },
      "notifications": {
        "webhook_url": null
      }
    }
  }
}

The config field is hidden in list responses and only visible when fetching a single config by ID.

POST /upload-configs

Create a new 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": "avatars",
    "space_id": "01HQ...",
    "delivery_type": "upload",
    "config": {
      "validation": {
        "allowed_formats": "jpg,png,webp",
        "max_file_size": 5242880
      },
      "transformations": {
        "eager": [
          { "width": 64, "height": 64, "crop": "thumb" },
          { "width": 200, "height": 200, "crop": "thumb" }
        ]
      }
    }
  }'

Parameters:

Field	Type	Required	Description
`name`	string	Yes	Config name
`description`	string	No	Description
`space_id`	string	Yes	Parent space
`is_signed`	boolean	No	Require signed URLs for upload
`allow_unsigned`	boolean	No	Allow public unsigned uploads
`delivery_type`	string	No	`upload`, `private`, or `authenticated`
`config`	object	No	Full config object (see below)
`unsigned_restrictions`	object	Conditional	Required when `allow_unsigned` is `true`

Config object structure:

{
  "storage": {
    "folder": "string",
    "generate_filename": "boolean",
    "unique_filename": "boolean"
  },
  "validation": {
    "allowed_formats": "string (comma-separated)",
    "max_file_size": "integer (bytes)",
    "min_image_width": "integer|null",
    "min_image_height": "integer|null",
    "max_image_width": "integer|null",
    "max_image_height": "integer|null"
  },
  "transformations": {
    "upload_quality": "auto|original|1-100",
    "upload_format": "original|auto|jpeg|png|webp|avif|tiff|gif|pdf",
    "progressive": "boolean",
    "strip_metadata": "boolean",
    "eager": [{ "width": "int", "height": "int", "crop": "string" }]
  },
  "metadata": {
    "tags": ["string"],
    "auto_tagging": "boolean"
  },
  "notifications": {
    "webhook_url": "string|null"
  }
}

Unsigned restrictions (when allow_unsigned: true):

Field	Type	Required	Validation
`unsigned_restrictions.allowed_referrers`	string	Yes	Min 1 item, domain regex pattern
`unsigned_restrictions.require_https`	boolean	Yes
`unsigned_restrictions.max_uploads_per_hour`	integer	No	1-1000

POST /upload-configs/update

Update an existing upload config. Uses POST instead of PUT.

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-avatars",
    "config": { ... }
  }'

DELETE /upload-configs

Delete an upload config. Requires the config ID in the request body.

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

PreviousUpload Endpoints NextErrors