Server API

import { UFApi } from "@uploadfile/core/server";

// Reads UPLOADFILE_TOKEN, which selects the service address.
export const ufapi = new UFApi();

Use UFApi only on the server. You can also pass token to the constructor. The token selects the service address. uploadFiles and uploadFilesFromUrl return { data, error } for each file. The other methods throw UploadfileError when a request fails.

import { UFFile } from "@uploadfile/core/server";
import { ufapi } from "./ufapi";

const file = new UFFile(["Hello from the server"], "hello.txt", { type: "text/plain" });
const { data, error } = await ufapi.uploadFiles(file);
if (error) throw new Error(error.message);
console.log(data.key, data.ufsUrl);

uploadFiles also accepts an array. UFFile takes an optional customId, an application-unique ID you can use in place of the key.

import { ufapi } from "./ufapi";

const { files, hasMore } = await ufapi.listFiles({ limit: 25 });
const [first] = files;
if (first) {
  await ufapi.renameFiles({ fileKey: first.key, newName: "report.pdf" });
  const { ufsUrl } = await ufapi.getSignedURL(first.key, { expiresIn: "1h" });
  console.log(ufsUrl, hasMore);
  await ufapi.deleteFiles(first.key);
}

updateACL makes files public or private, and getUsageInfo returns the application's stored bytes and file count. Signed URLs last at most 7 days.

Each API key belongs to one application and has a set of scopes. A key can't manage organization members, sign-in, or billing. Create a separate key for each integration so you can revoke one without touching the others.

Handle authorization failures, quota limits, conflicts, and transient errors differently. Retry only transient errors, and reuse the same idempotency key so a retried operation doesn't run twice.