Folders

All folder operations live on vaze.folders. Every method returns the response envelope.

The Folder object

type Folder = {
  id: string;
  name: string;
  key: string; // path relative to the storage root; "" for the root folder
  parentId: string | null; // null for the root folder
  createdAt: string;
  updatedAt: string;
};

Browse a folder

get() returns the files and direct subfolders of a folder. Call it with no arguments for the root folder, or target a specific folder by id or by key:

// root folder
const root = await vaze.folders.get();

// by id
const byId = await vaze.folders.get({ id: "folder-id" });

// by key
const byKey = await vaze.folders.get({ key: "projects/demo" });

// data => { files: File[], folders: Folder[] }

It also accepts the same ListOptions as the file methods to paginate and sort the files inside the folder:

const { data, error } = await vaze.folders.get({
  key: "projects/demo",
  limit: 50,
  orderBy: "name",
  orderDirection: "ASC",
});

Create a folder

Pass a path relative to the root folder — intermediate folders are created automatically:

const { data, error } = await vaze.folders.create("projects/demo/assets");

// data => { folder: Folder } — the deepest folder in the path

Folder names may contain dots (release/v1.0 is fine). Only the segments . and .., path separators inside a name, and NUL bytes are rejected.

Rename a folder

const { error } = await vaze.folders.rename({
  id: "folder-id",
  name: "new-name",
});

Renaming a folder also rewrites the keys of everything inside it. A sibling folder with the same name causes a 409 error, and the root folder cannot be renamed at all (400).

Move a folder

const { data, error } = await vaze.folders.move({
  id: "folder-id",
  folder: "archive/2025", // or: folderId: "folder-id"
});

// data => { folder: Folder } at its new key

Everything inside moves with it, and the keys of all its files and subfolders are rewritten. folder is created if missing and "" is the root. A clash in the destination returns 409; moving the root, or moving a folder into itself or one of its own subfolders, returns 400.

Change visibility in bulk

const { error } = await vaze.folders.setVisibility({
  id: "folder-id",
  visibility: "private",
});

Applies the visibility to every file in the folder and all its subfolders, in a single transaction.

This is a bulk write, not an inherited setting — folders don't carry a visibility of their own, so a file uploaded into the folder afterwards takes the instance default rather than the last cascade. Unlike rename, the root folder is a valid target, which locks down an entire instance in one call.

Download a folder as a zip

const { data, error } = await vaze.folders.download({ key: "projects/demo" });

if (data) {
  // "demo.zip", with every entry under demo/
  await fs.writeFile(data.filename ?? "folder.zip", Buffer.from(await data.blob.arrayBuffer()));
}

Pass id or key; with neither, the root folder is archived as files.zip. Subfolders are kept, empty ones included. Like files.download, the archive is read into a Blob, so stream the endpoint with fetch for archives too large to hold in memory. downloadUrl returns the URL it reads, to request yourself with authHeaders():

vaze.folders.downloadUrl({ id: "folder-id" }); // what download() fetches

Delete a folder

const { error } = await vaze.folders.delete("folder-id");

The root folder cannot be deleted (400) — it holds the entire storage tree.