Client

This page documents @squarecloud/api v5. If you are upgrading from v4, read the v4 → v5 migration guide first. Coming from v3, see the v3 → v4 migration guide.

Requirements

Node.js 20.0.0 or newer
A valid API key — request one at the Square Cloud Dashboard

Installation

npm
yarn
pnpm

npm install @squarecloud/api

yarn add @squarecloud/api

pnpm add @squarecloud/api

Instantiating the client

TypeScript
JavaScript (ESM)
JavaScript (CommonJS)

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);

const { SquareCloudAPI } = require("@squarecloud/api");

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);

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
`api.databases`	Create, fetch and manage databases	Databases
`api.workspaces`	Create, list and manage workspaces	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 instance containing the account details, current plan, owned applications and owned databases.

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);   // e.g. "standard"
console.log(user.plan.duration); // plan duration, e.g. "monthly"
console.log(user.plan.memory);   // { limit: 2048, available: 512, used: 1536 } (MB)
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 instances (a Map subclass). Iterate them like any Map:

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

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

Listing snapshot history (account-wide)

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");

See 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).

const status = await api.service.status();

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

Unlike most v2 endpoints, this route does not wrap its payload in the standard { status, response } envelope.

Client cache

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

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:

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.

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);
    }
}

Error codes (APIErrorCode)

APIErrorCode is a const/union exported by the SDK (re-exported from @squarecloud/api-types) listing every value err.code can take. v5 renamed several codes for consistency; the old names are kept as deprecated type aliases, but the SDK now throws only the new names.

Old (deprecated alias)	New
`ID_INVALID`	`INVALID_ID`
`CODE_INVALID`	`INVALID_CODE`
`NAME_INVALID`	`INVALID_NAME`
`MEMORY_INVALID`	`INVALID_MEMORY`
`DATABASE_TYPE_INVALID`	`INVALID_DATABASE_TYPE`
`DATABASE_VERSION_INVALID`	`INVALID_DATABASE_VERSION`
`UNKNOWN_WORKSPACE`	`WORKSPACE_NOT_FOUND`
`UNKNOWN_MEMBER`	`MEMBER_NOT_FOUND`
`MAX_APPLICATIONS_REACHED`	`APPLICATIONS_LIMIT_REACHED`
`MAX_MEMBERS_REACHED`	`MEMBERS_LIMIT_REACHED`
`FAILED_WORKSPACE_CREATION`	`WORKSPACE_CREATION_FAILED`
`FAILED_DATABASE_CREATION`	`DATABASE_CREATION_FAILED`
`FAILED_CLUSTER_SELECTION`	`CLUSTER_SELECTION_FAILED`
`FEW_MEMORY`	`INSUFFICIENT_MEMORY`
`FAILED_READ`	`READ_FAILED`
`FAILED_DELETE`, `DELETE_ERROR`	`DELETE_FAILED`
`FAILED_RENAME`	`RENAME_FAILED`
`FAILED_TO_SAVE`	`SAVE_FAILED`
`FAILED_RESET`	`RESET_FAILED`
`FAILED_UPLOAD`	`UPLOAD_FAILED`
`FAILED_UPLOAD_DATA`	`STORAGE_UPLOAD_FAILED`
`COMMIT_ERROR`	`COMMIT_FAILED`
`INTERNAL_ERROR`	`INTERNAL_SERVER_ERROR`
`REGEX_VALIDATION`	`INVALID_DOMAIN`
`CAN_NOT_SET_SUBDOMAIN`	`CANNOT_SET_SUBDOMAIN`
`INVALID_APP` (metrics only)	`METRICS_NOT_SUPPORTED`
`SUBSCRIPTION_REQUIRED`	`UPGRADE_REQUIRED`

Unchanged codes: KEEP_CALM (short 429, retry in seconds), ACCESS_DENIED (401), PAYLOAD_TOO_LARGE (413), RATE_LIMIT_EXCEEDED. New in v5:

Code	Meaning
`DAILY_SNAPSHOTS_LIMIT_REACHED`	429, the plan’s daily snapshot quota was reached (distinct from `KEEP_CALM`)
`UPLOAD_ABORTED`	The client aborted an in-progress upload
`LOAD_BALANCER_LIMIT_REACHED`	403, attaching a custom domain beyond the plan’s app-per-domain limit
`FILE_TOO_LARGE`	413, on an upload over 100MB or reading a large file

import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const snapshots = await api.user.snapshots("applications");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        switch (err.code) {
            case "UPGRADE_REQUIRED":
                console.error("an active paid plan is required for account-wide snapshots");
                break;
            default:
                console.error(err.code, err.message);
        }
    }
}

Services

Runtimes

Platform

Troubleshooting

CLI

SDKs

Changelog

Requirements

Installation

Instantiating the client

Constructor

Modules

Getting the authenticated user

Fetching a single application

Listing snapshot history (account-wide)

Platform status

Client cache

Error handling

Error codes (APIErrorCode)

​Requirements

​Installation

​Instantiating the client

​Constructor

​Modules

​Getting the authenticated user

​Fetching a single application

​Listing snapshot history (account-wide)

​Platform status

​Client cache

​Error handling

​Error codes (APIErrorCode)

Requirements

Installation

Instantiating the client

Constructor

Modules

Getting the authenticated user

Fetching a single application

Listing snapshot history (account-wide)

Platform status

Client cache

Error handling

Error codes (APIErrorCode)