Skip to content
SuperFiles Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 public setting 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 is public, SuperFiles serves objects through a CDN endpoint that applies on-the-fly transforms. Transform directives are path-based — they sit between the bucket slug and the object key:

https://superfiles-api.example.com/cdn/{bucket}/{transforms}/{key}

# Examples
https://superfiles-api.example.com/cdn/media/f_webp,h_600,w_800/photo.jpg
https://superfiles-api.example.com/cdn/media/c_cover,f_auto,h_300,w_300/avatar.jpg

Directives are comma-separated in alphabetical order (the server normalises the order automatically).

Directive Values Description
c_X contain cover fill crop Fit/crop mode (default: contain)
f_X webp avif jpg png auto Output format; auto picks the best from the Accept header
h_N 1–8000 Output height in pixels
q_N 1–100 Quality for lossy formats (default: 85)
t_N ≥ 0 Video: extract frame at N seconds
w_N 1–8000 Output width in pixels

Omit the transform segment to serve the original file without processing:

https://superfiles-api.example.com/cdn/media/photo.jpg

Transformed variants are cached immutably (Cache-Control: public, max-age=31536000, immutable). Original files are cached for one hour.

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).

Was this page helpful?