Skip to main content
Every Dreep asset lives in a folder. You can address that folder three ways — by path, by object key, or by id — and any folders in a path that don’t exist yet are created for you.
Upload into a nested path
avatars, 2024 and q1 are created if they don’t already exist — no separate folder calls, no ids to keep track of.

​
Three ways to name a destination

Only one may be given per request. Sending folder together with folderId (or with a key that has a folder prefix) returns 400. Omit all three and the asset lands in your project’s default folder — a real folder created with the project and named after it.

​
Object keys

A key is the whole path, exactly like an S3 object key. Everything before the last / is the folder path; the last segment becomes the stored filename.
A key renames the stored asset — it never reinterprets the bytes. Dreep still detects the real file type from the uploaded file. To actually convert the file, pass format as above.

​
How path segments are normalized

Each segment is slugified: lowercased, with anything outside letters, numbers, _, - and spaces stripped, and runs of spaces/underscores/hyphens collapsed to a single -. This means Marketing Assets/2024 and marketing-assets/2024 are the same folder — you can’t accidentally create two folders that differ only by case or spacing. The original text is kept as the folder’s display name; the slug is what paths resolve against.

​
Limits

  • Depth: up to 10 levels.
  • Segment length: 100 characters after normalization.
  • A segment with no letters or numbers (###, ., ..) is rejected with 400. Path traversal is not possible.

​
Turning off auto-creation

Pass autoCreateFolders=false to require that the path already exists. An unknown path then returns 404 instead of quietly creating a folder tree — useful for catching typos in production.

​
Access control is inherited

When a path creates folders, each new folder inherits accessControlType and defaultExpirySeconds from its parent. Creating invoices/2024/q1 under a private invoices folder produces private subfolders — a new subfolder is never silently public. To set access control explicitly, create the folder first:
accessControlType applies to the leaf (q1); the intermediate folders inherit as usual. See Folders & Access Control.

​
Browsing by path

Every folder and asset comes back with its folder / path, so you never have to reconstruct a path from ids.

​
Coming from S3

The mapping is direct — drop the bucket, keep the key:
Two differences worth knowing:
  1. Folders are real records, not key prefixes. That’s what lets a folder carry access control and signed-URL expiry that its contents inherit.
  2. Paths are slug-normalized, so they are case-insensitive. S3 treats Avatars/ and avatars/ as two different prefixes; Dreep treats them as one folder.
Only empty folders can be deleted. A folder that still contains files or subfolders returns 409 — delete its contents first. Deleting a folder never destroys media, so a mis-click can’t lose data. Your project’s default folder can’t be deleted at all.