Files

All file operations live on vaze.files. Every method returns the response envelope — check error before using data.

The `File` object

File objects returned by the SDK look like this:

type File = {
  id: string;
  name: string; // unique within its folder
  key: string; // object key, e.g. "projects/demo/photo.png"
  mimeType: string; // e.g. "image/png"
  size: number; // bytes
  folderId: string;
  visibility: "public" | "private";
  url: string; // absolute hosting URL
  createdAt: string;
  updatedAt: string;
};

For a public file, url is ready to embed in an <img> tag or share directly. For a private file the same URL is the canonical address but returns 404 without credentials — use sign to get a link that works.

List options

Methods that return multiple files accept an optional ListOptions object:

type ListOptions = {
  limit?: number; // default: no limit
  offset?: number; // default: 0
  orderBy?: "createdAt" | "updatedAt" | "name" | "size"; // default: "createdAt"
  orderDirection?: "ASC" | "DESC"; // default: "DESC"
};

Upload files

Upload one or more File objects (Web API File, e.g. from fetch, form inputs, or Node's fs.openAsBlob). Optionally pass a target folder path — nested folders are created automatically:

const { data, error } = await vaze.files.upload({
  files: [new File(["hello"], "hello.txt", { type: "text/plain" })],
  folder: "projects/demo", // optional, defaults to the root folder
  visibility: "private", // optional, defaults to the instance setting
});

// data => { files: File[] } including the hosting URLs

Files keep the name you upload them with, so you control the public URL. Names are unique per folder — the same name in two folders is fine, but uploading over an existing name returns a 409 error.

Uploads stream to disk and are moved into the target folder only once the whole request has been received. A file over MAX_UPLOAD_SIZE returns 413, and a full volume returns 507.

Get all files

const { data, error } = await vaze.files.getAll({
  limit: 20,
  orderBy: "size",
  orderDirection: "DESC",
});

// data => { files: File[] }

Get a file by ID

const { data, error } = await vaze.files.getById("file-id");

// data => { file: File }

Returns an error with status 404 if no file matches.

Get a file by key

const { data, error } = await vaze.files.getByKey("projects/demo/photo.png");

// data => { file: File }

Search files by name

const { data, error } = await vaze.files.getByName(
  "hello.txt",
  { limit: 10 }, // optional ListOptions
);

// data => { files: File[] } — empty array when nothing matches

Download a file

Downloads the raw file content as a Blob:

const { data, error } = await vaze.files.download("file-id");

if (data) {
  const { blob, filename, contentType } = data;
  await fs.writeFile(filename ?? "download", Buffer.from(await blob.arrayBuffer()));
}

The underlying endpoint supports byte ranges and ETag revalidation, so a plain fetch against it can resume an interrupted transfer. download itself always retrieves the whole file.

Rename a file

const { error } = await vaze.files.rename({
  id: "file-id",
  name: "new-name.txt",
});

The name must be a single path segment. Renaming to a name already taken in the same folder returns a 409 error.

Change visibility

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

Making a file private stops /api/hosting from serving it to anonymous callers. The file's bytes and key are untouched.

To flip a whole tree at once, use folders.setVisibility.

Sign a URL

Mints a time-limited link that reads a file without an API key — how you hand a private object to a browser or a third party:

const { data, error } = await vaze.files.sign({
  key: "projects/demo/report.pdf", // or: id: "file-id"
  expiresIn: 900, // seconds, optional
});

// data => { url: string, expiresAt: string }

url is absolute and ready to use. expiresIn defaults to the instance's DEFAULT_PRESIGN_TTL_SECONDS and is capped at MAX_PRESIGN_TTL_SECONDS.

Signed links cannot be revoked individually — they are stateless signatures, not stored grants. Prefer short lifetimes. Rotating AUTH_SECRET invalidates every outstanding link at once.

Delete a file

const { error } = await vaze.files.delete("file-id");

Removes the file from both disk and the database.

Delete several files

const { data, error } = await vaze.files.deleteMany(["file-id", "other-id"]);

console.log(data.deleted); // ids that were removed
console.log(data.failed); // [{ id, message }] for the ones that were not

One request per batch, and a single bad id does not stop the others. error is only set when the whole request fails — for example when none of the ids exist.

On this page