Concepts

Spaces

A space is an isolated container for assets. Each space has:

• A unique handle (auto-generated 6-character string) used in CDN URLs
• Its own API keys, upload configs, folders, and access controls

Users can create and manage spaces from the Tuzzle dashboard. Each space operates independently with its own settings.

Files

A file is an uploaded asset stored in cloud storage. Each file has:

• A generated name (ULID-based) used as the storage identifier
• The original_name preserved from the upload
• A storage_path combining the space handle and file name: {handle}/{name}
• A resource_type: image, video, audio, text, document, archive, or other
• A type that controls access: upload, private, or authenticated
• A status: active (ready) or pending (presigned upload in progress)

Folders

Folders provide hierarchical organization within a space. They support:

• Nested parent-child relationships
• Inherited access control (files inherit folder settings)
• Path-based references (e.g., photos/vacation/)

Upload Configs

An upload config defines rules for how files are uploaded and processed:

• Storage: folder path, filename generation, uniqueness
• Validation: allowed formats, max file size, image dimension limits
• Transformations: upload quality, format conversion, eager transforms
• Metadata: auto-tagging, default tags
• Notifications: webhook URL for upload events

Each space has at least one upload config. The "starter" config is created automatically.

File Access Types

Access control can be set at the space, folder, or file level and cascades downward.

API Keys

API keys are space-scoped credentials for programmatic access. They use the prefix sk_ and can be used as Bearer tokens. API keys:

• Are scoped to a single space
• Can be revoked independently
• Track last usage time
• Support optional expiration

Create and manage API keys from the Tuzzle dashboard or via the API.

Signed URLs

Signed URLs are time-limited, HMAC-signed links that grant temporary access to protected files. They contain:

• An expires timestamp (Unix epoch)
• A signature (HMAC-SHA256 hash)

Signed URLs are used to grant temporary access to private and authenticated files without exposing your API key.

Transformations

Transformations modify images on the fly via URL query parameters:

Transformed images are cached automatically, so subsequent requests are served instantly without reprocessing.

Blurhash

A blurhash is a compact string representation of an image placeholder. Tuzzle automatically generates blurhash values for uploaded images and returns them in the x-blurhash response header during delivery.