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 512B and 1GiB. Practically any file type is accepted, including formats with no registered MIME type: .bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy and so on. The stored extension comes from the filename you upload, and compound compression suffixes are preserved (reads.fastq.gz stays .fastq.gz).
The only exception is a denylist of executables and installers (.exe, .msi, .bat, .apk and similar), refused with BLOCKED_FILE_TYPE.

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.

Option 1: Direct Upload (512B to 100MB)

Recommended for the standard workflow of small and medium-sized files.

1. General Information

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

2. Query Parameters

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 (Ex.: image/jpeg)

Option 2: Chunked Upload (Over 100MB up to 1GiB)

For heavy files, the upload is split into small blocks (chunks). Since there is no session state saved on the server, the entire process relies on a single "token" generated at the beginning. The workflow goes through up to four steps:

1. Initialize Upload

Reserves the object key and opens the transfer.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Method: POST
• Query Parameters: Uses the same parameters as Option 1 (name, prefix, expire, etc.), with the addition of filename (the original name and extension, e.g., reads.fastq.gz). Since there is no FormData, the extension is derived from filename.
• Return: The API will return a token in the response.upload property. Persist this token, as it will be used in all subsequent steps.

2. Upload Parts

Sends the file data in pieces. Each part (except the last one) must be between 5MB and 32MB. You can upload up to 6 parts in parallel.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Method: PUT
• Rate Limit: 60 parts every 10 seconds.
• Query Parameters: ?upload=YOUR_TOKEN_HERE&part=1 (the part number ranges from 1 to 205).
• Headers:
• Authorization: YOUR_API_KEY
• Content-Type: application/octet-stream
• Body: Raw bytes of the chunk only. Do not use multipart/form-data.

3. Complete Upload

After uploading all parts, you must "seal" the file so the platform can assemble the pieces and release your public URL.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Method: PATCH
• Rate Limit: 5 requests every 10 seconds.
• Headers:
• Authorization: YOUR_API_KEY
• Content-Type: application/json
• Body (JSON):

{
  "upload": "YOUR_TOKEN_HERE"
}

4. Cancel Upload (Error Handling)

If the upload fails or is abandoned by the user, cancel it to clean up the saved chunks and free up space within your account limit (maximum of 8 open uploads).

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Method: DELETE
• Rate Limit: 10 requests every 10 seconds.
• Headers:
• Authorization: YOUR_API_KEY
• Content-Type: application/json
• Body (JSON):

{
  "upload": "YOUR_TOKEN_HERE"
}

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: 08/04/2026