Core Concepts
Understand the fundamental building blocks of SuperFiles.
Core Concepts
Buckets
A bucket is a top-level namespace for your files — like a folder at the root of your storage. Every file belongs to exactly one bucket.
| Property | Description |
|---|---|
slug |
URL-safe name used in all API paths and CDN URLs (e.g. my-media) |
public |
When true, objects are accessible without authentication via a CDN URL |
storageUsed |
Total bytes consumed by all objects in the bucket |
Buckets are scoped to a team. Each team can have multiple buckets.
Objects
An object is a file stored in a bucket. Objects have:
- A key — the path within the bucket (e.g.
images/avatar.jpg). Slashes in the key create virtual folders; there are no real folder entities. - A content hash — SHA-256 of the file contents. Identical files share the same underlying blob (deduplication).
- Metadata — content type, size, custom headers.
- Visibility — inherits the bucket’s
publicsetting unless individually overridden with a presigned URL.
Virtual folders
SuperFiles has no real folder objects. “Folders” emerge from the /-separated segments of an object key. The Storage API supports prefix-based listing:
# List everything under "images/"
GET /v1/storage/my-bucket?prefix=images/&delimiter=/The WebDAV and S3-shim interfaces both expose virtual folders as first-class directory entries.
API keys
API keys authenticate requests to the Storage API and the Management API.
| Scope | What it grants |
|---|---|
storage:read |
Download objects, list buckets/objects |
storage:write |
Upload, delete, copy, move objects |
buckets:manage |
Create, update, delete buckets |
admin |
Team management, billing, all admin endpoints |
Keys are hashed (SHA-256) at rest. If a key is compromised, revoke it from Settings → API Keys — the hash is immediately invalidated.
CDN transforms
When a bucket has CDN enabled, SuperFiles proxies object URLs through an image transform service. Append query parameters to transform on the fly:
https://cdn.superfiles.montr.online/my-bucket/photo.jpg?w=800&h=600&fit=cover&format=webp&q=85| Parameter | Description |
|---|---|
w |
Output width in pixels |
h |
Output height in pixels |
fit |
cover | contain | fill | inside | outside |
format |
webp | avif | jpeg | png | gif |
q |
Quality 1–100 (lossy formats only) |
blur |
Gaussian blur radius |
sharpen |
Boolean; applies an unsharp mask |
rotate |
Degrees: 90 | 180 | 270 |
flip |
h (horizontal) or v (vertical) |
Transformed images are cached at the CDN edge. Cache keys include all transform parameters.
Storage backend
SuperFiles writes blobs to a content-addressed local store by default (~/.superfiles/blobs/<sha256-prefix>/<sha256>). Each unique blob is stored once regardless of how many objects reference it — deduplication is built in.
An optional S3-compatible backend (R2, MinIO, etc.) can be configured for the blob store, while metadata stays in SQLite.
Teams
All resources — buckets, API keys, billing — are owned by a team. Users can belong to multiple teams with different roles (owner, admin, member).