Download and list

Read a file

const documents = pawabase.storage.from("documents");

const blob = await documents.download("7/contract.pdf");             // Blob
const text = await documents.downloadText("7/notes.txt");
const notes = await documents.downloadJson<Notes>("7/notes.json");
const stream = await documents.downloadStream("7/big.zip");           // ReadableStream, for large files
const res = await documents.downloadResponse("7/contract.pdf");
res.headers.get("etag"); res.headers.get("content-type"); res.headers.get("content-length");

documents = pb.storage.from_("documents")

data = documents.download("7/contract.pdf")        # bytes
text = documents.download_text("7/notes.txt")
notes = documents.download_json("7/notes.json")
response = documents.download_response("7/contract.pdf")      # httpx.Response
response.headers["etag"]

A file that doesn’t exist, or that the Who may read rule hides, raises NotFoundError. They look the same on purpose, so a refusal never reveals which keys exist. To offer a download in a browser:

const href = URL.createObjectURL(await documents.download("7/contract.pdf"));
const a = Object.assign(document.createElement("a"), { href, download: "contract.pdf" });
a.click();
URL.revokeObjectURL(href);

List files

Needs Who may list objects (or read, if unset).

const page = await documents.list({ prefix: "7/", limit: 50 });
page.files;       // [{ key, size, content_type, modified }]
page.prefixes;    // the "folders" below the prefix: ["7/2025/", "7/2026/"]
page.cursor;      // pass it back for the next page; empty on the last

for await (const file of documents.listAll({ prefix: "7/" })) console.log(file.key, file.size);

page = documents.list(prefix="7/", limit=50)
page["files"], page["prefixes"], page["cursor"]

for file in documents.list_all(prefix="7/"):
    print(file["key"], file["size"])

listAll follows the cursor for you (on the async Python client use async for). Listing is by prefix, so design keys with that in mind (<user id>/<year>/file).

Build a folder view

async function openFolder(prefix: string) {
  const { files, prefixes } = await documents.list({ prefix, limit: 100 });
  return {
    folders: prefixes.map((p) => ({ name: p.slice(prefix.length).replace(/\/$/, ""), prefix: p })),
    files: files.map((f) => ({ name: f.key.slice(prefix.length), size: f.size, type: f.content_type })),
  };
}

Delete

Needs Who may delete objects.

await documents.remove("7/contract.pdf");

for await (const file of documents.listAll({ prefix: "7/" })) await documents.remove(file.key);   // a whole "folder"

documents.remove("7/contract.pdf")
for file in documents.list_all(prefix="7/"):
    documents.remove(file["key"])

There is no recycle bin. To allow undo, mark a record deleted instead and clean files up later (Files and records).

Moving and renaming

The client has no rename: upload under the new key, update your record, remove the old key. In Studio, Rename or move does it in one step (Browse files).

Caching

Files carry an ETag that changes when a file is replaced, so a browser can ask “has it changed?” cheaply. The bucket’s Browser cache (seconds) controls how long a browser reuses a file before asking. If you replace a file but keep its key, add a version to the address (?v=2) so every browser refetches at once, or better, use a new key.

Errors

Error	Cause
`AuthenticationError`	The rule needs a signed-in user
`PermissionError` / `ForbiddenError`	The rule refused (list, delete)
`NotFoundError`	No such file, or hidden by the read rule
`NetworkError`, `TimeoutError`	Connection problems. Pass `signal` / `timeoutMs` for control

Links and URLs

Public, signed and share links.

Patterns

Galleries, downloads, exports.

Getting started

Set up in Studio

Use it from your app

Protect and build

Download and list

Read a file

List files

Build a folder view

Delete

Moving and renaming

Caching

Errors

Links and URLs

Patterns

​Read a file

​List files

​Build a folder view

​Delete

​Moving and renaming

​Caching

​Errors

Links and URLs

Patterns

Read a file

List files

Build a folder view

Delete

Moving and renaming

Caching

Errors