> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob SDK: install and create the client

> Install @squarecloud/blob and create a SquareCloudBlob client with an API key or an upload token. The only option is maxRetries.

<Info>
  This page documents **`@squarecloud/blob` v4**. Upgrading from v3? Read the [v3 → v4 migration guide](/en/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` is the official JavaScript SDK for [Square Cloud Blob Storage](/en/services/blob). It covers every [Blob API](/en/blob-reference/authentication) endpoint plus the [S3 gateway](/en/blob-reference/s3-compatibility).

## Requirements

* **Node.js 20** or newer, or any modern browser. The SDK only uses `fetch`, `FormData` and `Blob`.
* Ships as **ESM and CommonJS**, with **zero runtime dependencies**.
* `@aws-sdk/client-s3` is an **optional peer dependency**, only needed if you call [`s3()`](/en/sdks/blob/s3).

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @squarecloud/blob
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @squarecloud/blob
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @squarecloud/blob
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @squarecloud/blob
    ```
  </Tab>
</Tabs>

## Creating the client

The examples read the key from the `SQUARECLOUD_API_KEY` environment variable. Set it in the terminal where you run them:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"system"}
    export SQUARECLOUD_API_KEY="your-api-key"
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={"system"}
    $env:SQUARECLOUD_API_KEY = "your-api-key"
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

  <Tab title="CommonJS">
    ```javascript theme={"system"}
    const { SquareCloudBlob } = require("@squarecloud/blob");

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>
</Tabs>

Check the client with a first call. `stats()` reads your usage:

```typescript theme={"system"}
const { usage } = await blob.stats();

console.log(`${usage.objects} objects, ${usage.storage} bytes`);
```

It prints the number of objects and the bytes they use, for example:

```text theme={"system"}
12 objects, 5242880 bytes
```

### Constructor

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `credential` | `string` | required | An **API key**, or an **upload token** (`squp_...`) that can only call `put()`. |
| `options.maxRetries` | `number` | `2` | How many times a safe-to-repeat request (a `GET` or a multipart part) is retried after a network error or a `5xx`. `0` disables retries. See [Retry policy](/en/sdks/blob/errors#retry-policy). |

## Credentials

The credential is sent **as-is** in the `Authorization` header, with no `Bearer` prefix.

| Credential | Where it comes from | What it can do |
| - | - | - |
| API key | [Square Cloud dashboard](https://squarecloud.app/en/account/security) | Every method, subject to its `blob:read` / `blob:write` [scopes](/en/blob-reference/authentication#scopes). |
| Upload token (`squp_...`) | [`blob.uploadTokens.create()`](/en/sdks/blob/uploads#uploading-from-the-browser), on your server | Only `put()`. Any other method fails with `403 UPLOAD_TOKEN_NOT_ALLOWED`. |

<Warning>
  Never ship an API key to a browser. Mint an upload token on your server and hand only the token to the client.
</Warning>

## What you cannot configure

`maxRetries` is the **only** option. The client does not accept:

* **A base URL.** It is fixed at `https://blob.squarecloud.app/v1/`.
* **A custom `fetch`.** Requests use the global `fetch`.
* **A timeout or an `AbortSignal`.** A call lasts as long as `fetch` waits, and there is no way to cancel it.
* **Custom headers.**

## Methods

Every method returns plain data (no classes), except `s3()`, which returns an `S3Client`. Options and results use the API's own field names, mostly snake\_case (`security_hash`, `expires_at`), so the [Blob API reference](/en/blob-reference/authentication) applies as-is.

| Group | Methods | Page |
| - | - | - |
| `blob` | `put(file, options)` | [Uploads](/en/sdks/blob/uploads) |
| `blob.uploadTokens` | `create(options)` | [Uploads](/en/sdks/blob/uploads#uploading-from-the-browser) |
| `blob` | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Objects](/en/sdks/blob/objects) |
| `blob.shares` | `create(object, options)`, `list()`, `revoke(id)` | [Sharing](/en/sdks/blob/sharing) |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()` | [Rules and stats](/en/sdks/blob/rules_and_stats) |
| `blob` | `s3Credentials()`, `s3()` | [S3](/en/sdks/blob/s3) |

The package also exports `SquareCloudBlobError`, the `BlobErrorCode` type and every option and result type (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). See [Errors](/en/sdks/blob/errors).

## Object ids

Every object is identified by an **opaque id**, such as `pub/...` for a public object or `prv/...` for a private one.

* **Store the id exactly as returned.** Never build one by hand and never parse it.
* **Changing `private` or `expire` changes the id.** Always replace your stored id with the one [`update()`](/en/sdks/blob/objects#updating-objects) returns.
* **Use the `url` from the response** instead of building URLs. Private objects have `url: null`: get a link with [`downloadUrl()`](/en/sdks/blob/objects#download-links) or a [share](/en/sdks/blob/sharing).

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```

## Next steps

<CardGroup cols={3}>
  <Card title="Uploads" icon="upload" href="/en/sdks/blob/uploads">
    Upload files and mint upload tokens.
  </Card>

  <Card title="Blob API quickstart" icon="code" href="/en/blob-reference/quickstart">
    Base URL and a first upload with curl.
  </Card>

  <Card title="Blob Storage plans" icon="box-archive" href="/en/services/blob">
    What each plan includes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.