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

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.

Delete a folder

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

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