Upload Endpoints

Complete API reference for file upload endpoints.

Upload endpoints are part of the Upload API tier, designed for high-throughput production use. All endpoints are under /api/v1/upload.

POST /upload

Upload one or more files. Requires authentication.

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

Parameters:

Field	Type	Required	Validation
`file`	file	Yes (or `files`)	Max 50MB
`files`	file	Yes (or `file`)	Each max 50MB
`space`	string	Yes	Must be valid space handle
`upload_config`	string	No	Upload config ID
`folder_id`	string	No	Valid folder ID
`folder_path`	string	No	Valid folder path (requires `folder_id`)

Response:

{
  "data": {
    "id": "01HQ...",
    "name": "image-01HQ...",
    "original_name": "photo.jpg",
    "mime_type": "image/jpeg",
    "size": 245000,
    "storage_path": "a1b2c3/image-01HQ...",
    "type": "upload",
    "resource_type": "image",
    "status": "active"
  }
}

POST /upload/generate-signed-url

Generate a signed URL for client-side uploads. Requires authentication.

curl -X POST https://api.tzzl.io/api/v1/upload/generate-signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_config_id": "01HQ...",
    "expiration_minutes": 30,
    "filename": "photo.jpg",
    "content_type": "image/jpeg"
  }'

Parameters:

Field	Type	Required	Description
`upload_config_id`	string	Yes	Upload config to validate against
`expiration_minutes`	integer	No	URL validity period
`filename`	string	No	Suggested filename
`content_type`	string	No	Expected MIME type

POST /upload/signed

Upload a file using a signed URL. Auth is handled via the signed URL signature.

curl -X POST "SIGNED_URL" \
  -F "[email protected]" \
  -F "upload_config_id=01HQ..." \
  -F "space_id=01HQ..."

Parameters:

Field	Type	Required
`file`	file	Yes
`upload_config_id`	string	Yes
`space_id`	string	Yes

POST /upload/unsigned/:spaceHandle/:configName

Public upload without authentication. The upload config must have allow_unsigned: true.

curl -X POST https://api.tzzl.io/api/v1/upload/unsigned/a1b2c3/user-avatars \
  -F "[email protected]"

Unsigned uploads are rate-limited separately from authenticated uploads. The API validates the Referer header against the config's allowed_referrers list.

POST /upload/presign

Generate a presigned PUT URL for direct-to-storage uploads. Requires authentication.

curl -X POST https://api.tzzl.io/api/v1/upload/presign \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "space": "a1b2c3",
    "filename": "video.mp4",
    "content_type": "video/mp4",
    "size": 104857600
  }'

Parameters:

Field	Type	Required	Validation
`space`	string	Yes	Valid space handle
`filename`	string	Yes	Max 255
`content_type`	string	Yes	Max 100
`size`	integer	Yes	Min 1
`upload_config`	string	No	Valid config name
`ref`	string	No	Custom reference, max 255

Response:

{
  "file_id": "01HQ...",
  "upload_url": "https://...r2.cloudflarestorage.com/...",
  "object_key": "a1b2c3/video-01HQ...",
  "expires_in": 3600
}

The file is created with status: "pending".

POST /upload/confirm/:fileId

Confirm that a presigned upload has completed. Requires authentication.

curl -X POST https://api.tzzl.io/api/v1/upload/confirm/FILE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

The API verifies the object exists in cloud storage, then changes the file status from pending to active.

PreviousFolder Endpoints NextUpload Config Endpoints