Requirements
Installation
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); // "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 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();
}
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)
const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots = await api.user.snapshots("databases");
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
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);
}
}
