> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Blob Storage: what it is and how to use it (CDN)

# 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:

| Plan | Included Free Storage |
| ---- |
| Hobby-1 | **5 GB** |
| Hobby-2 | **15 GB** |
| Standard-4 | **30 GB** |
| Standard-6 | **50 GB** |
| Standard-8 | **100 GB** |
| Pro-12 | **200 GB** |
| Pro-16 | **250 GB** |
| Enterprise | **250 GB** |

---

## 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:

| Parameter | Type | Required | Description |
| ---- |
| `name` | String | Yes | File name (without extension). Pattern: `a-zA-Z0-9_` (3-32 characters). |
| `prefix` | String | No | Folder/prefix to organize the file. |
| `expire` | Number | No | Days until expiration (1 to 365). Leaving it undefined will make it permanent (until manually deleted). |
| `security_hash` | Boolean | No | `true` to require a security hash on access. |
| `auto_download` | Boolean | No | `true` to force download when opening the URL. |

3. Headers
| Key | Value |
| ---- |
| `Authorization` | `YOUR_API_KEY` |

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):**
```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):**
```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.
```
```