このページは SDK を全面的に書き直した
@squarecloud/api v6 を解説しています。v5 から移行する場合は、v5 → v6 移行ガイドをお読みください。要件
- Node.js 22 以降、Deno、Bun、またはエッジランタイム。SDK が必要とするのは
fetch、FormData、Blob、Web Streams だけです。 - API キー (API キーとスコープを参照)。
@squarecloud/api-types はもう必要ありません。
インストール
- npm
- pnpm
- yarn
- bun
- deno
API キーとスコープ
squarecloud.app/account/security でキーを作成します。SDK はキーをAuthorization ヘッダーにそのまま送信します (Bearer プレフィックスは付きません)。
キーはスコープ (apps:read、apps:deploy、apps:control、ai:chat など) や、特定のアプリ・データベースに制限できます:
- その制限を超える呼び出しは、403
MISSING_SCOPEまたはRESOURCE_NOT_ALLOWEDのSquareCloudAPIErrorをスローします。 - 一覧系のメソッド (
account.me()、apps.statusAll()など) は、キーから見えるリソースだけを返します。 - 不明なキー、取り消されたキー、期限切れのキーは 401
ACCESS_DENIEDになります。
SQUARECLOUD_API_KEY からキーを読み取ります。サンプルを実行するターミナルで設定してください:
- macOS / Linux
- Windows (PowerShell)
クライアントの作成
- TypeScript / ESM
- CommonJS
TypeError がスローされます。
オプション
モジュール
ランタイムでエクスポートされるのは
SquareCloudAPI、SquareCloudAPIError、BASE_URL だけです。その他のエクスポート (App、RuntimeStats、ErrorCode など) はすべて型です:
規約
ID を先に渡し、プレーンなデータを受け取る
すべてのメソッドはリソース ID を第 1 引数に取り、プレーンなデータを返します (クラスもキャッシュもありません)。フィールド名は API のもの (created_at、version_id、lastModified、joinedAt、netIO など) そのままなので、API リファレンスをそのまま適用できます。
- 変更系のメソッドは
voidで解決されます。ただし API がデータを返す場合 (envs.*、deploys.setWebhook、deploys.linkGithubApp、databases.resetCredentialsとcreate系のメソッド) は除きます。 - 文字列の結果が
undefinedになることはありません。API が何も送らない場合は""になります。 - 一覧は 1 回の呼び出しで完全に返されます。ページネーションはありません。
Workspace のアプリ
すべてのappId は、workspace を通じて共有されたアプリを操作するための複合形式 <appId>-<workspaceId> も受け付けます。workspaces.get() と workspaces.list() は素の ID を返すので、複合 ID は自分で組み立てます:
ID はエンコードされる
URL パス内の ID はパーセントエンコードされます。空、.、.. の ID は別のルートに届いてしまうため、何も送信する前にローカルで INVALID_ID (ステータス 0) として失敗します。Workspace のルートは ID をボディで送信するため、そこでの INVALID_ID (400) はサーバーから返されます。
日付
start と end の引数 (ネットワークを参照) は ISO 8601 文字列または Date を受け取ります。レスポンス内の日付は API が送ったまま (ISO 文字列、または API が使用している箇所では Unix ミリ秒) です。
タイムアウト
timeoutMs に 0 以下、Infinity、または >= 2^31 を指定すると、120 秒の下限も含めてすべてのタイムアウトが無効になります。
AbortSignal を受け取るメソッドは apps.create、apps.commit、files.write、apps.realtime、downloadSnapshot の 5 つだけです。
SquareCloudAPIError ではなくシグナルの reason で reject されます。中断された realtime() のループは単に終了します。
アカウント
api.account.me() は、認証済みのユーザーと、キーから見えるアプリおよびデータベースを返します。
api.account.snapshots({ scope }) はアカウントのすべての snapshot を一覧します。Snapshot を参照してください。
プラットフォームのステータス
api.service.status() は公開されているプラットフォームのステータスを返します。このルートに有効なキーは不要ですが、クライアントには空でないキーが必要です。
unknown はチェック自体を実行できなかったことを意味し、障害の証拠ではありません。
次のステップ
アプリケーションの管理
ステータス、ライフサイクル、ログ、メトリクス。
エラー
エラークラス、リトライ、レート制限。
API 入門
ベース URL、認証、最初のリクエスト。
CLI クイックスタート
ターミナルからアプリを deploy して管理します。

