Skip to main content
Blob Storage has three ways to hand a file to someone. Pick by how long the link must live and whether you need to take it back.

​
Public URLs

A public file has a permanent URL on the CDN:
Use it for assets you embed: images on a site, attachments in a bot, files other services fetch. Legacy files, stored before the September 2026 update, keep their URL on https://public-blob.squarecloud.dev/<user_id>/<path> for 30 days, until October 25, 2026. Move them with Object Copy (move: true) to get a URL on blob.squarecloud.dev.
With security_hash=true (the default for private files and upload tokens without a name), the path gets a random suffix, so the URL can’t be guessed from the name.
Object Download signs a link to one file, valid for 60 seconds up to 24 hours (default 1 hour). Use it to deliver a private file right now: a download button, an email attachment, a file your backend passes to another service.
  • The link needs no credential and cannot be revoked: it only stops working when it expires or when the file is deleted, moved or changes visibility. Keep the lifetime short.
  • It supports Range (resumable downloads and video seeking) and conditional requests (If-None-Match, If-Modified-Since).
  • You can force a download and pick the file name the browser saves (disposition and filename).
  • For a public file without those overrides, Object Download returns the public URL itself.
  • A link accepts 60 requests per minute per IP, on top of an overall limit for all the links of your account. Past that it answers 429 in plain text. To hand one file to many people, make it public: public files are served by the CDN, without this limit. An expired or invalid link answers 404.
Create Share makes a link with a page of its own, for people rather than programs: sending a file to a client, a report to a team, a build to a tester.
  • It lasts from 60 seconds to 30 days (default 24 hours).
  • It can be revoked at any time with Delete Share, and is listed by List Shares.
  • max_downloads caps how many times the file can be downloaded. The count is exact, even under concurrent downloads. Once it runs out the link answers 410.
  • On Pro and Enterprise, a password makes the page ask for it before the download. Wrong attempts are limited per IP and per link. A password link created before a downgrade keeps its password.
  • The page follows the visitor’s browser language (English, Portuguese, Spanish, French, German, Italian, Japanese and Chinese).
  • The account can have up to 1000 active share links.
  • Downloading a private file goes through a temporary link, with the same limits: 60 requests per minute per IP, plus the overall limit of your account.
A share link is tied to the file as it was when the link was created. Deleting the file, moving or renaming it, or changing its visibility makes the link answer 404 right away, before any password page and without spending a download. The next visit removes it from List Shares.
A share link to a public file ends in a redirect to the file’s permanent public URL. Whoever opens it gets that URL and can download the file again without going through the link, so the password, the download cap and the expiry only truly protect private files. When the protection matters, share a private file.

​
Making a file private or public

Change visibility with Object Update (private: true or false), or when copying with Object Copy.
  • The object id changes: pub/... becomes prv/... and the other way around. Store the new id from the response.
  • Making a file private removes the public copy before the request answers. Its public URL stops working, and CDN caches drop it in about 60 seconds. If the public copy can’t be removed, the object answers VISIBILITY_CHANGE_FAILED and stays public, so you can retry.
  • Making a file public needs a paid plan. Making it private is always allowed, even without a plan.
  • Share links and temporary links to the file stop working, since they point to the old id. Create new ones for the new id.
A file that was public may have been downloaded or cached by others before you made it private. Upload sensitive files as private from the start (private=true).