Square Cloud API: base URL and first request

The Square Cloud API is a REST API over HTTPS. It covers what you do in the dashboard: deploying and controlling applications, reading their logs and metrics, managing files, environment variables, snapshots, databases and workspaces. It sends and receives JSON, with two exceptions: upload and commit take a zip as multipart/form-data, and realtime streams Server-Sent Events.

Base URL

Every endpoint in this reference is relative to:

https://api.squarecloud.app/v2

Blob Storage is a separate API with its own base URL, https://blob.squarecloud.app/v1, and it takes the same API key.

Authentication

Create an API key in your account security settings and send it in the Authorization header of every request. The Bearer prefix is optional.

Authorization: <api_key>

The key is shown only once, when you create it. Keep it on your server, in an environment variable, and never in client-side code or in a repository. Each key carries scopes that limit what it can do: see Authentication for the scope of each endpoint.

Your first request

Account Information returns your profile, your plan and every application and database you own. It needs a key with the account:read scope.

export SQUARECLOUD_API_KEY="your-api-key"

curl https://api.squarecloud.app/v2/users/me \
  --header "Authorization: $SQUARECLOUD_API_KEY"

{
  "status": "success",
  "response": {
    "user": {
      "id": "1234567890",
      "name": "John Doe",
      "email": "john@example.com",
      "locale": "en-US",
      "plan": {
        "name": "standard-4",
        "memory": { "limit": 4096, "available": 3584, "used": 512 },
        "duration": 1780615237662
      },
      "created_at": "2024-05-01T12:00:00.000Z"
    },
    "applications": [
      {
        "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
        "name": "my-app",
        "ram": 512,
        "lang": "javascript",
        "domain": "my-app.squareweb.app",
        "custom": null,
        "cluster": "example-cluster",
        "created_at": "2024-05-01T12:00:00.000Z"
      }
    ],
    "databases": []
  }
}

If you get 401 ACCESS_DENIED, the key is missing or not recognized. If you get 403 MISSING_SCOPE, the key works but lacks account:read.

Response format

A successful call answers 2xx with "status": "success" and, when there is something to return, the data in response:

{ "status": "success", "response": { } }

Actions such as start or stop answer only { "status": "success" }. A failed call answers 4xx or 5xx with "status": "error" and a code to branch on:

{ "status": "error", "code": "APP_NOT_FOUND" }

Field names in responses use snake_case. Every code, with what to do about it, is in Errors.

IDs

Applications and databases have a 32-character hexadecimal id, such as a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d. Get them from Account Information or from the address of the resource in the dashboard.
An application shared with you through a workspace is addressed as <appId>-<workspaceId> in the path, for example /v2/apps/<appId>-<workspaceId>/status.
Workspaces have a 32-character hexadecimal id. Older workspaces keep a 40-character one.

Limits

Each account has a budget of requests per 60 seconds, set by its plan, and some endpoints have their own limit, stated on their page. See Limitations and restrictions for the values and Errors for how 429 works.

OpenAPI specification

The whole API is described in an OpenAPI document at https://api.squarecloud.app/v2/openapi.json. Import it into Postman or Insomnia, or generate a client from it.

Prefer a typed client? The Square Cloud SDKs for JavaScript, Python and Go wrap every endpoint of this reference, and the CLI covers the same tasks from a terminal.

Next steps

Authentication and scopes

Pick the scopes each integration needs.

Error codes

Every code the API returns and how to handle it.

Upload an application

Deploy a zip with one request.

Rate limits

Request budgets per plan.

Get started

Account

Applications

Databases

Workspaces

AI

Square Cloud API: base URL and first request

Base URL

Authentication

Your first request

Response format

IDs

Limits

OpenAPI specification

Next steps

Authentication and scopes

Error codes

Upload an application

Rate limits

​Base URL

​Authentication

​Your first request

​Response format

​IDs

​Limits

​OpenAPI specification

​Next steps

Authentication and scopes

Error codes

Upload an application

Rate limits

Base URL

Authentication

Your first request

Response format

IDs

Limits

OpenAPI specification

Next steps