Server SDK | Buildspace Docs

Server calls use your secret key, so path rules don't gate them (file-size and type limits still apply). Pass userId when acting for an end user: it's recorded as the uploader so owner_only rules work for them.

import Buildspace from "@buildspacestudio/sdk";

const bs = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);

// 1. Get a URL signed for this exact size and content type
const { upload_url, key } = await bs.storage.getUploadUrl({
  key: "exports/report.pdf",
  contentType: "application/pdf",
  size: bytes.byteLength,
  userId: session.user.id, // optional
});

// 2. PUT the bytes (Content-Type must match)
await fetch(upload_url, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: bytes,
});

// 3. Confirm it: records the real size and makes it visible in listings and usage
await bs.storage.completeUpload(key, { userId: session.user.id });

const signed = await bs.storage.getSignedUrl("exports/report.pdf", { expiresIn: 60 });
const { objects } = await bs.storage.list("exports/");
await bs.storage.delete("exports/old.pdf");
const usage = await bs.storage.getUsage();

Uploads you don't confirm are confirmed (or discarded, if nothing landed) by a background job after the URL expires, so skipping step 3 only delays when they show up.

For browser uploads, see createUploadRoute.