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

# Client

> The SquareCloudAPI class is the entry point to the SDK. It is instantiated with an API key and exposes every module — applications, databases, workspaces, user and platform service — through a single client.

<Info>
  This page documents **`@squarecloud/api` v4**. If you are upgrading from v3, read the [v3 → v4 migration guide](/en/sdks/js/migrating_to_v4) first.
</Info>

## Requirements

* **Node.js 20.0.0** or newer
* A valid API key — request one at the [Square Cloud Dashboard](https://squarecloud.app/en/dashboard)

## Installation

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

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

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @squarecloud/api
    ```
  </Tab>
</Tabs>

## Instantiating the client

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);
    ```
  </Tab>

  <Tab title="JavaScript (ESM)">
    ```javascript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>

  <Tab title="JavaScript (CommonJS)">
    ```javascript theme={null}
    const { SquareCloudAPI } = require("@squarecloud/api");

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>
</Tabs>

### Constructor

| Parameter | Type     | Required | Description                                                               |
| --------- | -------- | -------- | ------------------------------------------------------------------------- |
| `apiKey`  | `string` | Yes      | Your Square Cloud API key. The client will throw if this is not a string. |

## Modules

The client exposes the entire v2 platform through dedicated modules. Each module is a property of the `SquareCloudAPI` instance.

| Property           | Module                                             | Documentation                                             |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------- |
| `api.user`         | Authenticated user, plan, owned apps and databases | This page                                                 |
| `api.applications` | List, fetch, upload and inspect applications       | [Managing applications](/en/sdks/js/managing_application) |
| `api.databases`    | Create, fetch and manage databases                 | [Databases](/en/sdks/js/databases)                        |
| `api.workspaces`   | Create, list and manage workspaces                 | [Workspaces](/en/sdks/js/workspaces)                      |
| `api.service`      | Aggregate platform status                          | This page                                                 |
| `api.cache`        | In-memory cache populated by SDK events            | This page                                                 |

## Getting the authenticated user

`api.user.get()` returns a [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts) instance containing the account details, current plan, owned applications and owned databases.

```typescript theme={null}
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
```

`user.applications` and `user.databases` are [`Collection`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts) instances (a `Map` subclass). Iterate them like any `Map`:

```typescript theme={null}
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}
```

## Fetching a single application

Use `api.applications.fetch(id)` to retrieve a fully populated `Application` (or `WebsiteApplication`, when the app has a website domain).

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // narrowed to WebsiteApplication — `.network` is available
    await app.network.purgeCache();
}
```

The legacy `api.applications.get(id)` overload still exists, but it returns the lighter `BaseApplication` and is only kept for backwards compatibility. **Prefer `.fetch()` for v4.**

## Listing snapshot history (account-wide)

```typescript theme={null}
const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
```

See [Snapshots](/en/sdks/js/snapshots) for details on snapshot payloads.

## Platform status

`api.service.status()` exposes the aggregated platform health (the same data shown on the public status page).

```typescript theme={null}
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // human-readable summary
```

<Note>
  Unlike most v2 endpoints, this route does **not** wrap its payload in the standard `{ status, response }` envelope.
</Note>

## Client cache

The client maintains an in-memory cache that the SDK keeps in sync as you make calls:

```typescript theme={null}
api.cache.user;   // last fetched User
// each application instance also exposes app.cache.status / .logs / .snapshots
```

The SDK emits typed events you can subscribe to:

```typescript theme={null}
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});
```

## Error handling

Failed requests throw a `SquareCloudAPIError`. The error exposes a stable `code` property you can switch on to discriminate failure modes.

```typescript theme={null}
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}
```