JavaScript SDK: quickstart and client

This page documents @squarecloud/api v6, a rewrite of the SDK. Coming from v5? Read the v5 → v6 migration guide.

Requirements

Node.js 22 or newer, Deno, Bun or an edge runtime. The SDK only needs fetch, FormData, Blob and web streams.
An API key (see API key and scopes).

The package ships ESM and CommonJS builds, has no runtime dependencies and includes its own TypeScript types: you no longer need @squarecloud/api-types.

Installation

npm
pnpm
yarn
bun
deno

npm install @squarecloud/api

pnpm add @squarecloud/api

yarn add @squarecloud/api

bun add @squarecloud/api

deno add npm:@squarecloud/api

API key and scopes

Create a key at squarecloud.app/account/security. The SDK sends it as-is in the Authorization header (no Bearer prefix). A key can be limited to scopes (apps:read, apps:deploy, apps:control, ai:chat, …) and to specific apps or databases:

A call outside those limits throws a SquareCloudAPIError with 403 MISSING_SCOPE or RESOURCE_NOT_ALLOWED.
List methods (account.me(), apps.statusAll(), …) only return the resources the key can see.
An unknown, revoked or expired key is 401 ACCESS_DENIED.

Keep the key on the server. The SDK runs in a browser too, but that would expose the key to every visitor.

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

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Creating the client

TypeScript / ESM
CommonJS

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

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

const { user, applications } = await api.account.me();
console.log(`Hi ${user.name}, you have ${applications.length} apps`);

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

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

The first example prints your account name and the number of apps the key can see:

Hi Jane, you have 3 apps

An empty or whitespace-only key throws a TypeError in the constructor, before any request.

Options

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

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!, {
    baseUrl: BASE_URL, // "https://api.squarecloud.app/v2" (default)
    timeoutMs: 30_000,
    maxRetries: 2,
    userAgent: "my-bot/1.0",
    fetch, // any fetch-compatible function (proxy, tracing, tests)
});

Option	Default	Description
`baseUrl`	`https://api.squarecloud.app/v2`	API base URL. A trailing `/` is stripped. Also exported as `BASE_URL`.
`timeoutMs`	`30000`	Timeout per attempt, covering the whole response. See Timeouts.
`maxRetries`	`2`	Retries of safe failures only (up to 3 attempts). A negative value counts as `0`. See Retries.
`userAgent`	`squarecloud-sdk-js/<version>`	Replaces the whole `User-Agent` header.
`fetch`	the global `fetch`	A custom `fetch` for proxies, tracing or tests.

The API key is stored as a regular property of the client object. Don’t console.log or serialize the client.

Modules

Property	Covers	Page
`api.account`	`me()`, `snapshots({ scope })`	Account and Snapshots
`api.service`	`status()`	Platform status
`api.apps`	Get, delete, status, lifecycle, logs, metrics, domains, load balancers	Managing applications
`api.apps.create` / `commit`	Uploads	Commit and upload
`api.apps.files`	File manager	Managing files
`api.apps.envs`	Environment variables	Environment variables
`api.apps.deploys`	Webhook and GitHub App deploys	Deploys
`api.apps.network`	Analytics, logs, DNS, custom domain, cache	Network
`api.apps.realtime`	Live logs and status	Realtime
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Backups	Snapshots
`api.databases`	Managed databases	Databases
`api.workspaces`	Workspaces, members and shared apps	Workspaces
`api.ai`	`chat()`	AI

The only runtime exports are SquareCloudAPI, SquareCloudAPIError and BASE_URL. Every other export (App, RuntimeStats, ErrorCode, …) is a type:

import type { App, Snapshot } from "@squarecloud/api";

Conventions

Ids first, plain data back

Every method takes the resource id as its first argument and returns plain data (no classes, no cache). Field names are the API’s own (created_at, version_id, lastModified, joinedAt, netIO, …), so the API reference applies as-is.

Mutations resolve to void, unless the API returns data (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials and the create methods).
A string result is never undefined: it is "" when the API sends none.
Lists come complete in one call: there is no pagination.

Methods are arrow functions, so you can destructure them:

const { restart, logs } = api.apps;

await restart(appId);
console.log(await logs(appId));

Workspace apps

Every appId also accepts the composite form <appId>-<workspaceId> to act on an app shared with you through a workspace. workspaces.get() and workspaces.list() return raw ids; you build the composite id yourself:

await api.apps.restart(`${appId}-${workspaceId}`);

Ids are encoded

Ids in the URL path are percent-encoded. An id that is empty, . or .. would reach a different route, so it fails locally with INVALID_ID (status 0) before anything is sent. Workspace routes send their ids in the body instead: there, INVALID_ID (400) comes from the server.

Dates

start and end arguments (see Network) take an ISO 8601 string or a Date. Dates in responses stay as the API sends them (ISO strings, or Unix milliseconds where the API uses them).

Timeouts

Call	Timeout
Every other call	`timeoutMs` (30 s) per attempt
Calls the server holds open: `start`/`stop`/`restart` of apps, `start`/`stop` of databases, `databases.create`, snapshot `create`/`restore`, `ai.chat`	At least 120 s (a larger `timeoutMs` wins)
Uploads (`apps.create`, `apps.commit`), `files.write` above 1 MiB, `downloadSnapshot`	None: pass a `signal` to cancel
`apps.realtime`	Only until the response headers arrive

A timeoutMs of 0 or less, Infinity or >= 2^31 disables every timeout, the 120 s floors included. Only five methods take an AbortSignal: apps.create, apps.commit, files.write, apps.realtime and downloadSnapshot.

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await api.apps.commit(appId, "./build.zip", { signal: controller.signal });

An aborted call rejects with the signal’s reason, not with a SquareCloudAPIError. An aborted realtime() loop just ends.

Account

api.account.me() returns the authenticated user plus the apps and databases the key can see.

const { user, applications, databases } = await api.account.me();

console.log(user.id, user.name, user.email, user.plan.name);
console.log(user.plan.memory); // { limit, available, used } in MB
console.log(user.plan.duration ? new Date(user.plan.duration) : "never expires");

Field	Description
`user`	`id`, `name`, `email`, `locale`, `created_at` and `plan` (`name`, `memory`, `duration`: the Unix ms at which the plan expires, `null` if it never does)
`applications`	Array of `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }`
`databases`	Array of `{ id, name, ram, type, cluster, created_at }`

api.account.snapshots({ scope }) lists every snapshot of the account: see Snapshots.

Platform status

api.service.status() returns the public platform status. The route needs no valid key, but the client still requires a non-empty one.

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

console.log(status.status); // "online" | "degraded" | "unknown"
console.log(status.message);

for (const [name, service] of Object.entries(status.services ?? {})) {
    console.log(name, service.status); // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown means the check itself could not run: it is not evidence of an outage.

Next steps

Managing applications

Status, lifecycle, logs and metrics.

Errors

Error class, retries and rate limits.

API introduction

Base URL, authentication and a first request.

CLI quickstart

Deploy and manage apps from the terminal.

CLI

VS Code

SDKs

JavaScript SDK: quickstart and client

Requirements

Installation

API key and scopes

Creating the client

Options

Modules

Conventions

Ids first, plain data back

Workspace apps

Ids are encoded

Dates

Timeouts

Account

Platform status

Next steps

Managing applications

Errors

API introduction

CLI quickstart

​Requirements

​Installation

​API key and scopes

​Creating the client

​Options

​Modules

​Conventions

​Ids first, plain data back

​Workspace apps

​Ids are encoded

​Dates

​Timeouts

​Account

​Platform status

​Next steps

Managing applications

Errors

API introduction

CLI quickstart

Requirements

Installation

API key and scopes

Creating the client

Options

Modules

Conventions

Ids first, plain data back

Workspace apps

Ids are encoded

Dates

Timeouts

Account

Platform status

Next steps