Blob Storage: What It Is and How to Use It

In modern application development, managing files (images, videos, documents) directly on the application server can consume precious resources and complicate scaling. Square Cloud's Blob Storage solves this problem by offering a fully serverless binary large object storage (Binary Large Objects) with low latency and an included CDN.

1. What It Is and Why Use It

Blob Storage is an asset storage service designed for high availability. Unlike a traditional file system, it is optimized for fast reading through a Content Delivery Network (CDN).

• Serverless: You don't need to manage disks or volumes.
• Low Latency: Thanks to the CDN, content is served from the point of presence closest to the user.
• Efficiency: Reduces the I/O load on your main application or bot server.

2. Features and Customization

When uploading a file to Blob, you have full control over the asset's behavior:

• Expiration: Set a lifetime for the file (ideal for temporary files).
• Name and Prefix: Organize your files into logical "folders" using prefixes.
• Security Hash: Generates a random suffix to prevent the link from being "guessed" by third parties.
• Auto Download: Option to force the browser to download the file instead of just previewing it.

3. Limits and Supported Formats

The service allows file uploads between 1KB and 100MB. Below are the accepted file types categorized by extension:

You have a free usage quota depending on your plan. Check the table below:

4. Access URL Structure

Once the file is uploaded, it becomes publicly available through a standardized URL. The structure follows this format:

https://public-blob.squarecloud.dev/{square_account_id}/{prefix}/{filename}{_security_hash}{extension}

Practical example:
If your ID is 123, the prefix is banners, the file is promocao, and it has a hash:
https://public-blob.squarecloud.dev/123/banners/promocao_xyz789.jpg
If you choose not to set a prefix and hash, with no expiration time:
https://public-blob.squarecloud.dev/123/promocao.jpg

5. How to Upload Files

There are two main ways to interact with Blob Storage:

Via Dashboard

Ideal for manual management. Just go to the Blob tab in your dashboard, click on Upload new object, and fill out the form.

Via Public API

For automation (such as uploads made by your project's users), use the POST endpoint.

1. General Information

• Endpoint: https://blob.squarecloud.app/v1/objects
• Method: POST
• Authentication: API Key in Header.
• Rate Limit: 1/s

2. URL Parameters (Query Params)

You must include the file configurations directly in the request URL:

3. Headers

4. Request Body

The body must use the FormData format containing only the file:

• Key: file
• Value: [Binary File]
• mimetype: file mimetype (e.g., image/jpeg)

• API Reference:
• Upload
• Listing
• Deletion
• Statistics

Tip: If you upload a file without a hash and without an expiration time, you can update it by uploading another file of the same type and with the same parameters (prefix/name). Keep in mind that there is a caching period since it uses a CDN.

6. Best Practices

• Organization: Always use prefixes (e.g., profiles/, logs/) to prevent your Blob root from getting cluttered.
• Cache and CDN: Remember that assets on a CDN are cached. If you need to update a file while keeping the same name, using security hashes is highly recommended to prevent the user from seeing the old version.
• Security: Although the link contains your account ID, it is public. Do not store unencrypted confidential information.

```

Updated on: 05/21/2026