Files

Managing files, listing, updating, and deleting assets.

Files are the core asset type in Tuzzle. Each file belongs to a space and can optionally be organized into folders.

File Properties

Field	Description
`id`	ULID primary key
`name`	Generated storage name (e.g., `image-01HQ...`)
`original_name`	Original filename from upload
`mime_type`	MIME type (e.g., `image/jpeg`)
`size`	File size in bytes
`storage_path`	Storage object key (`{handle}/{name}`)
`type`	Access type: `upload`, `private`, `authenticated`
`resource_type`	`image`, `video`, `audio`, `text`, `document`, `archive`, `other`
`status`	`active` or `pending`
`extension`	File extension (derived from MIME type)
`ref`	Optional custom reference string
`public_id`	Public identifier (defaults to `name`)
`folder_path`	Path of the containing folder

Listing Files

List files in a space with cursor pagination:

curl "https://api.tzzl.io/api/v1/files?space_id=SPACE_ID&limit=20" \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Query Parameters

Parameter	Description
`space_id`	Required. The space to list files from
`limit`	Number of files per page
`cursor`	Cursor for pagination

Get a File

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

Get a File by Reference

Look up a file by its custom reference:

curl "https://api.tzzl.io/api/v1/files/by-ref?space_id=SPACE_ID&ref=my-custom-ref" \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Update a File

curl -X PUT https://api.tzzl.io/api/v1/files \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01HQ...",
    "name": "new-name",
    "original_name": "renamed-photo.jpg",
    "folder_id": "01HQ...",
    "folder_path": "photos/"
  }'

Updatable Fields

Field	Type	Description
`name`	string	Storage name (max 255 chars)
`original_name`	string	Display name (max 255 chars)
`mime_type`	string	MIME type
`size`	integer	File size
`storage_path`	string	Storage path
`space`	string	Space handle (to move between spaces)
`folder_id`	string	Target folder ID
`folder_path`	string	Target folder path

Delete a File

curl -X DELETE https://api.tzzl.io/api/v1/files/FILE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Deleting a file removes:

The file record from the database
The original file from cloud storage
All cached transformed variants

File Access Control

Update access control for a specific file:

curl -X PUT https://api.tzzl.io/api/v1/files/FILE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": true
    }
  }'

Reset to inherited defaults:

curl -X DELETE https://api.tzzl.io/api/v1/files/FILE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Generate a Signed URL

For private or authenticated files:

curl -X POST https://api.tzzl.io/api/v1/files/FILE_ID/signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..."

File Metadata

The storage_meta field contains image-specific metadata that is synced by the CDN after the first delivery:

{
  "width": 1920,
  "height": 1080,
  "blur_hash": "LEHV6nWB2yk8...",
  "face_detections": [
    { "left": 150, "top": 80, "width": 200, "height": 250 }
  ]
}

Resource Types

Files are automatically classified by MIME type:

Resource Type	MIME Types
`image`	`image/*`
`video`	`video/*`
`audio`	`audio/*`
`text`	`text/*`
`document`	`application/pdf`, `application/msword`, etc.
`archive`	`application/zip`, `application/gzip`, etc.
`other`	Everything else

PreviousRate Limiting NextFolders