Upload

Set the bucket’s rules and limits up first (Create a bucket). Then upload(key, body) stores a file at a key. If the key already exists the file is replaced, so repeating an upload is safe.

Upload a file

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

const stored = await documents.upload(`${user.id}/contract.pdf`, file);
stored.size;           // bytes
stored.content_type;   // "application/pdf"
stored.key;            // the key you used

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

stored = documents.upload(f"{user_id}/contract.pdf", open("contract.pdf", "rb"))
stored["size"], stored["content_type"], stored["key"]

In a web page the file comes from an input:

input.addEventListener("change", async () => {
  const file = input.files?.[0];
  if (file) await documents.upload(`${user.id}/${crypto.randomUUID()}.pdf`, file);
});

The result describes what was stored: bucket, key, size, content_type and, when available, etag.

What you can pass

TypeScript	Python
`File` or `Blob` (content type taken from the file)	`bytes`, `bytearray`, `memoryview`
`ArrayBuffer`, typed arrays	An open binary file
`string` (stored as text)	A `pathlib.Path` (content type guessed from its name)
`ReadableStream` (not retried on failure)	`str` (stored as text)
`FormData`

If you don’t pass a content type the client uses the file’s own, then guesses from the key’s extension, then falls back to application/octet-stream. Pass one when the guess would be wrong: { contentType: "image/png" } / content_type="image/png".

What the bucket checks

Everything you set in Studio is enforced on every upload:

Bucket setting	If broken
Who may upload new objects (or replace, when the key exists)	`AuthenticationError` / `PermissionError`
Accepted types	`ValidationError` (judged from the file’s real contents)
Largest file	`PayloadTooLargeError`

Choose keys

Put the owner first: <user id>/avatar.png, so a single rule protects it (Who can do what).
Generate names (crypto.randomUUID(), uuid.uuid4()); keep the original file name in a record (Files and records).
To keep an old version, use a new key each time.

Upload straight from the browser

For large files, or to keep your server out of the data path, your server makes a one-time signed upload link and the browser sends the file to it. The link is limited to one key, one content type and one size, and expires. First turn on Signed uploads in the bucket’s settings (it is on by default). Then:

// On your server, signed in as (or acting for) the person
const { url } = await serverSide.storage.from("videos").createSignedUploadUrl(`${userId}/intro.mp4`, {
  expiresIn: 300,
  contentType: "video/mp4",
  maxBytes: 200 * 1024 * 1024,
});

// In the browser, with the url your server returned
await pawabase.storage.from("videos").uploadToSignedUrl(url, file);

bucket = pb.storage.from_("videos")
link = bucket.create_signed_upload_url(f"{user_id}/intro.mp4", expires_in=300, content_type="video/mp4", max_bytes=200 * 1024 * 1024)
bucket.upload_to_signed_url(link["url"], open("intro.mp4", "rb"), content_type="video/mp4")

The browser sends no key and no token: the link is the credential. Anything outside the link’s key, type or size is refused.

Progress, cancel and time out (TypeScript)

const controller = new AbortController();
cancel.onclick = () => controller.abort();

await documents.upload(key, file, { signal: controller.signal, timeoutMs: 120_000 });

fetch can’t report upload progress. For a percentage, make a signed upload link and send that one upload with XMLHttpRequest, listening to upload.onprogress.

Handle refusals

import { AuthenticationError, PermissionError, PayloadTooLargeError, ValidationError } from "@pawabase/client";

try {
  await documents.upload(key, file);
} catch (e) {
  if (e instanceof AuthenticationError) showSignIn();
  else if (e instanceof PermissionError) show("You can't upload here.");
  else if (e instanceof PayloadTooLargeError) show("That file is too large.");
  else if (e instanceof ValidationError) show("That file type isn't allowed.");
  else throw e;
}

from pawabase import AuthenticationError, ForbiddenError, ValidationError

try:
    documents.upload(key, data)
except AuthenticationError: ...
except ForbiddenError: ...
except ValidationError: ...

Check size and type in the browser first for a quick message, but treat the bucket’s limits as the real check.

Uploading many files

Upload them one after another or a few at a time, not hundreds at once:

for (const file of files) {
  await documents.upload(`${user.id}/${crypto.randomUUID()}-${file.name}`, file);
  setProgress((n) => n + 1);
}

Download and list

Read what you stored.

Troubleshooting

When an upload fails.

Getting started

Set up in Studio

Use it from your app

Protect and build

Upload a file

What you can pass

What the bucket checks

Choose keys

Upload straight from the browser

Progress, cancel and time out (TypeScript)

Handle refusals

Uploading many files

Download and list

Troubleshooting

​Upload a file

​What you can pass

​What the bucket checks

​Choose keys

​Upload straight from the browser

​Progress, cancel and time out (TypeScript)

​Handle refusals

​Uploading many files

Download and list

Troubleshooting

Upload a file

What you can pass

What the bucket checks

Choose keys

Upload straight from the browser

Progress, cancel and time out (TypeScript)

Handle refusals

Uploading many files