url

Return a URL to fetch a key - a signed GetObject where the adapter can sign, or a direct CDN/public URL where one is configured.

files.url(key, options?)

Returns a URL the caller can use to fetch key. Every adapter returns the most direct URL it can produce. Signing adapters (S3 and the S3-compatible catalog — R2 over HTTP plus every regional / budget / decentralised wrapper — alongside Google Cloud Storage, Firebase Storage, Azure (shared-key or user-delegation SAS), Supabase, UploadThing in private mode, Vercel Blob in access: "private" mode, and the R2 binding when HTTP credentials are also configured) sign a read URL - defaulting to a 1-hour expiry, override per-call via { expiresIn } or per-adapter via defaultUrlExpiresIn. If the adapter is constructed with a publicBaseUrl (CDN, custom domain, r2.dev, Bunny Pull Zone) or UploadThing’s public-read ACL, a plain url(key) returns that permanent link without signing (capabilities.publicUrl is true).

expiresIn always means “give me a link that expires”. On an adapter that can sign, passing it returns a signed URL even when a publicBaseUrl is configured. On one that can’t (Vercel Blob in public mode, UploadThing public-read, Convex, Appwrite, the filesystem), it throws an Unsupported FilesError rather than handing back a permanent link that ignores it. Leave it out to get the adapter’s default. expiresIn is a whole number of seconds: 0, a negative or fractional value, or NaN throws an Invalid FilesError before anything is signed, instead of returning a URL that never works.

Adapters with no URL primitive throw unless you configure a public URL for them: an R2 Workers binding without either publicBaseUrl or HTTP credentials; Bunny Storage, FTP, SFTP, and WebDAV without publicBaseUrl; Google Drive, OneDrive, and SharePoint without publicByDefault: true; and Appwrite without public: true. Netlify Blobs has no URL primitive at all, so url() always throws there. Provider gaps covers each one, and files.capabilities.signedUrl tells you up front whether the adapter can sign.

// One call, every adapter. S3 and the S3-compatible catalog (R2 over HTTP
// plus every regional / budget / decentralised wrapper) sign a GetObject (1h
// default, override with { expiresIn }); Google Cloud Storage and Azure sign
// a read URL natively with the same default; Supabase signs via createSignedUrl
// (or returns the public URL when constructed with public:true); Vercel Blob
// (public), UploadThing (public-read), and Bunny Storage with publicBaseUrl
// return their CDN URLs. If you configured `publicBaseUrl` on the adapter, a
// plain url() returns that permanent link.
const url = await files.url("avatars/abc.png");
// An expiring link: signed even when `publicBaseUrl` is set; an `Unsupported`
// error on an adapter that only has permanent links.
const short = await files.url("avatars/abc.png", { expiresIn: 60 });

// Force download (defeat stored XSS from user-uploaded HTML/SVG).
// Forces signing even if `publicBaseUrl` is configured - a permanent
// CDN URL has no signature to bind the override into, and silently
// dropping a security ask would be a regression.
const safe = await files.url("avatars/abc.png", {
  responseContentDisposition: "attachment",
});

Options