> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud API: base URL and first request

> Start with the Square Cloud REST API: the v2 base URL, the Authorization header, a first curl request, the response envelope, IDs, scopes and error handling.

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](/en/api-reference/endpoint/apps/upload) and [commit](/en/api-reference/endpoint/apps/commit) take a zip as `multipart/form-data`, and [realtime](/en/api-reference/endpoint/apps/realtime) streams Server-Sent Events.

## Base URL

Every endpoint in this reference is relative to:

```bash theme={"system"}
https://api.squarecloud.app/v2
```

[Blob Storage](/en/blob-reference/quickstart) 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](https://squarecloud.app/en/account/security) and send it in the `Authorization` header of every request. The `Bearer ` prefix is optional.

```bash theme={"system"}
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](/en/api-reference/authentication) for the scope of each endpoint.

## Your first request

[Account Information](/en/api-reference/endpoint/users/me) returns your profile, your plan and every application and database you own. It needs a key with the `account:read` scope.

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"

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

```json theme={"system"}
{
  "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`:

```json theme={"system"}
{ "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:

```json theme={"system"}
{ "status": "error", "code": "APP_NOT_FOUND" }
```

Field names in responses use `snake_case`. Every code, with what to do about it, is in [Errors](/en/api-reference/errors).

## IDs

* **Applications and databases** have a 32-character hexadecimal id, such as `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`. Get them from [Account Information](/en/api-reference/endpoint/users/me) 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](/en/api-reference/limitations-and-restrictions) for the values and [Errors](/en/api-reference/errors#rate-limits) for how `429` works.

## OpenAPI specification

The whole API is described in an [OpenAPI document](/en/api-reference/openapi) at `https://api.squarecloud.app/v2/openapi.json`. Import it into Postman or Insomnia, or generate a client from it.

<Tip>
  Prefer a typed client? The [Square Cloud SDKs](/en/sdks/introduction) for [JavaScript](/en/sdks/js/client), [Python](/en/sdks/py/client) and [Go](/en/sdks/go/client) wrap every endpoint of this reference, and the [CLI](/en/cli-reference/quickstart) covers the same tasks from a terminal.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication and scopes" icon="lock" href="/en/api-reference/authentication">
    Pick the scopes each integration needs.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/en/api-reference/errors">
    Every code the API returns and how to handle it.
  </Card>

  <Card title="Upload an application" icon="upload" href="/en/api-reference/endpoint/apps/upload">
    Deploy a zip with one request.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/en/api-reference/limitations-and-restrictions">
    Request budgets per plan.
  </Card>
</CardGroup>