Direct Upload
Upload files directly with Bearer token authentication.
Direct upload is the simplest method. Send files to the API with a Bearer token from your backend.
Basic Upload
curl -X POST https://api.tzzl.io/api/v1/upload \
-H "Authorization: Bearer sk_a1b2c3d4..." \
-F "[email protected]" \
-F "space=a1b2c3"
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",
"extension": "jpg"
}
}
Parameters
| Parameter | Required | Description |
|---|---|---|
file | Yes (or files) | Single file to upload |
files | Yes (or file) | Array of files to upload |
space | Yes | Space handle |
upload_config | No | Upload config ID (uses space default if omitted) |
folder_id | No | Target folder ID |
folder_path | No | Target folder path (requires folder_id) |
Upload to a Folder
curl -X POST https://api.tzzl.io/api/v1/upload \
-H "Authorization: Bearer sk_a1b2c3d4..." \
-F "[email protected]" \
-F "space=a1b2c3" \
-F "folder_id=01HQ..." \
-F "folder_path=photos/vacation/"
Using a Specific Upload Config
curl -X POST https://api.tzzl.io/api/v1/upload \
-H "Authorization: Bearer sk_a1b2c3d4..." \
-F "[email protected]" \
-F "space=a1b2c3" \
-F "upload_config=01HQ..."
The upload config controls validation rules (allowed formats, max size, dimension limits) and post-upload transformations.
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"
Each file is validated and stored independently. The response includes an array of file records.
Using an API Key
You can use a space-scoped API key (sk_ prefix) instead of a user token:
curl -X POST https://api.tzzl.io/api/v1/upload \
-H "Authorization: Bearer sk_..." \
-F "[email protected]" \
-F "space=a1b2c3"
Error Handling
Common upload errors:
| Status | Reason |
|---|---|
| 401 | Invalid or missing authentication |
| 413 | File exceeds maximum size (50 MB default) |
| 422 | Validation failed (blocked format, dimension limits, etc.) |
| 429 | Rate limit exceeded |