# Deploy a Bun App or Bot Source: https://docs.squarecloud.app/en/articles/getting-started-with-bun Run Bun apps and bots on Square Cloud: add bun to package.json, start it with npx bun in START, and deploy on the Node.js runtime with automatic npm install. Square Cloud runs Bun on the [Node.js runtime](/en/articles/getting-started-with-nodejs): you add Bun to your project as an npm package and start your app with `npx bun`. ## Before you begin * Bun on your machine, from the [official Bun installer](https://bun.sh/), or the npm package (`npm install bun`). * A Square Cloud account: [sign up](https://squarecloud.app/en/signup) with your email or GitHub. * An active plan. See the [plans](https://squarecloud.app/en/pricing) and pick the one that fits your project. ## Configure Square Cloud If you upload your application through the dashboard, you can skip this section: the dashboard creates the `squarecloud.app` configuration file for you. The `squarecloud.app` file tells Square Cloud how to run your application: its main file, memory, runtime version, name and, for a website, its subdomain. First, add the `bun` package to your project's `dependencies`, so that the `npx bun` command is available on Square Cloud. Don't add it to `devDependencies`: they are not installed in production. ```bash theme={"system"} npm install bun ``` Then set `RUNTIME=nodejs` and start your app with Bun in the `START` field. A complete configuration file for each kind of app: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npx bun index.ts MEMORY=256 VERSION=recommended DISPLAY_NAME=My bot ``` ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npx bun index.ts MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` To run a `package.json` script with Bun instead, use `START=npx bun run start`. ## What Square Cloud runs * `START` is executed directly. For more information about configuration file parameters, visit [configuration parameters](/en/getting-started/config-file#configuration-parameters). * If the app has no `node_modules` folder, Square Cloud runs `npm install --no-audit --no-fund` before starting it, which also installs `bun`. Packages in `devDependencies` are not installed, because the runtime sets `NODE_ENV=production`. When `node_modules` already exists, the install step is skipped. ### Port and host for websites and APIs Square Cloud sets the `PORT` environment variable to `80`. `Bun.serve()` reads `PORT` by itself and listens on all network interfaces (`0.0.0.0`) by default, so a plain server works: ```typescript index.ts theme={"system"} Bun.serve({ fetch() { return new Response("Hello, World!"); }, }); ``` ## Prepare the project ### Required files * [`squarecloud.app`](/en/getting-started/config-file), at the root of the ZIP. * Your entry file, for example `index.ts`. * [`package.json`](/en/articles/how-to-create-your-package-json), which lists `bun` in `dependencies`. An upload without it fails with `INVALID_DEPENDENCY`. The configuration file (`squarecloud.app`) must be located at the root of the zip file. Otherwise, Square Cloud will not be able to find it during deploy. ### What to leave out * `node_modules`: Square Cloud removes this folder from your upload and installs the dependencies from `package.json` on the first start. * Lockfiles: dependencies are installed with npm, so `bun.lock` is not used. The CLI and the VS Code extension also leave `package-lock.json`, `yarn.lock` and `pnpm-lock.yaml` out by default; when you need the exact versions of your `package-lock.json`, re-include it with `!package-lock.json` in your [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore). ## Troubleshooting `bun` is missing from the `dependencies` of your `package.json`, or it is in `devDependencies`. Run `npm install bun`, upload the new `package.json`, then delete the `node_modules` folder in the dashboard file manager so the next start installs it. The minimum amount of RAM required to host a bot is 256MB and for a site/API it is 512MB. However, depending on the size and complexity of your application, it may be advisable to allocate a larger amount of RAM to avoid your application running out of memory and crashing. For other problems, see [Troubleshooting](/en/platform/troubleshooting). ## Deploy ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Uploading application to Square Cloud

Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Create a package.json for Node.js Source: https://docs.squarecloud.app/en/articles/how-to-create-your-package-json Create a package.json for a Node.js app: initialize it with npm init, add start scripts and dependencies, and see what Square Cloud installs in production. The `package.json` file is the heart of any Node.js project. It acts as a manifest that lists dependencies, defines automation scripts, and configures the project's behavior. This guide teaches how to configure a robust `package.json`, ensuring your project is reproducible, organized, and compatible with the Square Cloud environment. *** The safest way to create the file is by using the NPM CLI. Navigate to the root of your project and choose one of the options: **Option A: Interactive (Recommended for beginners)** Answer the questions step-by-step to configure custom metadata. ```bash theme={"system"} npm init ``` **Option B: Automatic (Default)** Generates the file immediately accepting all default settings. ```bash theme={"system"} npm init -y ``` Open the generated `package.json`. For a professional project, ensure these fields are filled correctly: * `name`: Unique project identifier (use kebab-case, e.g., `my-project-api`). * `version`: Follows the SemVer standard (e.g., `1.0.0`). * `main`: The entry point of the application (usually `index.js` or `src/index.js`). * `type`: Set as `"module"` if using ES Modules (import/export) or remove to use CommonJS (require). The `scripts` section is vital for automation. This is where you define how your application should be started, tested, or built. ```json theme={"system"} "scripts": { "start": "node index.js", "test": "echo \"Error: no test specified\" && exit 1" } ``` **About initialization on Square Cloud:** By default, Square Cloud runs `node MAIN` (the file set in `MAIN`), but it offers full flexibility. You can (and should) explicitly configure which command the system should execute to start your application. For example, you can configure the **Start Command** in the dashboard or in the Square configuration file to execute `npm run start`, ensuring that the script defined above is respected. Here lie the essential libraries for your code to run in production. To install and automatically save to this list: ```bash theme={"system"} npm install package-name ``` **Attention to `devDependencies` and Build on Square Cloud:** Tools used only in local development (like `eslint` or `prettier`) stay in `devDependencies`. **Important:** Square Cloud performs installation in production mode by default, which means packages listed in `devDependencies` are **NOT** installed. If you need to run a **build** process in the cloud (e.g., compile TypeScript or run post-install scripts), you must move those tools to `dependencies`. Otherwise, the build will fail due to missing packages. For more complex projects, `package.json` offers powerful control features: **1. Overrides (Force versions):** Useful when a dependency you use installs a sub-dependency with multiple vulnerabilities. You can force resolution to a safe version: ```json theme={"system"} "overrides": { "vulnerable-package": "2.0.1" } ``` **2. Imports (Path aliases):** Avoid long relative paths like `../../../utils`. With `imports`, you create native internal shortcuts (requires recent Node): ```json theme={"system"} "imports": { "#utils/*": "./src/utils/*.js", "#database": "./src/core/database.js" } ``` This allows importing in code using `import db from '#database'`. *** ## Tips and best practices * **Semantic Versioning**: Prefer fixing critical versions by removing `^` (e.g., use `"14.14.1"` instead of `"^14.14.1"`) to prevent automatic updates from breaking your production code. * **Security**: Run `npm audit` regularly to identify vulnerabilities in your dependencies. The `overrides` field taught above is the ideal solution to fix these issues. * **package-lock.json**: Keep it in Git: it records the exact dependency tree that worked on your machine. The Square Cloud CLI and the VS Code extension leave lockfiles out of uploads by default, so Square Cloud installs the newest versions allowed by the ranges in `package.json`. When you need the pinned versions, re-include it with `!package-lock.json` in your [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore). * **Organization**: Keep the file clean. If the `scripts` section gets too big, consider using external automation tools or separating into files. *** ## Final file example Below, an example of a modern and optimized `package.json`: ```json package.json theme={"system"} { "name": "square-cloud-project", "version": "1.0.0", "description": "Professional Node.js API", "main": "src/index.js", "type": "module", "scripts": { "start": "node src/index.js", "lint": "eslint ." }, "imports": { "#services/*": "./src/services/*.js" }, "dependencies": { "discord.js": "14.14.1", "dotenv": "16.3.1", "typescript": "5.3.3" }, "devDependencies": { "eslint": "8.56.0" } } ``` *** ## Next steps With your `package.json` file configured: 1. Commit it to your Git repository. 2. Host your project with the [Node.js runtime guide](/en/articles/getting-started-with-nodejs), or follow a framework guide such as [Express](/en/tutorials/api/express) or [Next.js](/en/tutorials/website/nextjs). 3. [Deploy automatically from GitHub](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) on every push. # How to Create a pyproject.toml File Source: https://docs.squarecloud.app/en/articles/how-to-create-your-pyproject Create a pyproject.toml for a Python app: declare project metadata, pinned dependencies and a build system so Square Cloud can install it with pip. The `pyproject.toml` file is a modern way to specify all your project's build system requirements and dependencies in a single file. This guide shows how to create, configure and use `pyproject.toml` to ensure consistency between development and production environments. ## What is a pyproject.toml file? A `pyproject.toml` lists dependencies, build system and other metadata for your Python project. This allows: * You and your team to maintain identical environments * New collaborators to reproduce the environment exactly * Set up development and production dependencies separately *** First, create a file named `pyproject.toml` in the root of your project. In the `pyproject.toml` file, start by defining your project metadata. We will define the project name, version, description, and other relevant information.\ The project name must consist of ASCII letters, digits, underscores “\_”, hyphens “-” and periods “.”. It must not start or end with an underscore, hyphen or period. For example: ```toml pyproject.toml theme={"system"} [project] name = "my-python-project" description = "A sample Python project using pyproject.toml" version = "1.0.0" ``` Next, we will list the dependencies required for our project. We can specify both development and production dependencies. The production dependencies are listed under the `dependencies` section, while development dependencies can be listed under `optional-dependencies` with a specific group name (e.g., `dev`).\ You can specify versions for your dependencies using comparison operators like `==`, `>=`, `<`... In the example below, every dependency is pinned to an exact version with `==`. It is recommended to specify exact versions to ensure reproducibility and prevent breakage from incompatible updates in production. ```toml pyproject.toml theme={"system"} [project] name = "my-python-project" description = "A sample Python project using pyproject.toml" version = "1.0.0" dependencies = [ "discord.py==2.7.1", "aiohttp==3.14.3" ] [project.optional-dependencies] dev = [ "pytest==9.1.1", "black==26.5.1" ] ``` Finally, we need to specify the build system requirements. This is necessary for tools like pip to know how to build and install your project. We will use `setuptools` as our build backend, which is a common choice for Python projects, but you can choose others like `poetry`. The `py-modules = []` line under `[tool.setuptools]` tells setuptools that there is no module to package, so `pip install .` only installs the dependencies. Without it, an app with several top-level folders (for example `cogs/` and `utils/`) fails with `Multiple top-level packages discovered in a flat-layout`. ```toml pyproject.toml theme={"system"} [project] name = "my-python-project" description = "A sample Python project using pyproject.toml" version = "1.0.0" dependencies = [ "discord.py==2.7.1", "aiohttp==3.14.3" ] [project.optional-dependencies] dev = [ "pytest==9.1.1", "black==26.5.1" ] [build-system] requires = ["setuptools"] build-backend = "setuptools.build_meta" [tool.setuptools] py-modules = [] ``` *** ## Install dependencies with pip To install the dependencies listed in your `pyproject.toml` file, you can use pip or other tools that support `pyproject.toml`. This allows you to work on your project while having the dependencies installed. ```bash theme={"system"} pip install . ``` This command will read the `pyproject.toml` file, install the dependencies listed under `dependencies`, and set up your project for development. It is also what Square Cloud runs when your upload has a `pyproject.toml` and no `requirements.txt`. If you want to install the development dependencies as well, you can use: ```bash theme={"system"} pip install .[dev] ``` This will install both the production and development dependencies, allowing you to work on your project with all the necessary tools. ## Best practices and tips * **Keep updated**: Review and update `pyproject.toml` regularly as you add new dependencies * **Use exact versions**: Always use `==` instead of `>`, `>=` or no version to avoid surprises in production * **Versioning**: Commit `pyproject.toml` to git to track dependency changes and version updates * **Isolated environment**: Maintain one virtual environment per project to avoid global conflicts * **Test locally**: Before deploying, test the file with `pip install .` in a new environment *** ## Next steps With your `pyproject.toml` file configured: 1. Commit it to your Git repository. 2. Host your project with the [Python runtime guide](/en/articles/getting-started-with-python), or follow a framework guide: [Django](/en/tutorials/api/django), [Flask](/en/tutorials/api/flask) or [FastAPI](/en/tutorials/api/fastapi). 3. [Deploy automatically from GitHub](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) on every push. # How to Create a requirements.txt File Source: https://docs.squarecloud.app/en/articles/how-to-create-your-requirements Create a requirements.txt for a Python app: generate it with pip freeze inside a virtual environment, pin versions with ==, and deploy it on Square Cloud. The `requirements.txt` file is the industry standard for specifying and managing dependencies in Python projects. This guide shows how to create, configure and use `requirements.txt` to ensure consistency between development and production environments. ## What is a requirements.txt file? A `requirements.txt` file lists all external Python packages your project needs, with their specific versions. This allows: * You and your team to maintain identical environments * New collaborators to reproduce the environment exactly * Deploy on Square Cloud to work with the correct dependencies *** Working inside a virtual environment is essential to keep your project dependencies isolated from the global Python system. This avoids version conflicts and ensures reproducibility. Create the virtual environment in the root of your project (use `python3` if `python` is not found on macOS/Linux): ```bash theme={"system"} python -m venv .venv ``` Activate it with one of the commands below, depending on your system: **Windows:** ```bash theme={"system"} .venv\Scripts\activate ``` **macOS/Linux:** ```bash theme={"system"} source .venv/bin/activate ``` Then install the packages your project uses, for example: ```bash theme={"system"} pip install discord.py python-dotenv ``` Always specify exact versions with `==` to ensure reproducibility and prevent breakage from incompatible updates in production. ### Option A: Generate with pip freeze (recommended) With the virtual environment activated, write every installed package and its exact version to the file: ```bash theme={"system"} pip freeze > requirements.txt ``` Inside a virtual environment, `pip freeze` lists only the packages installed in it (your dependencies and their sub-dependencies), already pinned with `==`. Outside a virtual environment, `pip freeze` lists every package installed on your system. Review the file and remove what your project does not use. ### Option B: Create manually Create a `requirements.txt` file in the root of your project and list the packages your project uses, with their versions: ```plaintext requirements.txt theme={"system"} discord.py==2.7.1 requests==2.34.2 python-dotenv==1.2.3 ``` Open the `requirements.txt` file in your text editor and: 1. Review the package list 2. Remove unnecessary dependencies 3. Update versions as needed 4. Ensure you are using exact versions (with `==`) To install all listed dependencies: ```bash theme={"system"} pip install -r requirements.txt ``` This command guarantees that all collaborators and production environments use exactly the same versions. With `requirements.txt` ready, you can: * Share it with your team * Put it in version control (git) * Ensure everyone works with the same versions * Simplify deployment on Square Cloud When you host your project on Square Cloud, the `requirements.txt` file is automatically detected and its dependencies are installed with `pip install -r requirements.txt` before your app starts. *** ## Best practices and tips * **Keep updated**: Review and update `requirements.txt` regularly as you add new dependencies * **Use exact versions**: Always use `==` instead of `>`, `>=` or no version to avoid surprises in production * **Review pip freeze**: If using `pip freeze`, review the file before committing, as it may include unnecessary auxiliary packages * **Versioning**: Commit `requirements.txt` to git to track dependency changes * **Isolated environment**: Maintain one virtual environment per project to avoid global conflicts * **Test locally**: Before deploying, test the file with `pip install -r requirements.txt` in a new environment *** ## Next steps With your `requirements.txt` file configured: 1. Commit it to your Git repository. 2. Host your project with the [Python runtime guide](/en/articles/getting-started-with-python), or follow a framework guide: [Django](/en/tutorials/api/django), [Flask](/en/tutorials/api/flask) or [FastAPI](/en/tutorials/api/fastapi). 3. [Deploy automatically from GitHub](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) on every push. # Migrate from Heroku to Square Cloud Source: https://docs.squarecloud.app/en/articles/migrating-from-heroku Migrate from Heroku to Square Cloud: map your Procfile, Config Vars, Postgres and logs, deploy with the CLI and point your custom domain. ## What you get on Square Cloud * **Predictable flat pricing in BRL**: one monthly plan price covers the RAM and vCPU your applications use. See [Plans and Pricing](/en/platform/plans). * **Dedicated resources**: RAM and vCPU are reserved for your applications. * **Deploy in seconds**: upload a zip or push via CLI and your application is running. ## Concept mapping | Heroku | Square Cloud | | - | - | | `Procfile` (`web:`/`worker:` process types) | [`squarecloud.app` configuration file](/en/getting-started/config-file): `MAIN`/`START` fields | | Buildpacks | [Runtimes](/en/runtimes/introduction): automatic language detection, no buildpack to choose | | Config Vars | [Environment variables](/en/platform/environment-variables), set in the dashboard or uploaded from a `.env` file | | `$PORT` | `PORT`, set to `80` on Square Cloud, plus `HOST=0.0.0.0`: code that listens on `process.env.PORT` keeps working | | Heroku Postgres | [Square Cloud managed databases](/en/services/databases) (PostgreSQL, MySQL, MongoDB, Redis) | | `heroku logs --tail` | [`squarecloud app realtime`](/en/cli-reference/logs#squarecloud-app-realtime) to stream live logs, [`squarecloud app logs`](/en/cli-reference/logs#squarecloud-app-logs) for the most recent lines, or the dashboard logs | | Custom domains (paid dynos) | Custom domains on the [Standard plan or higher](/en/platform/plans) | ## Migration steps Replace your `Procfile` with a `squarecloud.app` file at the root of your project. A Heroku `Procfile` like: ``` web: node index.js ``` becomes: ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My migrated app SUBDOMAIN=my-app ``` A `web` process must listen on host `0.0.0.0` and on the port in `PORT` (`80`). For a worker process type, drop `SUBDOMAIN` and set `START` to your worker's start command instead. See the [configuration file reference](/en/getting-started/config-file) for every field. Export your Heroku Config Vars (`heroku config`) and set the same keys on Square Cloud, either from the dashboard's environment variables panel or by uploading a `.env` file: ```bash theme={"system"} squarecloud app env set --from-file .env --app ``` Then restart the application: it reads environment variables when it starts. See [Environment variables](/en/platform/environment-variables). Upload your project via the CLI or the dashboard: ```bash theme={"system"} squarecloud upload ``` See [How to Host your Website/API](/en/tutorials/how-to-deploy-your-website) for a full walkthrough of both methods. Once the app is live at `.squareweb.app`, point your domain's DNS at Square Cloud and attach it from the CLI: ```bash theme={"system"} squarecloud app network domain example.com --app ``` Custom domains require an active Standard plan or higher. For the DNS records, see [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) in the help center. ## Key differences to plan for * **Region and latency.** Square Cloud's data center is located in New York: see the [Platform Overview](/en/platform/overview) for infrastructure details. If most of your users are in a different region than your current Heroku dyno region, measure latency before cutting over. * **An active plan is required.** Every application runs on one. See [Plans and Pricing](/en/platform/plans) to pick the right tier for your workload. * **Databases move separately.** Migrating Heroku Postgres data means exporting it (e.g. `pg_dump`) and restoring it into a new [Square Cloud managed database](/en/services/databases): plan a maintenance window for the cutover. ## Next steps Every field of the file that replaces your Procfile. Move your Config Vars and keep secrets out of your code. Create the database that replaces Heroku Postgres. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Migrate from Railway to Square Cloud Source: https://docs.squarecloud.app/en/articles/migrating-from-railway Migrate from Railway to Square Cloud: map railway.json, variables and database plugins, deploy with the CLI and move to flat monthly plan pricing. ## What you get on Square Cloud * **Predictable flat pricing in BRL**: one monthly plan price for the RAM and vCPU your applications use, independent of how much traffic they handle. See [Plans and Pricing](/en/platform/plans). * **Dedicated resources**: RAM and vCPU are reserved for your applications. * **Deploy in seconds**: upload a zip or push via CLI and your application is running. ## Concept mapping | Railway | Square Cloud | | - | - | | `railway.json` / Nixpacks | [`squarecloud.app` configuration file](/en/getting-started/config-file) + automatic [Runtimes](/en/runtimes/introduction) | | Usage-based billing | Flat monthly [plan pricing](/en/platform/plans) | | Postgres/Redis plugins | [Square Cloud managed databases](/en/services/databases) (PostgreSQL, MySQL, MongoDB, Redis) | | Environment variables | [Environment variables](/en/platform/environment-variables), set in the dashboard or uploaded from a `.env` file | | `PORT` variable | `PORT`, set to `80` on Square Cloud, plus `HOST=0.0.0.0`: code that listens on `process.env.PORT` keeps working | | `railway up` | `squarecloud upload` | | Custom domains | Custom domains on the [Standard plan or higher](/en/platform/plans) | ## Migration steps Replace `railway.json`/Nixpacks detection with a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My migrated app SUBDOMAIN=my-app ``` Square Cloud's [Runtimes](/en/runtimes/introduction) detect your language automatically from the extension of your `MAIN` file and check its dependency file, such as `package.json` or `requirements.txt`. A web service must listen on host `0.0.0.0` and on the port in `PORT` (`80`). See the [configuration file reference](/en/getting-started/config-file) for every field. Recreate the variables from your Railway project's Variables tab, either from the dashboard's environment variables panel or by uploading a `.env` file: ```bash theme={"system"} squarecloud app env set --from-file .env --app ``` Then restart the application: it reads environment variables when it starts. See [Environment variables](/en/platform/environment-variables). Upload your project via the CLI or the dashboard, in place of `railway up`: ```bash theme={"system"} squarecloud upload ``` See [How to Host your Website/API](/en/tutorials/how-to-deploy-your-website) for a full walkthrough of both methods. If your project used a Railway Postgres, MySQL or Redis plugin, provision the equivalent [Square Cloud managed database](/en/services/databases) and point your app's connection string at it. Once the app is live at `.squareweb.app`, point your domain's DNS at Square Cloud and attach it from the CLI: ```bash theme={"system"} squarecloud app network domain example.com --app ``` Custom domains require an active Standard plan or higher. For the DNS records, see [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) in the help center. ## Key differences to plan for * **Billing model.** There is no per-second usage meter to watch: cost is fixed per plan regardless of traffic. Size your plan by RAM/vCPU need rather than projected usage. See [Plans and Pricing](/en/platform/plans). * **Region and latency.** Square Cloud's data center is located in New York: see the [Platform Overview](/en/platform/overview) for infrastructure details. Measure latency from your user base before cutting over if you were running in a different Railway region. * **Databases move separately.** Migrating a Railway Postgres/Redis plugin's data means exporting it and restoring it into a new [Square Cloud managed database](/en/services/databases): plan a maintenance window for the cutover. ## Next steps Every field of the file that replaces railway.json. Move your variables and keep secrets out of your code. Create the database that replaces your Railway plugin. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Changelog Source: https://docs.squarecloud.app/en/changelog Discover the latest news and improvements in Square Cloud. Follow product releases, performance optimizations, and much more. ## 🔗 Git webhooks * **Tags and deleted branches no longer block a deploy:** a push of a tag (or any ref that isn't a branch) and a push that deletes a branch are answered with `202` and never deployed, and they no longer use up the webhook's limit of 1 push per 15 seconds. A release sent with `git push --follow-tags`, or a merged pull request whose branch is deleted automatically, no longer holds back the deploy of the branch push that arrives with it. * **The reply says why:** it starts with `GIT_REF_NOT_SUPPORTED` or `GIT_BRANCH_DELETED`, shown on GitHub in **Settings > Webhooks > Recent Deliveries**. See [Webhook deliveries](/en/api-reference/endpoint/apps/deploy/webhooks#webhook-deliveries). ## ⚙️ Applications * **Start, stop and restart during a restore:** while a snapshot restore runs on an application (up to about 2 minutes), these actions now answer `403 RESTORE_IN_PROGRESS` right away, instead of waiting and then failing. Wait for the restore to finish and try again. ## 🔌 AI Gateway: when to retry * **`Retry-After` on limits:** `429 rate_limit_exceeded` carries the plan's pacing, so the OpenAI SDKs wait and retry on their own, and `503 server_overloaded` asks for 2 seconds. The daily and weekly limits, and `503 daily_capacity_reached`, carry the time until the reset plus `x-should-retry: false`, so the SDKs stop repeating requests that can only fail again. See [Retries](/en/api-reference/ai-gateway#retries). ## 🤖 Cubic: larger limits * **Daily limits raised on every plan:** Hobby 5M tokens (was 2M), Standard 10M to 20M (was 5M to 10M), Pro 30M to 40M (was 15M) and Enterprise 50M to 100M (was 25M to 50M). * **New weekly limit** of 4x the daily one, reset on Monday at 00:00 UTC. A heavy day is fine: only near-maximum use almost every day of the week reaches it. When it does, Cubic answers `AI_WEEKLY_LIMIT_REACHED` until the reset. ## 🔌 AI Gateway: its own limits * **Separate from Cubic:** gateway requests now count only against the gateway's own token limits, so an API key never uses up your Cubic allowance, and vice versa. * **Token limits per plan:** Standard 2.5M tokens per day, Pro 5M and Enterprise 10M to 20M by plan size, each with a weekly limit of 4x, reset on Monday at 00:00 UTC. The new `429 weekly_limit_reached` tells the weekly limit apart from the daily `daily_limit_reached`. See [Plans and limits](/en/api-reference/ai-gateway#plans-and-limits). * **Fair-use allowance recalibrated:** Pro now has 2x the base allowance and Enterprise 5x. ## 💻 Square Cloud CLI * **Log in from the browser:** `squarecloud auth login` shows a code and opens the authorization page. Approve it and the CLI receives its own API key, limited to the permissions it uses and valid for 90 days. For scripts and CI, use `--token`, `--with-token` or the `SQUARECLOUD_API_KEY` environment variable. See [Authentication](/en/cli-reference/authentication). * **`squarecloud.ignore` with real gitignore rules**, the same file the VS Code extension reads: `!` re-includes, `**`, folder-only and root-only patterns. See the [squarecloud.ignore guide](/en/getting-started/squarecloud-ignore). * **Eight languages:** German, French, Italian and Japanese join English, Portuguese, Spanish and Chinese. Help and flag descriptions are translated too, and the language follows your system on every run. * **More reliable transfers:** large uploads and commits are no longer cut off after 30 seconds, `app realtime` stays connected, and `app file write`, `app file read` and `app file delete` work with any file, binary included. * **New:** `app env remove --all`, `--json` on `app logs`, `upload` and `auth whoami`, a confirmation before `app file read -o` overwrites a local file, and clear hints when a key expired or a rate limit was hit. * **Install:** the install script verifies the release checksums and supports 32-bit x86 and ARMv7, and the npm package installs on arm64 and ARMv7. Update with `npm install -g @squarecloud/cli@latest`. **Read before upgrading CI jobs.** The [Scripts and CI](/en/cli-reference/global-flags-and-ci#scripts-and-ci) section has the details. * Commands that ask for confirmation exit with code 1 when there is no terminal and no `-y`, instead of doing nothing. Pass `-y`. * `auth login` no longer prompts for a key. In scripts, set `SQUARECLOUD_API_KEY` or use `auth login --with-token` or `--token `. * More failures exit with code 1, and an npm install now passes the real exit code through. Check exit codes, not message text. * Commands without JSON output reject `--json`, and `app logs --json` prints `{"logs": "..."}`. * Errors, prompts and the update notice go to stderr, and `app realtime` prints log lines as they are, with `[status] ` only when the status changes. * Table headers are translated on non-English systems: parse `--json`, or run with `LC_ALL=en_US.UTF-8`. * `package-lock.json`, `pnpm-lock.yaml` and `yarn.lock` are no longer uploaded by default: add `!package-lock.json` (or your lockfile) to `squarecloud.ignore` to keep it. Patterns follow gitignore rules, so review rules that relied on name-suffix matching. * `app env replace` needs at least one variable (use `app env remove --all -y` to clear them all), and with `--from-file` an unquoted value ends at ` #`. * `locale` in the config file is ignored: the language follows the system, or `LC_ALL`/`LANG`. ## 🧩 VS Code extension The extension now has its own [documentation](/en/vscode-extension/installation): installation, features, commands and troubleshooting. * **Get Started walkthrough:** `Square Cloud: Get Started` opens a ten-step guide (connect, config file, upload and commit, logs and metrics, snapshots, databases, workspaces, GitHub deploys and edge analytics) with buttons that run the real commands. * **Redesigned sign-in and dashboard** with the Square Cloud look: a step-by-step sign-in that explains each permission, skeletons while loading, illustrated empty and error states, paging and a filter for long application lists, and full keyboard and high-contrast support. * **Eight languages**, like the Square Cloud website. * **From the command palette:** application and database actions ask which one to use, and pickers offer only what fits (Start lists applications that aren't running). * **Official JavaScript SDK v6** underneath: the extension shows the API's real error codes and messages, times calls out and retries only what is safe to retry. * **Same ignore file as the CLI:** `squarecloud.ignore` with gitignore syntax and the same defaults. `.gitignore` is no longer read in its place, and a `\` makes the next character literal. * **Fixes:** an expired authorization asks you to connect again, snapshot restore uses the listing's own identifiers, snapshots stream to disk, deleting keeps the application when the recovery snapshot is still being generated, and the 24h metrics show RAM correctly. ## 🧰 SDKs rewritten from scratch The JavaScript, Python and Go SDKs have new major versions, rewritten for the current API. All three cover the same **67 operations** plus snapshot downloads, share the same structure and examples, and have **zero runtime dependencies**. The [SDK documentation](/en/sdks/introduction) was rewritten for them. | SDK | Version | Migration guide | | - | - | - | | `@squarecloud/api` | 6.0.0 (Node.js 22+, Deno, Bun, edge) | [v5 → v6](/en/sdks/js/migrating_to_v6) | | `squarecloud-api` | 5.0.0 (Python 3.11+) | [v4 → v5](/en/sdks/py/migrating_to_v5) | | `github.com/squarecloudofc/sdk-api-go/v3` | 3.0.0 (Go 1.22+) | [v2 → v3](/en/sdks/go/migrating_to_v3) | | `@squarecloud/blob` | 4.0.0 (Node.js 20+ and browsers) | [v3 → v4](/en/sdks/blob/migrating_to_v4) | **These are breaking releases.** Methods now take the id first and return the API's own data (no classes, no cache, no events), and every failure is a single error type with the HTTP `status`, the API's `code` and the server's `message`. Read the migration guide before upgrading. * **One error type per SDK:** `SquareCloudAPIError` (JavaScript and Python) and `*APIError` (Go). Codes the SDK used to invent are gone: an expired key is `401 ACCESS_DENIED`, and a response without a code is `UNKNOWN_ERROR` with the real status. * **Timeouts:** 30 seconds by default, and at least 120 seconds for calls the server holds open (start, stop, restart, snapshots, database creation and AI). * **Retries only when safe:** network errors on `GET` and `503 UPLOAD_BUSY`/`ANALYTICS_BUSY`, with backoff. A `429` is never retried. * **New in all three:** [AI Gateway](/en/api-reference/ai-gateway) chat, network analytics, realtime logs and status with automatic reconnection, GitHub App deploys with an API key, streamed uploads and snapshot downloads, and apps shared through a workspace (`-`). * **Python:** a sync `SquareCloud` and an async `AsyncSquareCloud` client, using only the standard library. The app cache and listeners were removed. * **Go:** `context` on every call, and the license is now MIT. ## 🗂️ Blob SDK v4 * The new [Blob SDK documentation](/en/sdks/blob/client) covers uploads, objects, links, shares, rules, stats and the S3 gateway. * A `429` is never retried, and writes get a single attempt. Reads and multipart parts are retried on network errors and any `5xx`. * `maxRetries` now defaults to `2` (was `5`) and the backoff is capped at 8 seconds. Pass `{ maxRetries: 5 }` to keep the old read budget. ## 🛡️ API and Blob Storage **If your code checks `RATE_LIMIT` or `RATE_LIMIT_EXCEEDED`, switch to `RATE_LIMITED`.** The account or API key request limit and the temporary block for invalid keys in the [API](/en/api-reference/authentication), the [network](/en/api-reference/endpoint/apps/network/analytics) routes, [`GET /v2/users/snapshots`](/en/api-reference/endpoint/users/snapshots) and the account limit and invalid-credential block in [Blob Storage](/en/blob-reference/errors) now all answer `429 RATE_LIMITED`. `KEEP_CALM` and the other `429` codes don't change. * **Database start and stop:** when the cluster refuses the action, [start](/en/api-reference/endpoint/databases/start) and [stop](/en/api-reference/endpoint/databases/stop) now answer `409` with the error code (`CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_TEMPORARILY_SUSPENDED` or `ACTION_FAILED`), instead of `200` with `status: "error"`. * **Application start, stop and restart:** the `409` body carries only `status` and `code`, and a failure to reach the cluster answers `ACTION_FAILED`. * **Database creation:** `memory` must be a whole number of MB. A decimal or a string answers `400 INSUFFICIENT_MEMORY`. * **AI Gateway:** a request that takes longer than **90 seconds** in total answers `503 server_overloaded` and can be retried. See the [error table](/en/api-reference/ai-gateway). * **GitHub App:** [linking a repository](/en/api-reference/endpoint/apps/deploy/github-app-link) needs write (push) or admin permission on it (`403 REPOSITORY_PERMISSION_REQUIRED`), and a repository and branch can be linked to only one application on the whole platform. ## 📁 File manager in base64 **[Read File](/en/api-reference/endpoint/apps/filemanager/content) without `encoding` is deprecated.** The `{ "type": "Buffer", "data": [...] }` response will be removed on **March 27, 2027**, when base64 becomes the default. Send `?encoding=base64` now to get `{ "encoding": "base64", "data": "" }`. Until then, the legacy response carries the `Deprecation` and `Sunset` headers. * **Writing in base64:** [Create/Modify File](/en/api-reference/endpoint/apps/filemanager/put) accepts `encoding: "base64"`, the recommended format for binary files. An empty `content` (`""` or `[]`) writes an empty file. * [List Files](/en/api-reference/endpoint/apps/filemanager/list) answers `404 FILE_NOT_FOUND` for a directory that doesn't exist, instead of an empty list. ## 🔧 More API changes * **Git webhook replies:** the [webhook URL](/en/api-reference/endpoint/apps/deploy/webhooks) answers in plain text whether a deploy was queued, so **Recent Deliveries** on GitHub shows what happened to each push. A `200` is sent only once the deploy is stored in the queue. A `503` means nothing was deployed: redeliver the push or push again. * **AI Gateway:** every error, including authentication, scope, rate-limit and invalid-body errors, now uses the OpenAI format with a lowercase `code` (`access_denied`, `missing_scope`, `rate_limited` and others). See the [error table](/en/api-reference/ai-gateway). * **Expired API keys** answer `401 ACCESS_DENIED`, exactly like an invalid key. The `APIKEY_EXPIRED` code no longer exists. * **Database creation:** a creation that fails leaves nothing behind, so it is safe to [try again](/en/api-reference/endpoint/databases/create). ## 🗂️ The biggest Blob Storage update yet Blob Storage got its biggest update since launch and is now **out of beta**. You can now store **private** files, hand files out through **temporary links** or **share links**, use **S3 tools** (aws-cli, boto3, rclone, the AWS SDKs), let the **browser upload directly** without exposing your API key, set **rules per prefix** and upload files of up to **10 GiB**. The [Blob documentation](/en/services/blob) was rewritten from scratch, with a page for every route. **What changes if you already integrate with Blob:** * **New files have an id starting with `pub/` or `prv/`** (`pub//images/logo.png`). Existing files keep their id, and every route accepts both forms. Store the `id` as it comes and treat it as opaque: it changes when the file changes visibility or expiry. * **New public files are served from `https://blob.squarecloud.dev/pub/...`.** The existing URLs on `public-blob.squarecloud.dev` keep working for **30 days, until October 25, 2026**: move those files with [`POST /v1/objects/copy`](/en/blob-reference/endpoint/copy) (`move: true`) to get their new URL. * **Read a file's expiry from `expires_at`**, present in the upload, list and info responses. Don't parse the date out of the file name. * **Options that depend on the plan answer `403 UPGRADE_REQUIRED`**, with a `message` naming the plan that unlocks the feature. ## 🔒 Private files and links * **`private=true` on upload** stores the file without a public URL. It is read through the API, the S3 gateway or a link. * **Change visibility any time** with the new [`PATCH /v1/objects`](/en/blob-reference/endpoint/update). Making a file private removes the public copy before answering, and the CDN stops serving it in about 60 seconds. Making files private works even on an account without an active plan. * **Temporary links** with the new [`GET /v1/objects/download`](/en/blob-reference/endpoint/download): valid from 60 seconds to 24 hours, no credential needed, `Range` support (resumable downloads and video) and a choice of the name the file is saved as. * **Share links** with the new [`POST /v1/shares`](/en/blob-reference/endpoint/shares-create): up to 30 days, **revocable** at any time, with an optional **download cap** and, on Pro and Enterprise, a **password**. The link page follows the visitor's language in the platform's 8 languages. * A share link whose file was deleted, moved or changed visibility answers `404` right away, before any password page and without spending a download, and leaves the list of links. * A share link to a **public** file ends in a redirect to the file's permanent URL, so the password, the download cap and the expiry only truly protect **private** files. Share private files when the protection matters. * The [Links and sharing](/en/blob-reference/links-and-sharing) page compares the three kinds of link and when to use each. ## 🪣 S3-compatible * An **S3 gateway** at `https://s3-blob.squarecloud.app` works with aws-cli, boto3, rclone, Cyberduck and the AWS SDKs. * The key pair comes from the new [`GET /v1/s3/credentials`](/en/blob-reference/endpoint/s3-credentials) and is **derived from your API key**: revoking or regenerating the key does the same to the pair, and a key with only `blob:read` gives a read-only pair. * Three fixed buckets per account: `public`, `private` and `legacy` (legacy files, uploaded before this update, with read, list and delete). * Rate limits per plan, every 10 seconds: Hobby 100, Standard 200, Pro 400 and Enterprise 600 requests. S3 requests don't count against your plan's API request limit. * Supports listing with folders, `Range`, multipart uploads of up to 10 GiB, server-side copy, batch delete of up to 1000 keys, presigned URLs of up to 7 days and checksum verification. Details in [S3 compatibility](/en/blob-reference/s3-compatibility). * `Content-MD5` is always verified, even alongside an `x-amz-checksum-*` header, and a mismatch answers `BadDigest`. * Gateway responses are never cached at the edge: a presigned URL stops working exactly when it expires, when the API key is revoked or when the file is deleted. * Keys can have up to about 1000 bytes. Past that, `KeyTooLongError` says the exact limit for your account. ## 🌐 Direct browser uploads * The new [`POST /v1/upload-tokens`](/en/blob-reference/endpoint/upload-tokens) mints, on your server, a short-lived **upload token** (`squp_...`) that the browser uses instead of the API key. * The token pins the name, prefix, visibility, expiry, maximum size, accepted extensions and metadata. It lasts from 1 to 60 minutes and 1 to 100 uses, and only works on upload routes. * Without a pinned name, the browser picks one and it always gets the security hash, so a leaked token can never replace existing files. ## ⚙️ Rules per prefix * The new [`PUT /v1/account/settings`](/en/blob-reference/endpoint/settings-put) saves your rules (5 on Hobby and Standard, 10 on Pro, 20 on Enterprise), each applying to the files under a prefix. * **Defaults:** visibility, expiry and cache. * **Limits:** maximum size and accepted extensions. * **Automatic deletion** after N days, which also applies to files that already existed and to files written over S3. It only starts acting **24 hours after** the rule is saved, so there is time to adjust a prefix that is too broad. ## 🧰 Server-side operations * **Batch updates** with [`PATCH /v1/objects`](/en/blob-reference/endpoint/update): visibility, expiry, cache, `Content-Disposition` and metadata of up to 50 files per request, with one result per file. * **Copy, move and rename** without downloading the file with [`POST /v1/objects/copy`](/en/blob-reference/endpoint/copy). * **File details** with [`GET /v1/objects/info`](/en/blob-reference/endpoint/info): type, ETag, expiry, cache, original name and metadata. * **Batch delete:** [`DELETE /v1/objects`](/en/blob-reference/endpoint/delete) accepts up to 100 files per request and reports what was deleted, what didn't exist and what failed. With a single id, the behavior is unchanged. ## 📤 Uploads * **Chunked uploads of up to 10 GiB**, with up to 2048 parts of 5 to 32 MB and up to 32 open uploads per account. * **Resume:** the new [`GET /v1/objects/chunked`](/en/blob-reference/endpoint/chunked-status) shows which parts already arrived, and [`GET /v1/objects/chunked/open`](/en/blob-reference/endpoint/chunked-open) lists the account's open uploads with the token of each. Uploads idle for 24 hours are aborted automatically. * **New upload parameters:** `private`, `overwrite`, `disposition`, `cache_control`, `metadata` and `checksum_sha256` (when the file doesn't match the checksum, the upload is refused with `CHECKSUM_MISMATCH` and nothing is stored). * **More flexible names:** 1 to 128 characters, accepting `.` and `-`, and prefixes up to 8 folders deep. * **Expiry in hours or days:** `6h`, `30` or `30d`. * The upload response includes the file's `sha256` and whether it replaced another file (`replaced`). ## 📋 Listing and metrics * [`GET /v1/objects`](/en/blob-reference/endpoint/list) gained a visibility filter (`private`), folders (`delimiter=/`), `limit` and the `cursor` parameter. Each entry carries `private`, `url` and `etag`, and the limit is now 30 requests per 30 seconds. * A malformed or outdated `cursor` answers `400 INVALID_CONTINUATION_TOKEN`: start again without it. * [`GET /v1/account/stats`](/en/blob-reference/endpoint/stats) shows this **month's average usage** (`month.average_storage`). * A public health check at `https://blob.squarecloud.dev/pub/status` answers `OK` and is never cached, ready for your monitoring. ## 💎 Features by plan Every plan gets the full API. A few options depend on the plan: | Feature | Plans | | - | - | | Rules per prefix | 5 on Hobby and Standard, 10 on Pro, 20 on Enterprise | | Custom metadata (up to 5 keys, 512 bytes) | Pro and Enterprise | | Password-protected share links | Pro and Enterprise | | Uploads without the 1-per-second limit | Pro and Enterprise | | Expiry and automatic deletion under 7 days (down to 1 hour) | Enterprise | | Files served without edge cache (`no-cache`) | Enterprise | Enterprise includes **250 GB** of storage. Rules saved before a downgrade keep applying, and the next change must fit the new plan. ## 🖥️ Blob in the dashboard The [Blob page](https://squarecloud.app/en/dashboard/blob) of the dashboard was rebuilt on top of the new API, in all 8 languages. * **File explorer** with grid and list views, folders, a visibility filter, sorting and multi-select. Bulk delete, visibility, expiry and move show progress and only retry the files that failed. * **Upload queue** with progress, cancel and resume, files of up to 10 GiB, and a choice of folder, visibility and expiry. Leaving the page while uploads run asks first. * **File details:** rename, move, copy, visibility, expiry, headers and metadata. Private previews only load when you ask. * **Share links and temporary links**, each window explaining the difference. Sharing a public file shows a warning with a one-click **Make private**, and deleting, moving or renaming a shared file warns that its links will stop working. * **Folder rules**, with a counter of how many your plan allows. * **S3 access** tab, which creates an API key for Blob and shows its S3 key pair. * Options that depend on the plan say which plan unlocks them. Accounts without an active plan can still view, delete and make files private. * The public [Blob Storage page](https://squarecloud.app/en/blob) was rebuilt around the new features, with a refreshed price comparison. Importing from a URL was removed from the upload window. ## 🧾 Activity feed * The [activity feed](https://squarecloud.app/en/dashboard/activity) was redesigned: days grouped in cards, times on the right and the IP on each row. * The first page covers the **last 24 hours**, and older activity loads as you scroll or click, up to your plan's history window (2 days on Standard, 7 on Pro and 30 on Enterprise). * Blob Storage actions have their own names in the feed: file updates, copies, share links created and revoked, upload tokens and rule changes. ## 🩺 One-click fixes for crashes When an application crashes with a known error, the console now shows **exactly what to change** and applies it for you: it edits the file, environment variable or configuration, restarts the application and watches the result. It says so when the fix worked, when the error came back or when the application didn't start. * Covers the most common crashes: npm install scripts blocked by `allowScripts` (with the ready `package.json` snippet), dependencies installed from Git, peer dependency conflicts, native binaries built for another system, a missing `MAIN` file, missing npm or pip packages, ES modules and Node.js versions, among others. * Only fixes it can prove: a module that is a file of your own project is never offered as a package to install, and edits made while the window is open are kept. * Every fix respects workspace permissions, and "Ask for help" hands the diagnosis to Cubic or support. * Changing custom domains too often now explains that you should wait about 30 minutes. ## ✨ Website and dashboard * The Product page became **[Features](https://squarecloud.app/en/features)**, and every service page was redesigned with fixed facts and clearer copy. The old address redirects. * The **[AI Gateway](https://squarecloud.app/en/dashboard/ai-gateway)** page got an animated diagram, a 3-step quickstart, real examples in JavaScript, Python and cURL, a limits table per plan and a table of error codes. * The **[Domains](https://squarecloud.app/en/dashboard/domains)** page lists each domain with its runtime and shortcuts to metrics and network settings, with search and an illustrated guide to connect a custom domain. * The **[Load Balancers](https://squarecloud.app/en/dashboard/loadbalancers)** page was rebuilt with a live traffic simulation, showing round-robin and failover between replicas. * **Pricing:** a plan chosen before signing in is kept after sign-in, pages only offer the plans that include the feature they describe, Hobby accounts see an upgrade card on databases instead of a paywall, and renewal no longer shows up when a saved card already renews the plan. * **Faster:** the sign-in button no longer waits for the CAPTCHA, Cubic streams answers with a fraction of the work, and the application overview spends far less time on live metrics. * Layout fixed down to 320 px wide in every language. ## 🛡️ API * **Network analytics:** cache misses of the [analytics](/en/api-reference/endpoint/apps/network/analytics), errors, logs and performance routes share one limit of **20 requests per minute** per owner, and cached responses don't count. When edge analytics are busy the routes answer `503 ANALYTICS_BUSY`, or return the most recent cached data for the window. * **Upload and commit:** the request body is capped at **101 MB** (a file of up to 100 MB plus the form), and a larger request is refused while it is still uploading. * **Protection against invalid keys:** an IP that insists on API keys that don't belong to any account is blocked for a few minutes. Valid keys in normal use are not affected. Details in [Authentication](/en/api-reference/authentication). * **AI Gateway:** the new `503 daily_capacity_reached` means the platform's shared daily capacity is used up until 00:00 UTC, different from your key's own `429 daily_spend_limit_reached`. See the [error table](/en/api-reference/ai-gateway). * The [OpenAPI document](/en/api-reference/openapi) no longer lists the routes that only work with a dashboard session, since they never accepted an API key. * **GitHub App with an API key:** [linking](/en/api-reference/endpoint/apps/deploy/github-app-link) and [unlinking](/en/api-reference/endpoint/apps/deploy/github-app-unlink) a repository through the Square Cloud GitHub App now work with an API key that has the `apps:deploy` scope, so the SDK methods for it no longer need a session token. Linking a repository that is not covered by an installation of your own GitHub account answers `403 REPOSITORY_NOT_AVAILABLE`. ## 📚 Documentation * The documentation has a new home page and a refreshed design, with new icons and diagrams. * New pages: [Errors](/en/blob-reference/errors), [S3 compatibility](/en/blob-reference/s3-compatibility), [Links and sharing](/en/blob-reference/links-and-sharing) and a page for every new route. * [Authentication](/en/blob-reference/authentication) shows which scope (`blob:read` or `blob:write`) each route needs. * Everything is available in the 8 languages of the documentation. ## 🎨 Redesigned dashboard, updated runtimes and more capacity This entry gathers everything shipped since the end of August that was not yet in this changelog. The dashboard was reviewed end to end, with configurable navigation and a full mobile pass. Restoring a snapshot now takes a single window. Every runtime and database moved to a new version, billing got clearer, and two new public clusters went live. **If you create databases through the API with a pinned full version, update the `version` field.** [`POST /v2/databases`](/en/api-reference/endpoint/databases/create) accepts the exact current version or a prefix of it. With the new images, a full version that is not the current one now returns `400 INVALID_DATABASE_VERSION`. Send only the major (`"8"`, `"17"`, `"9"`), which always resolves to the latest version of that major. For Redis, the major is now `8`. ## 🖥️ Dashboard ### Configurable navigation * **Navigation position:** left (default), right, top or bottom. The side positions also offer a **compact icon-only rail**, with each item's name on hover. * **Plan accent color** (Standard, Pro and Enterprise) on the navigation and dashboard details. On by default, and it can be turned off. * Set it under **Account → Interface** or from the account menu in the sidebar. The choice is saved on the device and applied before the page first paints, together with the theme, so nothing shifts after loading. * On phones, the top bar and bottom navigation stay the same in every position. * Switching between light and dark theme is now instant, and the CAPTCHA follows the theme. ### Full mobile pass * A swipe from the left edge opens the sidebar. * Inside an application, the top bar gained shortcuts to overview, logs, files and settings. * Larger touch targets on menus, selects, file manager actions, environment variables, DNS, logs, notifications, Blob and paginators. * Dialogs open as bottom sheets, the on-screen keyboard resizes the content instead of covering it, the save button sticks to the bottom, and iOS safe areas are respected across the dashboard and the website. * The plan memory bar and the renew and upgrade buttons fit on screen, and snapshot badges wrap instead of squeezing. * On desktop, the layout is unchanged. ### Loading, error and empty states * Every skeleton on the website and dashboard was audited, and each data-dependent block got its own error state. * The file tree, the application log list and the network logs were redesigned, with empty and error states that say why. * A newly created application shows a notice while its first metrics are collected. * Stripe card errors now come with guidance on the next step, and upload capacity messages are clearer. * When a repository download fails because the GitHub connection expired, the error notice itself offers **one-click reconnection**. On phones, an interrupted upload suggests checking your connection. ### Console and realtime * A console that had timed out from inactivity reconnects on its own when you start, stop or restart, complementing the automatic stream reconnection announced on September 5. * On applications that write a lot of logs, a tab that cannot keep up no longer piles up messages without limit, without affecting the status or other tabs. * Relative timestamps, such as "2 min ago", update on their own. * If a new dashboard version is published while your tab is open, the page recovers on its own instead of failing to load parts of the code. ### Performance Code is now loaded per route, dialogs and the paywall only on click, dashboard translations per section, and billing requests no longer block the initial load. ### Other fixes * Workspace quick actions open the correct application again. * Renewal invoices show up in the notification bell, and upgrade buttons no longer preselect the yearly cycle. * In the activity feed, a batch cache purge done by Cubic shows up as a single row, with the details of each application. * The PostgreSQL recommendation when creating a MySQL database is more concrete, with one-click creation. * The button to resend the sign-in code by email works again. * The GitHub connection is more stable. * Discord role sync waits out Discord's rate limit instead of failing. ## 🗂️ Snapshots * **Restore in a single window**, the same on the account snapshots page and on each application and database page: snapshot summary, target choice (with the origin preselected) and a confirm button that names the target. On an application or database page, the target is fixed and the choice does not appear. If the origin no longer exists, nothing is preselected. * **Create a new database during the restore:** the dashboard creates the database, waits until it is running, restores, and shows the connection URL once, at the end. If the creation fails, the form comes back filled in. If the restore fails after the creation, the retry goes straight to the newly created database. * **Origin and runtime** appear on each row (see the September 17 API change), and the downloaded file name carries the same suffixes. Daily automatic snapshots and those taken when a plan expires are now tagged too. * Restores of large snapshots now get up to 5 minutes to extract their files. * The [Snapshots](https://squarecloud.app/en/resources/snapshots) page now describes retention: each daily snapshot stays available for 7 days, and the most recent one is kept for up to 30 days. ## 🌐 Domains * When setting up a custom domain, the dashboard shows the exact value to add at your DNS provider, ready to copy. * **Accented domains (IDN):** a hostname such as `gestão.site.com` is normalized in the browser (scheme, path, port and trailing dot removed) and converted to Punycode, and only the ASCII form (`xn--gesto-dra.site.com`) reaches the API. The dashboard shows how the domain was saved and displays the readable form in the application header, in Domains and in Load Balancers. Links and DNS records stay in ASCII. * Through the API, [`POST /v2/apps/{app_id}/network/custom`](/en/api-reference/endpoint/apps/network/custom) still expects the hostname in ASCII: convert accented domains to Punycode before sending. ## 💳 Plans and billing ### Downgrade * The flow starts with the reason (cost, low usage, pausing or other) and shows a side-by-side comparison of the plans with prices, what changes, what stays the same, how long you have already paid for, and what the yearly cycle of your current plan would cost. * A downgrade swaps the plan **keeping your current expiry date, with no prorated credit for the difference**. The [pricing](https://squarecloud.app/en/pricing) FAQ describes the rule in all 8 languages and points to **Account → Billing**, where the downgrade is made. * The button is blocked when the account uses more than the lower plan allows: allocated RAM above its limit, custom domains or workspaces the lower plan does not include, or databases without permission. Blob usage above the lower plan's quota only shows a warning. ### Renewal * **Ready-to-pay renewal PIX:** accounts without a saved card receive, when entering the renewal window (3 days before expiry) and again in the last 6 hours, an email with the **QR code in the message itself** and the copy-and-paste code. It is the same charge in both emails and on the invoice page, valid until the end of the plan. * **Expiry reminders** at 14 and 7 days for every account with an active plan. For monthly renewers, the 14-day reminder shows the comparison with the yearly cycle. * **After expiry**, reminders at 3 and 21 days. * **Receipt for renewals after expiry:** a payment that reactivates an expired account generates its own receipt, which explains how to restore your applications from the snapshots taken at expiry. ### Emails * **Plan welcome**, sent a few minutes after the first purchase or a plan step-up (Hobby → Standard → Pro → Enterprise), introducing what the new plan unlocks. * **Plan full notice:** when applications and databases already allocate 95% or more of the plan's RAM, the account receives a suggestion of the next plan, at most once every 30 days. * **Open invoice:** a reminder shortly after creation and a follow-up after 24 hours, if the payment has not happened yet. * Every platform email, including sign-in emails, was rewritten in all 8 languages on a new layout, with the reason for the email in the footer. Sign-in code emails state how long the code is valid and include "Was it you?" and "Wasn't you?" shortcuts for account security. ## 🤖 Cubic * **Guidance mode for accounts without an active plan:** Cubic answers questions about the platform, hosting and development by looking up the platform knowledge base, service status and the web. Each message accepts up to 2,000 characters, with no image attachments and a budget of 500K tokens per day (reset at 00:00 UTC). Actions on applications remain exclusive to accounts with an active plan. * **Batch cache purge:** Cubic purges the cache of up to 50 applications at once and reports, per application, what was not found or has no domain. * **More reliable on long file tasks**, with fewer interruptions in the middle of an edit. * **Knowledge base reviewed** against the documentation: a custom domain is always your own domain, pointed with the three DNS records, and Cubic cites more pages of these docs. * Cubic got a pixel art mascot, which shows up on paginators, empty lists and error screens. ## 📡 Capacity Two new public clusters, **Iara** and **Rigel**, joined the placement of new deploys. ## ⚙️ Containers * **Memory limit without swap:** containers created from now on use only the RAM you allocated. On reaching the limit, the process is terminated (OOM) instead of staying slow with memory stuck at the ceiling. Existing containers follow the rule on their next RAM change. * **Maintenance without interrupting operations:** deploys, commits, restores, database creation and snapshots in progress finish before maintenance starts. ## 📦 Runtimes and databases The new versions apply to deploys made from now on. The `VERSION` field of the [configuration file](/en/getting-started/config-file) still chooses between `recommended` and `latest`. | Runtime | Before | Now | | - | - | - | | Node.js \[JS & TS] (`recommended`) | `24.15.0` | `24.21.0` | | Node.js \[JS & TS] (`latest`) | `26.1.0` | `26.9.0` | | Python (`recommended`) | `3.13.13` | `3.14.7` | | Python (`latest`) | `3.14.5` | `3.14.7` | | Go | `1.26.3` | `1.27.1` | | Rust | `1.95.0` | `1.98.1` | | PHP | `8.5.6` | `8.5.10` | | Ruby | `4.0.4` | `4.0.7` | | .NET/C# | `10.0.8` | `10.0.12` | | Elixir | `1.19.5` | `1.20.4` | | Java | JDK `25` | JDK `25.0.4` | The `recommended` Python version moved from 3.13 to 3.14. If a dependency of your project does not publish packages for Python 3.14 yet, check compatibility before your next deploy. The images still ship ffmpeg, Chromium and the build libraries used by native packages. | Database | Version | | - | - | | MongoDB | `8.3.11` | | PostgreSQL | `17.11` | | MySQL | `9.7.2` | | Redis | `8.8.3` | The new versions apply to databases created from now on; existing databases stay on the version they were created with. All of them keep TLS connections, and Redis 8.8.3 includes the JSON, Search (`FT.*`), TimeSeries (`TS.*`), probabilistic (`BF.*`, `CF.*`, `TDIGEST.*`) and Vector Sets modules. ## ✨ Website * **New [Features](https://squarecloud.app/en/features) page:** an overview of the platform in seven categories (deploy, network, scale, observe, storage, automate and trust). The "Services" header menu became "Features". * **New pages:** [APIs and backends](https://squarecloud.app/en/apis), [SaaS](https://squarecloud.app/en/saas) and [Domains](https://squarecloud.app/en/resources/domains). * Every `/resources` page was redesigned and got its own illustrations. * The [support center](https://squarecloud.app/en/support) was redesigned with Cubic as the first line of help, and the status button takes signed-in users straight to the status page in the dashboard. * The [Enterprise](https://squarecloud.app/en/enterprise) page got a new contact section, and the Enterprise checkout now stacks on phones. ## 📦 Snapshots know their runtime and origin Every snapshot listing (`GET /v2/apps/{app_id}/snapshots`, `GET /v2/databases/{database_id}/snapshots` and `GET /v2/users/snapshots`) now carries two extra fields per entry: | Field | Values | Meaning | | - | - | - | | `runtime` | the application's language (`javascript`, `python`, ...) or the database engine (`mongo`, `mysql`, `postgres`, `redis`) | What the snapshot was taken from. | | `origin` | `manual` or `automatic` | Whether it was requested (API, dashboard, CLI) or taken by the daily schedule. | Both are `null` on snapshots taken before this change. The `name` of a new snapshot carries the same information as suffixes (`__`), so the download URL format is unchanged. The restore endpoints (`POST .../snapshots/restore`) accept the `name` exactly as the listing returns it: pass it through unchanged as `snapshotId`. ## 🧭 Clearer error codes A handful of endpoints answered some failures with a bare `{ "status": "error" }` and no code, or with a `400` for something that was really "not found". Those cases now carry a code and the right HTTP status. Nothing was renamed: every code below already existed in the API's vocabulary and in the SDK types. ### Workspaces | Endpoint | Before | Now | | - | - | - | | `DELETE /v2/workspaces` | `400` with no code when the workspace was already gone | `404 WORKSPACE_NOT_FOUND` | | `POST` / `DELETE /v2/workspaces/applications` | `400` with no code when the workspace vanished mid-request | `404 WORKSPACE_NOT_FOUND` | | `POST /v2/workspaces/members` | `400` with no code when the workspace vanished mid-request | `404 WORKSPACE_NOT_FOUND` | | `PATCH` / `DELETE /v2/workspaces/members` | `400` with no code when the member had already left | `404 MEMBER_NOT_FOUND` | `INVALID_ID` (`400`) is unchanged, but it is now answered before anything else runs, so a malformed `workspaceId` no longer counts against the endpoint's rate limit. ### Files, logs, cache and deploys | Endpoint | Change | | - | - | | `PUT /v2/apps/{app_id}/files` | `content` officially accepts three shapes: a UTF-8 string, a plain array of byte values (`[]` writes an empty file) or a `{ type: "Buffer", data }` object. Content over **10 MB** is refused with `413 FILE_TOO_LARGE`; writes are limited to **10 per 5 seconds** per user (`429 KEEP_CALM`). | | `GET /v2/apps/{app_id}/logs` | The `404` now carries `LOGS_UNAVAILABLE` (or the application's own reason) instead of no code. | | `POST /v2/apps/{app_id}/network/purge_cache` | A failed purge answers `500 PURGE_CACHE_FAILED` instead of no code. | | `POST /v2/apps` and `POST /v2/apps/{app_id}/commit` | When too many uploads are being processed at once, the API answers `503 UPLOAD_BUSY` instead of failing the upload. Just retry in a moment. | ### Two codes any endpoint can return | Code | HTTP | Meaning | | - | - | - | | `KEEP_CALM` | 429 | The endpoint's rate limit was exceeded; wait and retry. | | `DATABASE_UNAVAILABLE` | 503 | The service is briefly unavailable; retry in a few seconds. Existing applications and databases are **never** reported as not found in this state. | ### Dashboard * The application console now reconnects on its own whenever the live stream drops, instead of staying disconnected until you click reconnect. * Removing a member or an application that was already removed elsewhere simply refreshes the list. ## 🗞️ Other updates ### 🤝 New partner program We are introducing a new, fully public partner program. Learn more and apply at [squarecloud.app/partners](https://squarecloud.app/partners). ### 🤖 Cubic and the AI Gateway on a new AI infrastructure In late August we migrated Square Cloud's entire AI layer to a new infrastructure, focused on faster responses, more stability and more generous limits. ZDR, our full privacy policy and zero logs are unchanged. **Cubic (the dashboard assistant)** * **Faster answers.** The first token arrives in about 2 seconds even in long conversations; the tens-of-seconds wait before a reply started is gone. * **No queue.** Capacity scales per request: the "AI at maximum capacity" message no longer exists. If a model provider fails, Cubic switches to another one automatically. * **Images with more formats and more memory.** Besides JPEG and PNG, Cubic accepts WebP. Attached images go through a dedicated analysis that transcribes text, errors and visible details, and that description stays in the conversation for later messages. * **Faster web search**, with results in about 1 second. **Voice transcription** remains on every plan, with the same 5-second to 2-minute window. * **New daily token limits per plan** (reset at 00:00 UTC): Hobby 2M; Standard 5M (4 GB), 7M (6 GB) and 10M (8 GB); Pro 15M; Enterprise unchanged. The unlimited-usage period has ended; usage counts against the plan's daily budget, visible in the chat's usage bar. **AI Gateway (OpenAI-compatible API)** * Routed by the same engine as Cubic, with the same drop in latency. * New limits per plan: * **Standard:** 1,000 requests per day, base fair-use allowance, 16,384-token context, up to 4,096 output tokens, 1 concurrent request, a minimum 5s interval (was 4s). * **Pro:** 5,000 requests per day, base allowance, 24,576-token context, up to 6,144 output tokens, 1 concurrent request, 2s interval. * **Enterprise:** unlimited requests, 5x the base allowance, 32,768-token context, up to 8,192 output tokens, 2 concurrent requests, no interval. * New 429 codes in the OpenAI format: `daily_request_limit_reached` (daily request ceiling) and `daily_spend_limit_reached` (daily fair-use allowance). Both reset at 00:00 UTC. * Still no streaming and no images; the built-in `web_search` keeps working. **About the permitted use of the AI Gateway.** The AI Gateway is a beta product and is currently **completely free**, offered as a courtesy to the Standard, Pro and Enterprise plans so you can add AI to your own projects hosted on Square Cloud. **Reselling, relaying or exposing the AI Gateway for mass third-party use is not allowed** (offering the API to other users, feeding third-party AI services, or distributing access through a single plan). We identified this kind of activity consuming most of the capacity; the new limits and the fair-use allowance exist to stop exactly that, and a project with normal usage is unlikely to get anywhere near them. Accounts that keep this pattern may have their AI Gateway access suspended. Full details in the [AI Gateway documentation](/en/api-reference/ai-gateway). ## 🔑 Up to 10 scoped API keys per account Your account used to have **one** API key, with access to everything: deploys, files, environment variables, databases and object storage. If a CI pipeline, a third-party script or any tool needed access, that was the key you handed over. Now you create **up to 10 named keys** from your account settings, and each one carries two independent axes: **what** it can do, and **where** it can act. **Your existing key keeps working and needs no action from you.** The token format did not change, so nothing you already have integrated broke. It now appears in your key list like any other, with its last-use timestamp and a revoke button. The secret of a new key is shown **exactly once** and is never readable again. Keys are stored as an irreversible hash. ### The 18 permissions | Scope | Grants | | - | - | | `account:read` | Read your account data | | `apps:read` | List applications, read status, logs and metrics | | `apps:control` | Start, stop and restart | | `apps:write` | Edit application configuration | | `apps:deploy` | Ship new code | | `files:read` | Browse and read the file tree | | `files:write` | Create, edit and delete files | | `envs:read` | Read environment variables | | `envs:write` | Create and change environment variables | | `snapshots:read` | List and download backups | | `snapshots:write` | Generate and restore backups | | `databases:read` | List databases and read status | | `databases:write` | Create, alter and delete databases | | `databases:credentials` | View and rotate database credentials | | `workspaces:manage` | Manage workspaces and members | | `ai:chat` | Use the AI Gateway | | `blob:read` | List and download objects | | `blob:write` | Upload and delete objects | Pass exactly `["*"]` for full access, which also covers scopes added in the future. Some scopes are broader than their name suggests. `files:write` and `apps:deploy` amount to arbitrary code execution in your container, `snapshots:read` returns the whole application **with its environment variables inside**, `databases:credentials` is your database password, and `workspaces:manage` grants access to **other accounts** in a way that survives revoking the key. Request the minimum. ### Restricting a key to specific resources `resources` takes application and database ids. A CI key that only sees the project of that pipeline exists, works, and simply cannot reach the rest of your account. Omit it for whole-account access. `resources` **cannot be combined with `blob:read`/`blob:write`** (nor with `["*"]`, which includes them), and the request answers `CONFLICTING_RESOURCES`. Object storage belongs to the account and no object carries an application id, so the restriction would have nothing to apply to there. Create one key for the applications and another for object storage. ### New error codes | Code | HTTP | Meaning | | - | - | - | | `MISSING_SCOPE` | 403 | The key lacks the scope this route requires | | `RESOURCE_NOT_ALLOWED` | 403 | The key is restricted to resources that do not cover this request | | `CONFLICTING_RESOURCES` | 400 | `resources` was combined with a blob scope or `["*"]` | | `APIKEY_LIMIT_REACHED` | 400 | The account is at 10 live keys | ## 💻 Connect the VS Code extension without pasting your key The VS Code extension now requests authorization **as an application**, instead of asking you to paste your account key into a text field. The extension opens a request, shows an 8-character code on screen, and you type that code in the dashboard to approve. What it receives is a **key of its own**: minimum scope, valid for 90 days, and listed alongside your other keys so you can revoke it whenever you want. The 8-character code exists only on the extension's screen: it never travels in the link and no endpoint returns it. An authorization link that reached you through any other channel will not work without it. After connecting, the extension shows which account it was bound to — check it. The authorization is bound to the extension that started it, so a request intercepted along the way cannot be completed by anything else. ## 👥 More workspaces The cap went up: **5 workspaces** on Standard and **10** on Pro and Enterprise. ## 🤖 AI Gateway (Beta): use Square Cloud's AI in your own apps You can now use Square Cloud's hosted AI model inside your **own** products — chatbots, assistants, automations — through the new **AI Gateway**, an **OpenAI-compatible** chat completions API. If your code already speaks the OpenAI API, no rewrite is needed: point the SDK at our base URL, use your account API key, and set the model to `cubic`. ```javascript theme={"system"} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.squarecloud.app/v2/ai", apiKey: process.env.SQUARECLOUD_API_KEY, }); const completion = await client.chat.completions.create({ model: "cubic", messages: [{ role: "user", content: "Hello!" }], }); ``` * **Works with any OpenAI SDK** (JavaScript, Python, or plain HTTPS) at `POST /v2/ai/chat/completions`. * **Built-in web search**: the model searches the web on its own when the conversation needs current information, citing result URLs in the answer. * **Function calling** in the standard OpenAI format, with up to 32 tool definitions per request. * **Per-plan limits**: Standard gets a 16,384-token context and 4,096-token output; Pro raises it to 24,576/6,144; Enterprise to 32,768/8,192 with 2 concurrent requests. Every request bills its real tokens against the plan's **daily AI token budget** — the same one the dashboard AI assistant uses (reset at 00:00 UTC). * **Beta with free early access**: during the beta there is no extra charge beyond your plan's daily AI token budget. Available on Standard plans and above. See the full [AI Gateway reference](/en/api-reference/ai-gateway) for the request contract, error codes and examples. ## 📋 Blob Storage actions in the account activity feed The account activity feed (available on Standard plans and above) now lists **Blob Storage actions** alongside your application actions: uploads, deletions, and chunked uploads being started, completed or aborted — each with the source IP, user agent and authentication type. Individual chunk parts are deliberately left out, so a large chunked upload shows up as clean start/complete events instead of hundreds of rows. ## 📦 1 GiB uploads from the dashboard Following the chunked upload flow released on July 31, the dashboard's Blob page now uses it automatically: files above 100 MB (up to **1 GiB**) upload in chunks, with real byte-level progress and a cancel button for in-flight uploads. ## 📦 Blob Storage: 1 GiB uploads, any file type, friendlier limits The Blob Storage API gained a chunked upload flow that raises the maximum object size from 100 MB to **1 GiB**, dropped the MIME allowlist in favor of accepting practically any file type, and had its rate limits retuned so bursts of normal usage no longer trigger long lockouts. ### ⬆️ Chunked uploads up to 1 GiB `POST /v1/objects` is unchanged and still caps a single request at 100 MB (the largest body Cloudflare's edge accepts). Files above that now go through a four-step flow on `/v1/objects/chunked`: 1. [Open the upload](/en/blob-reference/endpoint/chunked-init) (`POST`) and receive an opaque `upload` token plus the chunk limits. 2. [Send each chunk](/en/blob-reference/endpoint/chunked-part) (`PUT`) as a raw body of 5 to 32 MB, in any order, up to 6 in parallel; a failed part can simply be re-sent. 3. [Complete](/en/blob-reference/endpoint/chunked-complete) (`PATCH`) with just the token: the part list is read back from storage, so the client never tracks ETags. 4. [Abort](/en/blob-reference/endpoint/chunked-abort) (`DELETE`) to cancel and free the stored chunks (idempotent, and recommended whenever the user gives up). There is no server-side session: the token is the whole upload state, so uploads survive page reloads, and each account can keep up to 8 uploads open at once. If the account's quota fills up while parts are uploading, completion fails with `STORAGE_QUOTA_EXCEEDED` but the upload is left open, so you can free space and retry instead of re-uploading the whole file. ### 📁 Any file type accepted The MIME allowlist is gone. The stored extension now comes from the **filename you send**, so formats with no registered MIME type (`.bam`, `.vcf`, `.fasta`, `.fastq`, `.parquet`, `.h5`, `.npy` and so on) upload just fine, and compound compression suffixes are preserved (`reads.fastq.gz` stays `.fastq.gz`). Unknown formats are served as `application/octet-stream`, browser-renderable formats (`.html`, `.svg`, `.xml`) keep being forced to download, and only executables/installers are refused, with the new `BLOCKED_FILE_TYPE` code. ### ⚙️ Retuned limits * **Expiration range is now 7 to 1825 days** (5 years). Values below 7 days are rejected with `INVALID_OBJECT_EXPIRE`; update any preset shorter than a week. * **Minimum file size dropped from 1 KB to 512 bytes.** * \*\*Storage overage now costs R$ 0.20 per started GiB** (was R$ 0.25). * **Rate-limit blocks now expire with their window** instead of punishing bursts: object deletes went from 1 per second to 10 per 10 seconds, listing overruns block for 30 seconds instead of 5 minutes, stats overruns for 60 seconds instead of 5 minutes, and the chunked routes allow parallel opens, completes and cancels. * Chunk sending is exempt from the account-wide API budget, so a long upload cannot exhaust your API quota for the rest of the platform. See the updated [Blob Reference](/en/blob-reference/authentication) for the full contract, including the new error codes (`TOO_MANY_OPEN_UPLOADS`, `TOO_MANY_CONCURRENT_CHUNKS`, `INVALID_UPLOAD_TOKEN`, `INVALID_CHUNK_PART`, `CHUNK_TOO_LARGE`, `CHUNK_TOO_SMALL`, `EMPTY_CHUNK`, `NO_CHUNKS_UPLOADED`, `UPLOAD_NOT_FOUND`). ## 🚀 Load Balancers, CLI v3 and a new generation of SDKs This is one of the largest tooling waves we have ever shipped at once: a brand new **Load Balancer** capability for custom domains, the official CLI at **v3** with full platform parity, and new releases across **every official SDK**: JavaScript v5, Go v2, Blob v2, Python v4.1 and API Types v3. The public API and the Blob Storage API also gained new endpoints and richer responses, and the documentation you are reading is now fully available in 8 languages. ### ⚖️ Load Balancers: one domain, multiple applications You can now attach the **same custom domain to more than one application**. Traffic is balanced across the applications at the edge, with **automatic failover**: if one application goes offline, requests keep flowing to the healthy ones. * Per-plan capacity for applications sharing one domain: **2 on Standard, 5 on Pro and 10 on Enterprise** (going over it returns `LOAD_BALANCER_LIMIT_REACHED`). * Inspect your balancers through the API (`GET /v2/apps/load-balancers`), the SDKs, or the CLI (`squarecloud app load-balancers`). * The new `GET /v2/apps/domains` endpoint complements it by listing every domain configured across your applications in one call. ### ⌨️ Square Cloud CLI v3 The CLI went from exposing a small slice of the platform to **full parity** with it. Everything you can do in the dashboard, you can now do from the terminal. See the updated [CLI reference](/en/cli-reference/installation) for every command. * **Platform health:** `squarecloud status` shows the health of Square Cloud services. * **Deep application tooling:** `app info`, `app metrics` (last 24 hours of CPU, RAM, and network), `app realtime` (live event stream, Ctrl+C to exit), `app domains`, `app load-balancers`, `app status --all`, and `commit --path` to commit a subdirectory. * **Environment variables:** `app env list/set/remove/replace`, including bulk import with `--from-file .env`. * **Remote file manager:** `app file list/read/write/move/delete` straight from the terminal. * **Deploys and Git:** `app deploy list/current/webhook`, plus GitHub App `link`/`unlink`. * **Network suite:** `app network dns/domain/analytics/errors/logs/performance/purge-cache`, with analytics filters and custom time ranges. * **Snapshot restore:** both `app snapshot restore` and `db snapshot restore`. * **Complete `db` tree:** list, create, info, update, delete, start/stop, status, metrics, credentials (certificate and rotation), and snapshots. * **Complete `workspace` tree:** create, manage members and roles, share applications, and generate invite codes. * **Better UX everywhere:** a global `--json` flag for scripting, optional app/database IDs (resolved from the `squarecloud.app` config file or an interactive picker), y/N confirmation on every destructive action with `-y` to skip, Ctrl+C cancels in-flight requests, and `SQUARECLOUD_DEBUG=1` for request-level debugging. * **Fixes that matter:** authentication failures now exit with code 1, the application picker no longer hides API errors, and editing the `squarecloud.app` config file preserves your existing keys. ### 📦 A new generation of SDKs Every official SDK shipped a new release in this wave, all aligned with the same current API contract. **JavaScript SDK v5 (`@squarecloud/api`)** — see the updated [SDK reference](/en/sdks/js/client) and the [v4 → v5 migration guide](/en/sdks/js/migrating_to_v5): * The snapshots transition is complete: the old backup classes and methods were removed in favor of `Snapshot`/`DatabaseSnapshot`. * New `domains()` and `loadBalancers()` account modules, richer `create()`/upload results (language name and version, CPU, description, subdomain), and `dns()` returning the actual record list with per-record status. * Analytics with **11 drill-down filters** and **4 new breakdowns** (IPs, status codes, bots and content types). * The `APIErrorCode` export follows the standardized error codes, keeping the old names as deprecated aliases so existing comparisons keep working. **Go SDK v2 (`sdk-api-go`)** — rewritten from scratch, now covering the **entire Square Cloud API** with zero external dependencies: * Applications (metrics, realtime SSE stream, snapshots with restore, file manager, environment variables, deploys with GitHub App integration, DNS, analytics and the network suite), a complete databases interface, a complete workspaces interface, and platform status. * Machine-readable errors: failures return `*rest.APIError` with the HTTP status and the public error code (for example `APP_NOT_FOUND`), plus the `rest.ErrorCode(err)` and `rest.IsRateLimit(err)` helpers. * Real context support (`rest.WithContext(ctx)` propagates cancellation and deadlines) and the new module path `github.com/squarecloudofc/sdk-api-go/v2`. **Python SDK v4.1 (`squarecloud-api`)** — a big feature sync: * Application and database **metrics** (last 24 hours), **realtime** status streaming over SSE, GitHub App deploy `link`/`unlink`, and database snapshot list/create. * Edge network suite for websites: errors, logs, performance and cache purge, plus domain analytics with the full set of drill-down filters and custom time windows. * Account-level calls: platform status, user snapshots, domains and load balancers. **Blob SDK v2 (`@squarecloud/blob`)** — synced with the current Blob Storage contract: * Paginated listing via `continuationToken`, and `objects.delete` now accepts the object's public URL directly. * Uploads are validated client-side (name, size, expiration and MIME type) and queued to respect the concurrency limit, with automatic retry when the service is busy. * Errors now expose the machine-readable `error.code`, following the standardized error codes. **API Types v3 (`@squarecloud/api-types`)** — the canonical TypeScript contract, fully synced: * Types for the new domains and load balancer endpoints, the analytics filters and breakdowns, raw status variants, and the `APIErrorCode` union with the pre-standardization names kept as deprecated aliases. ### 🔌 Public API and Blob Storage improvements * **New endpoints:** `GET /v2/apps/domains` (every domain across your applications) and `GET /v2/apps/load-balancers`. * **Deeper analytics:** the domain analytics endpoint now accepts 11 drill-down filters (`country`, `ip`, `path`, `status`, `os`, `browser`, `protocol`, `referer`, `provider`, `content_type`, `bot`) applied to every breakdown at once, and returns 4 new breakdowns: IPs, status codes, bots and content types. * **The SDKs caught up with the full contract:** capabilities the API already offered are now first-class across the official SDKs and typings, such as creating a database with just the engine's major version (for example `"8"`), committing into a subdirectory via the `path` query parameter, raw status variants with `rawData=true` and the ruby runtime. * **Blob Storage:** paginated object listing via a continuation token and the standardized machine-readable error codes are now exposed end to end through the Blob SDK v2. ### 🛡️ Platform and account improvements * **Stay signed in, safely:** sessions now renew automatically while you use the platform, so active users are not asked to log in again; idle sessions expire sooner, which tightens security without getting in your way. * **Reinforced card security:** we extended the bank's 3DS authentication to more card charges for extra protection against fraud, and when the bank requires an action you receive a clear e-mail to complete the payment. * **Brazilian invoices (NFSe):** service invoices are now issued with complete fiscal data (company name, CPF/CNPJ and address), and you can set your CNPJ directly in the dashboard. When your NFSe is available, you automatically receive a personalized e-mail with a breakdown explaining what the invoice is and what it covers. * **Proactive RAM alerts:** if an application stays close to its allocated memory limit, the owner receives an e-mail warning before it becomes a problem. * **More stable long-lived connections at the edge:** realtime streams (SSE) and WebSockets no longer drop on long sessions, and the edge error pages were redesigned with proper localization. * **Smarter renewal reminders:** expiry notices now understand when automatic renewal is handling your cycle, and the transactional e-mails were revised in all 8 languages. ### 📚 Documentation, now in 8 languages * The documentation is now fully available in **English, Portuguese, Spanish, French, German, Italian, Japanese and Simplified Chinese**. * The **API reference** was enriched endpoint by endpoint with unique explanations, examples and per-route error tables. * The **CLI reference** was rebuilt for v3 (every command documented), the **JavaScript SDK** section was updated for v5 with a dedicated migration guide, and the **Blob Storage reference** was audited against the live service. ### 📊 Quick version summary | Product | Version | Main highlight | | - | - | - | | Load Balancers | new | One custom domain served by multiple applications, with automatic failover | | Square Cloud CLI | **v3** | Full platform parity: databases, workspaces, file manager, env vars, deploys, network suite, and `--json` everywhere | | JavaScript SDK | **v5** | Snapshots naming completed, domains and load balancers, deeper analytics, standardized error codes | | Go SDK | **v2** | Complete rewrite with full API coverage, typed errors, and zero dependencies | | Python SDK | **v4.1** | Metrics, realtime SSE, GitHub App deploys, edge network suite, database snapshots | | Blob SDK | **v2** | Pagination, typed error codes, client-side validation, smarter uploads | | API Types | **v3** | Full sync with the current API contract, `APIErrorCode` with deprecated aliases | ## 🧹 Standardized error codes across the API and Blob Storage We renamed a batch of error codes in the Square Cloud API and the Blob Storage API to follow a single, predictable convention: `INVALID_X`, `X_NOT_FOUND`, `X_FAILED` and `X_LIMIT_REACHED`. If your integration matches on error codes, update it to the new names below. ### API — renamed codes | Old code | New code | | - | - | | `ID_INVALID` | `INVALID_ID` | | `CODE_INVALID` | `INVALID_CODE` | | `NAME_INVALID` | `INVALID_NAME` | | `MEMORY_INVALID` | `INVALID_MEMORY` | | `DATABASE_TYPE_INVALID` | `INVALID_DATABASE_TYPE` | | `DATABASE_VERSION_INVALID` | `INVALID_DATABASE_VERSION` | | `UNKNOWN_WORKSPACE` | `WORKSPACE_NOT_FOUND` | | `UNKNOWN_MEMBER` | `MEMBER_NOT_FOUND` | | `MAX_APPLICATIONS_REACHED` | `APPLICATIONS_LIMIT_REACHED` | | `MAX_MEMBERS_REACHED` | `MEMBERS_LIMIT_REACHED` | | `FAILED_WORKSPACE_CREATION` | `WORKSPACE_CREATION_FAILED` | | `FAILED_DATABASE_CREATION` | `DATABASE_CREATION_FAILED` | | `FAILED_CLUSTER_SELECTION` | `CLUSTER_SELECTION_FAILED` | | `FEW_MEMORY` | `INSUFFICIENT_MEMORY` | | `FAILED_READ` | `READ_FAILED` | | `FAILED_DELETE` | `DELETE_FAILED` | | `FAILED_RENAME` | `RENAME_FAILED` | | `FAILED_TO_SAVE` | `SAVE_FAILED` | | `FAILED_RESET` | `RESET_FAILED` | | `FAILED_UPLOAD` | `UPLOAD_FAILED` | | `FAILED_UPLOAD_DATA` | `STORAGE_UPLOAD_FAILED` | | `DELETE_ERROR` | `DELETE_FAILED` | | `COMMIT_ERROR` | `COMMIT_FAILED` | | `INTERNAL_ERROR` | `INTERNAL_SERVER_ERROR` | | `REGEX_VALIDATION` | `INVALID_DOMAIN` | | `CAN_NOT_SET_SUBDOMAIN` | `CANNOT_SET_SUBDOMAIN` | | `INVALID_APP` | `METRICS_NOT_SUPPORTED` | | `SUBSCRIPTION_REQUIRED` | `UPGRADE_REQUIRED` | Notes: `INVALID_APP` was renamed only on `GET /v2/apps/{app_id}/metrics` (it signals that applications under 512 MB of RAM do not collect metrics). `KEEP_CALM`, the short-lived rate-limit code of the main API, keeps its name. ### Blob Storage — renamed codes | Old code | New code | | - | - | | `RATELIMIT` | `RATE_LIMITED` | | `ACCESS_DENIED` | `PERMISSION_DENIED` | | `FAILED_DELETE` | `DELETE_FAILED` | | `FAILED_LIST` | `LIST_FAILED` | | `INVALID_FILETYPE` | `INVALID_FILE_TYPE` | | `PAYLOAD_TOO_LARGE` | `FILE_TOO_LARGE` | Notes: the authentication `ACCESS_DENIED` (401 for a missing or invalid API key) is unchanged; only the active-plan gate on object upload now returns `PERMISSION_DENIED`. `FILE_TOO_LARGE` replaces `PAYLOAD_TOO_LARGE` on the object upload 413 (100 MB cap). ## 🌍 8 languages, a faster dashboard, smarter renewals, and improvements across the platform! Since the last changelog, we focused this window on two goals: making Square Cloud truly yours anywhere in the world, and making day-to-day use faster and smoother. The big highlight is the arrival of **four new languages** — now **eight** — covering the website, the dashboard, your account emails, and the sign-in flow. Alongside it comes an extensive round of performance, billing, integration, and experience improvements. ### 🌍 Square Cloud now speaks 8 languages The platform gained **four new languages**: **Japanese (日本語), French (Français), German (Deutsch), and Italian (Italiano)**, joining Portuguese, English, Spanish, and Chinese — for a total of **eight languages**. * **Full coverage:** the translation spans the **entire website, the dashboard, your account emails, and the whole sign-in flow**, for a consistent end-to-end experience. * **A language that follows you:** your language preference now **persists across sessions** and stays in sync when you switch languages. ### ⚡ Faster, from the cluster to the dashboard We invested in end-to-end performance — from the platform core to your browser — so everything responds faster, on any connection. * **Cluster \~2x faster:** deep optimizations in the platform core made communication with your apps and containers about **2x snappier**. * **Modernized to React 19** with deferred loading of heavy chunks (charts, payments, animations), speeding up page loads. * **Images and assets \~59% smaller** after a full recompression of the site. * **Faster marketing pages** via prerendering, preconnect, and trimmed translation payloads. * **Smoother scrolling**, with a less janky header and fewer re-renders in background animations. * **Improved PWA:** correct theme color, maskable icon, iOS standalone support, and a smoother sign-in flow in the installed app. ### 🎨 What's new in the dashboard * **Bulk file upload** in the file manager, with automatic compression and validation. * **Redeem history:** a new **redeemed gift codes** section in your account, plus a redesigned redeem page with FAQ and "how it works" sections. * **Auto-renewal, rethought:** setting it up takes seconds — save a card and your plan renews on its own, with the next charge's status always clear and visible in the dashboard. Less friction to set up, and peace of mind around expiry. * **Smart PostgreSQL suggestion** when creating a MySQL database, helping you pick the right tool for the job. * **Snapshot experience:** cooldown and processing feedback modals, and dark/light theme file previews. * **Google account connection** suggested directly in your notifications. * **Clearer file-content modal**, with save support. ### 🤝 A more integrated Discord * **Roles always up to date:** when you sign in with Discord, your account **automatically rejoins the Square Cloud server and re-syncs your roles**, keeping your access correct even if something drifted. * **More reliable sign-in:** linking and signing in with Discord became more robust, with better error handling and automatic retries. ### 🌐 Hosted sites * **Faster real-time:** we improved support for **WebSocket and Server-Sent Events** connections to your hosted apps — more speed and smoothness for live dashboards, chats, and long-lived streams. * **DNS up to 6x faster:** analysis of newly added domains and subdomains is now about **6x faster**, making them reachable much sooner. ### 💳 Billing and renewals * **Smarter auto-renewal:** added a card right before your plan expires? Renewal still happens on time — with safeguards to make sure **you're never billed twice** for the same cycle, including when a manual payment is in flight. * **Richer history:** your **gift codes redeemed in the last 12 months** now appear alongside your invoices. * **More robust payment** processing. ### 📦 API and storage * **Large-app snapshots in the background:** heavy snapshots now build in the background and show up in your list automatically when ready — fire it off and keep working. * **More reliable daily snapshots:** automated daily snapshots can now resume from where they left off if a run is interrupted. * **Faster loading** of workspaces and the dashboard, thanks to backend performance improvements. * **Clearer errors and docs:** oversized file reads now return a proper "file too large" response, and several endpoint descriptions are more precise. * **More flexible API key rotation** and a smoother experience for accounts without an active plan when accessing features that need a plan. * **Storage (Blob):** **faster object listing** and **more stable uploads** even when you push several at once. ### 📧 Your account emails, rethought We refined the whole account-email experience this cycle: * **Localized in all 8 languages**, matching the platform's new translation coverage. * **Refreshed onboarding:** welcome messages now show how to get the most out of the platform — the **VS Code extension** (deploy straight from your editor), the **CLI**, and the **mobile app** to monitor and restart your apps from anywhere. * **Clearer follow-up emails** (welcome, tips, and reminders), better organized and consistently formatted. ### 📈 Web, privacy, and discovery * **llms.txt** so AI search assistants can accurately describe Square Cloud's plans, runtimes, and features. * **Privacy controls** for analytics (GA4) with a granular preferences panel on the Privacy page. * **2026 revision** of the Terms of Service, Usage Policy, and Privacy Policy. ### 🔐 Security and reliability We continue with **ongoing security and session-reliability improvements** behind the scenes, keeping your account protected without getting in your way. ### 📊 Quick summary | Area | Highlight | | - | - | | Languages | **+4 languages** (Japanese, French, German, Italian) → **8 total**, covering website, dashboard, emails, and sign-in | | Performance | **Cluster \~2x faster**, React 19, assets **\~59% smaller**, faster pages | | Dashboard | Bulk upload, rethought auto-renewal, redeems, and snapshot experience | | Discord | Server rejoin + role re-sync on sign-in | | Hosted sites | Faster real-time (WebSocket/SSE), **DNS \~6x faster** | | Billing | Smarter auto-renewal with no double-billing, gift-code history | Thank you for building with Square Cloud. Every one of these updates was born from the feedback of people who use the platform every day — keep your ideas and suggestions coming. There's much more on the way. ❤️ ## 🚀 New VS Code extension, Node.js SDK v4, stable types, and a completely rethought dashboard! Ten days of intense work across nearly every Square Cloud product, and the result is one of the largest batches of releases we have ever shipped in a single window. We rewrote the VS Code extension from scratch, published a new major version of the official Node.js SDK, stabilized the API types, updated and expanded the OpenAPI documentation, and redesigned a large part of the dashboard experience — from the notification center to a brand new plan upgrade system. ### 🧩 VS Code Extension v5 The Square Cloud extension for Visual Studio Code received its **biggest update since launch**. This was not a small set of incremental improvements: the extension was **completely rewritten** on top of the new generation of our SDK, opening the door to features the community had been asking for and leaving the codebase much more solid for what is still to come. * **Workspaces directly in the editor:** the full workspace organization of your applications, previously available only in the web dashboard, is now accessible directly from the VS Code sidebar. * **Databases at your fingertips:** support for MongoDB, Redis, PostgreSQL, and MySQL inside the editor — view your instances and the overview of your data infrastructure without opening the browser. * **Environment variables:** check and adjust your application variables without leaving VS Code. Perfect for debugging configuration issues in seconds. * **Status in the editor status bar:** the state of your applications appears in real time in the VS Code status bar, without needing to open any tab or panel. * **More stable, more consistent:** the rewrite on top of SDK v4 made the extension predictable, with a polished experience across all supported languages. ### 📦 Official Node.js SDK v4 The official Square Cloud SDK for JavaScript/TypeScript reached its **new major version: v4**, and this is by far the largest evolution of the library in its entire history. v4 opens programmatic access to nearly the entire platform, with entirely new modules and deep improvements to the existing ones. * **Databases (brand new module):** list, create, and check the status of your instances. The new `Database` class gives you complete control: start, stop, update, delete, metrics, TLS certificate read, password/certificate rotation, and **database snapshots** with list, create, and **restore**. * **Workspaces:** manage them entirely through code — `list`, `find`, `create`, `leave`, and `delete` workspaces, generate invite codes, manage members (add, update, remove, roles), and share/unshare applications. * **Environment variables:** dedicated application module with `list`, `set`, `replace`, and `delete` — perfect for deploy automations and keeping environments in sync. * **Metrics and realtime:** `getMetrics()` returns the time series of **CPU, RAM, and network from the last 24 hours**. `realtime()` opens a **Server-Sent Events** stream with live updates from your application. * **GitHub-integrated deploys:** `linkGithubApp()`, `unlinkGithubApp()`, and `current()` to automate your deploy pipeline directly from the SDK. * **Application snapshots and restore:** the old "backups" concept became **snapshots** across the entire library, with clearer naming and **snapshot restore** (`snapshots.restore`) — a long-requested feature. Listing snapshots in the user scope is also available. * **Edge analytics and Network suite:** complete observability with **errors**, **logs**, **performance**, and **cache purge**, plus **DNS** data. `purgeCache()` was simplified and now clears the cache for the entire application. * **Platform health and new data:** `service.status()` in a single call, new fields on databases (language, creation date), applications (domain, custom domain, creation date), and users, plus **public error codes** accessible via `err.code` (e.g., `err.code === "FAILED_READ"`). * **Next-generation types and quality:** consumption of the new **API Types** line (now stable), more accurate autocomplete, several bug fixes, and **runnable examples** ready to copy and run. > **Breaking changes (3.x → v4):** `client.users.*` became `client.user.*`; `app.backup` / `app.backups` became `app.snapshots`; `app.deploys.list()` returns `Deployment[][]` (use `.flat()` for the old behavior); `app.network.dns()` returns `{ ownership, ssl }`; `app.network.analytics()` requires `{ start, end }`; in workspaces, `members` / `applications` became `memberList` / `applicationList`; **minimum Node is now 20+**. ### 🔌 Public API and official types The Square Cloud public API, the entry point for any integration with the platform, received a significant round of improvements. * **Revised and expanded OpenAPI documentation:** we expanded coverage to more endpoints and enriched the schemas for applications, databases, runtime statistics, file uploads, and more. Descriptions, response messages, and status codes were reviewed — you spend less time guessing the format of a response and more time building your integration. * **New Network endpoints:** focused on performance and errors, exposing data that was previously hard to access. These same endpoints power the new Network module in the Node.js SDK. * **Richer responses:** workspaces and users now carry the join moment (`joinedAt`), runtime statistics gained more detail, file reading now handles UTF-8 content better, and descriptions were revised across multiple endpoints. * **API Types v1.0: stable types.** The official API types reached their first stable version, with proper semantic versioning, full predictability for those who depend on them, and coordinated evolution alongside the simplification of the cache purge feature. ### 🎨 Dashboard The web dashboard, where most people experience Square Cloud day to day, is where we concentrated the largest volume of improvements during this period. Dozens of refinements, from brand new features to careful usability polish. * **New notification center with 1-click renewal:** redesigned bell and notification system from scratch. When your plan is close to expiring, the notification itself offers immediate renewal, without you needing to navigate through several screens. Usage and expiration notices migrated to this new system. * **New plan upgrade system:** * **Upgrade at any time, including mid-cycle** — the larger resources take effect immediately, without waiting for renewal. * **Proportional (pro-rata) charge with preview before confirming** — you see exactly how much you will pay, calculated based on the time remaining in your current cycle. * **Plan transition without overlapping charges** — the replaced plan's charge is automatically cancelled, with a unified calculation for the migration. * **Clearly identified invoices** in the history and **updated FAQ** explaining how everything works. * **New credit card experience:** redesigned flow, mobile-optimized, with **3DS authentication** from banks when needed. Lighter loading and more direct form filling. * **Reformulated billing page:** the old "invoices" gave way to the new **Billing** section, with much clearer history and details, identification of upgrade-related charges, and a dedicated tab for billing details. * **New pricing page and updated FAQ:** clearer and more direct plan presentation, working side by side with the new upgrade system. * **Redesigned file manager:** performance improvements when opening files and folders, smoother navigation, and clearer messages on actions like folder deletion. * **Improved analytics and logs:** quick content copy directly from the table, making issue investigation much faster. * **New section on the Bots page**, with more relevant information for those hosting bots. * **Translated DNS status** in every language. * **Light/dark theme** with several fine adjustments to contrast, icons, and logos. * **Broad mobile improvements**, with online/offline status, snapshots, and deploy screens redesigned for touch. * **More robust automatic reconnection** on real-time screens and stability fixes that make navigation feel solid overall. ### 📊 Quick version summary | Product | Version | Main highlight | | - | - | - | | VS Code Extension | **v5** | Workspaces, databases, environment variables, and real-time status, in a complete rewrite | | Official Node.js SDK | **v4** | New modules for databases, workspaces, environment variables, metrics, realtime (SSE), GitHub deploys, and edge analytics | | API Types | **v1.0** | First stable version of the official types | | Dashboard | n/a | New plan upgrade system (pro-rata with preview), notification center with 1-click renewal, new card experience, redesigned billing and pricing | Thank you for building with Square Cloud. Each of these releases was born from feedback from those who use the platform every day. Keep sending your ideas and suggestions — there is much more to come. ## 🚀 Mobile App, Runtime Hub, updated environments, and broad improvements across the entire platform! This cycle brings updates to every corner of Square Cloud: we launched a dedicated runtime hub with a specific page for each supported language, officially integrated our Android app into the platform, updated the full environment matrix, completed the light theme across the entire website, and shipped a broad round of UX, performance, and security improvements. ### 📱 Official Mobile App * **Native Android app** officially integrated into the platform. Square Cloud links now open directly in the app when you have it installed, without going through the browser. * **New dedicated page at `/resources/app`** presenting the app, its features, and the download link. * **Feature spotlight on the website** inviting users to try the app from strategic navigation points. * **Optimized installation size** to fit comfortably on any phone, with accurate descriptions in every supported language. * Available in **Portuguese, English, Spanish, and Chinese**, with full content parity across languages. ### 🧭 New Runtime Hub We launched a complete set of pages dedicated to the languages supported by the platform: * **Index page at `/runtimes`** with a visual grid and comparison table across all languages — available versions, key features, and a direct link to each specific page. * **Dynamic `/runtimes/[language]` page** with a custom hero, technical specifications, real use cases, available version listings, and a ready-to-copy configuration example for your `squarecloud.app`. * **Website header and mobile dropdown** updated with direct runtime navigation — now your language documentation is one click away. * **Shared FAQ across all pages** with the most common questions about each environment. * **Localized sitemap, metadata, and banners** for SEO in every supported language. * Everything is available in **PT-BR, EN, ES, and ZH**. ### 🆕 Environment Updates We keep our runtime matrix on the latest stable versions in the industry. These are the versions available starting with this cycle: * **JavaScript \[Node.js]** → Recommended: `24.15.0` | Latest: `26.1.0` * **Python** → Recommended: `3.13.13` | Latest: `3.14.5` * **DOTNET** → Recommended/Latest: `10.0.8` * **Rust** → Recommended/Latest: `1.95.0` * **Ruby** → Recommended/Latest: `4.0.4` * **PHP** → Recommended/Latest: `8.5.6` * **Go** → Recommended/Latest: `1.26.3` Node application cold starts became slightly faster in preliminary tests with the new matrix (this varies a lot by workload — we are still validating the real production numbers). ### ⚡ Faster and More Robust API * **Faster responses** on routes that depend on multiple checks, with no changes required on your end. * **Lower memory usage under load**, helping maintain stability during traffic peaks. * **Graceful shutdown** during maintenance and deployments — in-flight requests are completed correctly before maintenance proceeds. * **Improved handling of abrupt disconnections**, preventing ghost connections in monitoring tools and dashboards. * **More resilient workspace cleanup**, with clearer error handling in maintenance operations. ### 🛡️ Security and Privacy * **New account deletion page**, fully aligned with the **LGPD**. You always had this right — now the path is documented, translated, and one click away. * **Hardened upload validation:** file names, content types, and payload limits are now checked more consistently by scope. * **Improved workspace permission checks** on administrative actions. * **Refined security headers:** CSP and Referrer-Policy adjusted across the entire site for better protection against XSS and referrer leaks. * **Hardened token and API key comparison routines.** * **Improved validation for return links and redirects.** * External links now use `rel="noopener noreferrer"` across the entire website. ### 🎨 Renovated Website A large part of the website was touched in this cycle: * **New landing page** with a redesigned visual identity and header fixes. * **Complete light theme:** every component, modal, chart, and page now respects your system preference (light/dark). * **Bundle reduced by approximately 43%.** The site loads faster on any connection. * **New `/about` page** telling our story. The old page was moved to the documentation. * **New `/support` page** with chat, email, and contact channels organized clearly. * **New Help Center** in developer resources, grouping documentation, guides, and useful links. * **New Blob dashboard** with grid and list views, image previews, debounced search, and much faster object management. * **New Workspace creation page** with a simplified flow and clearer messages. * **New mobile header navigation** that feels much smoother. * **Footer with links grouped by category** — much easier to find what you are looking for. * **Complete refactor of the `/services` and `/resources` pages** for a more consistent experience across verticals. ### 📦 Upload and File Manager * **Bulk delete with live progress** and a "select all" action in the File Manager — managing many files is finally fast. * **Stricter upload validations** with clear error messages for invalid, empty, or corrupted files. * **New code editor** with autocomplete, automatic bracket closing, and better shortcuts — designed for long editing sessions. * **Automatic environment variable detection** in the upload context was kept and refined. ### 🗄️ Blob and Storage * **Automatic cleanup of orphaned objects** in storage — saving space and optimizing costs. * **Faster and more reliable inactive account reconciliation**, with better error reporting at each step. ### 💳 Billing and Checkout * **Selected duration remembered** between checkout screens — no more selecting monthly or yearly twice. * **Enterprise plan slider** redesigned with a dedicated label and better readability. * **Billing logic adapted** to the light theme across all components (payment cards, plan duration, etc.). * **Tier order reorganized** in the plan selector for a more intuitive path between options. * **Plan notices** refactored for better visual structure and clearer copy. ### ♿ Accessibility * **Hidden element behavior** fixed to work properly with screen readers and keyboard focus. * **Full `prefers-reduced-motion` support** across the entire site — animations and transitions are automatically disabled for users who prefer reduced motion. * **Optimized images** for better perceived performance and lower data usage. ### 🌍 Internationalization * **Full translation refactor** in **PT-BR, EN, ES, and ZH** with paired quality review across all 4 languages. * **FAQs about services, bots, and databases** are now 100% covered in Chinese. * **Language disclaimer** added to legal pages in all 4 languages, making it clear which version prevails in case of divergence. * **Standardized the term `workspace`** in Spanish as `espacio de trabajo` across all texts. * **Standardized database naming** (`MongoDB Hosting`, `Redis Hosting`, etc.) across the entire site, copy, and metadata. * Fixed several typos and grammar issues in existing translations. ### 🆘 Support and Communication * **New Support page** with live chat, email, and alternative channels clearly organized. * **WhatsApp** added as an official contact channel. * **Live chat** with automatic real-time online status detection. * **Chat synchronized** with the site theme (light/dark) and the user's session. ### 🤖 PWA and Android App Links * **Native Android app integration** published — platform links can be opened directly in the app without the browser prompt. * **Manifest and icons revised** for a better experience on any device. * **Improved metadata** for mobile application support on every relevant page. ### 🧩 Modals and CTAs * **Unified modal system** across all pages, with consistent performance and usability. * **New useful modals:** gift code redemption, insufficient memory, and verification code confirmation. * **Shared CTA** replacing duplicated CTAs across all product pages — communication is now consistent across the entire site. ### 🔧 Hotfixes and Quality of Life * Fixed pending redirects from the old `/sac` to `/support` across links, sitemap, and redirects. * Headers, modals, alerts, and tooltips received visibility fixes in the light theme. * Correct truncation of long IDs on mobile in application and database listings. (thanks to everyone who reported this!) * SEO structure with localized structured data by language and breadcrumb support on all main pages. * Several spelling and grammar fixes in existing translations. ## 🚀 Faster API, stronger infrastructure, and completely renovated dashboard! This is the largest update cycle at Square Cloud since the platform's launch. We rewrote the API core, expanded Realtime, completely redesigned Snapshots, and delivered a faster and more beautiful dashboard — all at the same time. ### 🧭 New API Foundation We rewrote how our routes process requests internally. The result is visible without any changes on your end: * **Faster responses** on all routes that depend on multiple checks. * **Fairer quota:** invalid requests are now rejected before consuming your limit. * **Correct rate limits in workspaces:** workspace members share the limit accurately — no loopholes. * **HTTP codes aligned with standards:** 401, 403, and 404 where they should be. No more generic errors that don't explain what happened. * **Improved compatibility** with clients that send non-standard headers. * **More secure file manager:** reinforced path validation by the File Manager to prevent human errors and improved speed when handling large directories. ### 🔌 Realtime with more capacity * **Up to 10 simultaneous connections per application** (previously 5). Live dashboards, logs, and observability tools now work without competing for slots. * Abrupt disconnections are handled much more robustly — terminated connections are completely freed, without accumulation over time. * Clearer error messages when the connection limit is reached. ### 🗄️ Snapshots and Backups The snapshot system was completely rewritten from scratch during this cycle: * **More efficient engine:** lower resource usage during backup generation, with adaptive compression based on snapshot type. * **Restore with guaranteed integrity:** restores keep the **60-second** stabilization window introduced in the February update, ensuring all data is completely stable before your application goes back online. * **Lists and details cached** for longer, reducing wait time when browsing between snapshots. * Errors during backup generation are now reported correctly — no silent failures. (thanks to everyone who reported this!) ### 🤖 New AI Engine * AI response generation migrated to a new provider and now **automatically selects the best available model** with each request. Direct result: faster and more consistent responses. * New **AI Analytics dashboard** available in the dashboard, with insights from your application. Available in Portuguese, English, Spanish, and Chinese. ### 🔁 Deploy via Git * We blocked the creation of two deploys pointing to the **same repository + branch** on the same account, preventing accidental duplicate deploys and confusion when managing multiple environments. * Deploy and code commits now complete correctly even under adverse network conditions — no silent errors or timeouts without response. ### 🎨 Renovated Dashboard * **Much faster real-time console** — logs appear almost instantly, without the sensation of freezing. * **Lighter dashboard** with pages that open faster especially on mobile. * **Improved mobile filter navigation** — filters take up less screen space, leaving more room for content. * **New pricing page (`/pricing`):** clearer comparisons, duration selection that remembers your choice, and reorganized layout. * **New paywall** on application and database pages — more visual, with rotating testimonials and direct button to choose a plan. * **New header and new footer** with reorganized links and more accessible language button. * **Redesigned heroes** on `/bots`, `/sites`, `/blob`, and `/databases`. * **New page `/resources/infrastructure`**. * **Revised banners** across the platform, with more consistent visuals. * **New code editor** with better shortcuts (including indentation with `Tab`), more readable syntax highlighting, and new font optimized for extended reading. ### 📦 Application Upload * We accept **`.zip` files up to 1GB on upload** to identify and inform exactly what needs to be removed (`node_modules`, caches, `.git`) — instead of simply rejecting the file. * The **platform's real limit remains 100MB**, but the experience of reaching that limit is now much clearer and friendlier. * If your `.zip` already contains a `squarecloud.app` or `.env` file, we ask if you want to **import the configuration automatically**. * Much clearer error messages for corrupted, empty, or unsupported format files. * Compressed files uploaded to the platform now go through extra validations and inappropriate files are **automatically blocked**. ### 🤝 Workspaces and Members * **Workspace members** can now add and remove subdomains without needing the account owner. * **Resource-specific paywalls** clearly inform, in a friendly way, what each plan unlocks — no surprises. ### 💳 Billing and Checkout * Checkout, renewal, and upgrade **preserve the chosen duration** between screens — no confusion. * **Blindsided downgrade:** before reducing the plan, we check if there are workspaces or custom domains incompatible with the destination plan. * (it was an intentional feature, but we noticed it could lead to inconsistencies even if domains were deactivated some time after the downgrade). * Canceled invoices go straight to checkout — no need to look for the right button. * Downgrade modal with step-by-step explanations and more human messages. ### 🔐 Account and Security * **Discord signup** now available, with all legal notices in place. (we resumed accepting new Discord registrations after we had disabled it). * Simplified login flow — fewer intermediate screens, less confusion. * More reliable sessions and logout in case of account switching. ### 🧱 General Stability * Reinforced internal network infrastructure, preventing connectivity issues in corporate environments. * Reduction of processing spikes during high-volume deploy hours. * When a workspace doesn't exist, the response is now a **clear 404** — no ambiguity. * Commits per minute limit adjusted to reduce burst deploy abuse. ### 🌍 Translations * **Portuguese, English, Spanish, and Chinese** reviewed end-to-end. * Correction of various typos and standardization of technical terms in all languages. * Regulatory notices (PayPal, Pix) with dedicated text in each language. (thanks to everyone who pointed this out!) ### 📈 Observability * The log pipeline was migrated to a more secure and modern authentication method, making integration simpler to operate. * The log buffer was reinforced to not lose events in the first few seconds after application boot. * We expanded the capacity of simultaneous connections made by the platform to external services. Fewer queues during peak times, fewer sporadic timeouts for your applications. ## 🚀 Brutal Performance, Data Intelligence and New Era of Infrastructure! Today we deliver the biggest technical leap in Square Cloud's history. We're not just scaling hardware; we're rewriting our platform's core with low-level algorithms to ensure an unprecedented development experience. > **CEO Note:** "This update sets the new efficiency standard at Square Cloud. By optimizing processing to $O(1)$ and refining snapshot orchestration, we deliver infrastructure that doesn't just host, but amplifies the growth of every project." ### ⚡ Performance Engineering: O(1) Core Engine We dove deep into our network and telemetry layer to eliminate every millisecond of overhead: * **Rate Limiting 2.0 (200x Gain):** We migrated to a more efficient constant-flow model. Traffic validation is now instant, regardless of load. * **Accelerated Realtime-Console:** We reduced round-trips and streamlined active connection handling. The console now responds in real time. * **Lean Runtime:** We performed stripping of obsolete dependencies and redundant validations in the execution environment, guaranteeing more actual CPU and RAM for your application. * **Smart Analysis System:** Intelligent system that automatically tracks deploys and performs random re-analyses hours later to ensure runtime integrity. ### 🗄️ Databases: Integrity, Encryption and Snapshots We solved complex orchestration challenges to ensure your data is always accessible: * **Credential Consistency Fix (MongoDB/MySQL):** Fixed a credential consistency issue after database snapshot restoration. Restores now keep account access flows consistent. * **Snapshots Management:** Restore cooldown increased from **30s to 60s** to ensure physical data stabilization and index propagation. * **Dedicated Pages:** Launch of optimized dashboards for `Redis`, `MySQL`, `PostgreSQL` and `MongoDB`. ### 📦 Runtime Update (2026 Stack) Maintaining our commitment to the state of the art, we updated our official environments: * **DOTNET:** Updated to **10.0.2**. * **ELIXIR:** Updated to **1.19.5**. * **GOLANG:** Updated to **1.25.7**. * **RUST:** Updated to **1.93.0**. ### 🛠️ Developer Experience (DX) and UX We optimized the workflow to make file and deployment management more fluid: * **File Manager Pro:** Added support for **bulk selection (up to 50 files)**, deletion confirmation via modal and `ESC` shortcut for quick deselection. * **Smart Upload:** Support for **Drag & Drop .zip files** with content visualization and automatic framework detection (**Next.js, Vite and Vue**). * **Git App (Case-Sensitivity):** Fixed bug that forced branches to lowercase. Now, the system respects original casing (e.g., `Dev` remains `Dev`). * **Network Intelligence:** Quick buttons to copy URLs and new `/network/logs` route (exclusive PRO/Enterprise) with date filters (`?start` and `?end`). ### ⚖️ Sustainability and Pro Infrastructure We redefined our limits to ensure global stability at all levels: * **New PRO Tier (24GB):** 12 high-performance vCPUs and 250GB Blob Storage. * **Enterprise Scale-Out:** Now starting at **16 base vCPUs** and support for **Enterprise-1024** (up to 1024 distributed vCPUs). * **Burst Logic 2.0:** New contextual CPU allocation algorithm that allows performance spikes based on project's actual need. * **Hobby Plan Focus:** To preserve global performance, the Hobby plan now focuses exclusively on applications, removing dedicated database instances and massive global snapshots to ensure 100% network availability. We continue building the future of hosting, one commit at a time. 🚀 ## 🚀 Visual Overhaul, LGPD and Core Optimizations! Today we’re launching an update focused on a visual overhaul of our main pages, critical improvements to the developer experience (DX), and a major data cleanup for compliance and performance. > **Black Friday Note:** Thank you for the massive participation! Our infrastructure operated with total stability during the period. The focus now is 100% back on product evolution. ### 🎨 New Design and User Experience (UX) We redesigned key areas of the platform to make it more modern and accessible: * **New Home and Authentication:** A completely new and smooth login/signup experience. * **Documentation Improvements:** General review and enhancement for greater technical clarity. * **Workspace Experience:** Admins now have better visual feedback on permissions, and Owners receive clearer guidance on resource allocation. ### 🔐 Secrets Tab Redesign By popular demand, we rebuilt the UI/UX for environment variable management to be more productive: * **SQUARECLOUD\_APP\_ID:** Automatic injection of this ENV with the application ID. * **Quick Actions:** Button to clear all ENVs and new validation on export. * **Advanced Interaction (Shift):** Holding `SHIFT` turns the menu button into a trash can for quick deletion. * **Direct Editing:** Click the input to edit the value immediately, no need to open menus. * **Compact Design:** Reduced overall padding for a denser and more efficient information view. ### 🛠️ Deploy and File Features We expanded your control over files and databases: * **Directory Handling:** You can now **rename and move directories** directly from the dashboard. * **Commit API (`?path=`):** Added support for allocating commits to specific subdirectories via API. * **Static Environments:** When deploying via runtime, the system automatically detects HTML/CSS projects, hides unnecessary commands, and makes publishing easier. * **Postgres:** PostgreSQL databases now start with the `squarecloud` database created by default, avoiding connection errors for beginners. ### 🔒 Security, LGPD and Infrastructure We focused on privacy and core platform stability: * **Data Cleanup (LGPD):** In compliance with privacy regulations, we permanently deleted **50,000+ support chats** and **40,000+ contacts** inactive for over 365 days. * **squareweb.app Scope:** Now accepts and manages connections from the Tor network (with security challenge). * **Smart Cache Reset:** New intelligent global cache cleaning system. * **VSCode Extension:** Fixes applied to resolve involuntary logouts. * **Hobby T1 Standardization:** Multithreading adjustment in this tier for standardization with the rest of the existing plans. ### 📉 Data Lifecycle Optimization We refined backup retention to improve storage efficiency and eliminate obsolete data: * **Application Snapshots:** Old versions now last up to **44 days** (30 days primary + 14 days retention). * **Database Backups:** Old versions now last up to **21 days** (14 days + 7 days retention). We continue working to make Square Cloud more and more efficient. ## 🚀 Black Friday, MySQL, Articles and Globalization! Today we're launching an update focused on tooling improvements, globalization of several areas, and enhanced overall platform usability. And there's more: the **only promotion of the year** is now live! ### 🎉 Black Friday — THE ONLY 2025 PROMOTION **Annual discount DOUBLED: 30% OFF** on any renewal, upgrade, or first purchase on the annual plan. Discounted pricing examples: (values in BRL) * **Standard T1:** from **34,90** to **24,43** month * **Pro T1:** from **100** to **70** month Take advantage of this exclusive opportunity to save and scale your projects on Square Cloud! ### ✨ Dashboard styling overhaul and bug fixes We completely redesigned the platform navigation, making several areas more accessible and modern: * Redesigned navigation to facilitate access to important features. * Optimizations to improve the experience for developers who rely on screen readers. * New rendering logic across much of the website, making everything more dynamic and faster. * Improved visualization of what gets removed when downgrading a plan. * Semiannual option removed — we now offer only two clearer and easier-to-understand options (monthly and annual). * Fixed several bugs that impacted navigation. * Improved compatibility with legacy browsers. ### 🛠️ Deploy experience improvements + new Database We expanded database support and optimized the deployment process: * **MySQL v9:** Now available and optimized for production. * **Elixir:** Runtime issues fixed + updated to version **1.19.2**. * Implemented more aggressive limits on file viewing via File Manager API (no more trying to view a 1GB file 😊). * Fixed a Git integration issue that caused higher-than-expected latency: * Listing reduced to the last 5 deploys. * Improved error notifications in responses. * **\~14ms global reduction** in deploys with the new architecture. * Fixed error that prevented viewing the Snapshots tab in some workspaces. * Fixed bug that imported empty environment variable when deploying with a partially invalid file. ### 📚 New articles and tutorials We added comprehensive guides to facilitate deployment of different frameworks and technologies: * **Angular:** [How to deploy an Angular project](https://docs.squarecloud.app/en/tutorials/website/angular) * **AstroJS:** [How to deploy an AstroJS project](https://docs.squarecloud.app/en/tutorials/website/astrojs) * **Nuxt:** [How to deploy a Nuxt project](https://docs.squarecloud.app/en/tutorials/website/nuxt) * **Gatsby:** [How to deploy a Gatsby project](https://docs.squarecloud.app/en/tutorials/website/gatsby) * **Laravel:** [How to deploy a Laravel API](https://docs.squarecloud.app/en/tutorials/api/laravel) * **Spring Boot:** [How to deploy a Spring Boot API](https://docs.squarecloud.app/en/tutorials/api/spring-boot) These tutorials cover everything from initial configuration to complete deployment, helping you get your projects live quickly. ### 🌍 Globalization and general improvements We continue expanding and improving the platform's international experience, with focus on accessibility, performance, and communication clarity. These are just some of the new features! We continue listening to the community and working daily to make Square Cloud even better. ## What's new and improvements (11/06/2025) We shipped an important set of usability, media-preview and runtime infrastructure improvements — all designed to speed up your workflows and make the platform friendlier for everyone, from trial users to high-traffic teams. ### Improved dashboard for users without an active plan The dashboard now offers a warmer, more informative experience for users who don't have an active plan. The UI highlights recommended actions (start a deploy, connect a repository, redeem credits), with clearer navigation and panels focused on what new users need most. ### Enhanced Blob previews The Blob page now lets you preview images and videos directly in the browser without downloading them. This makes content inspection faster, speeds up validations and reduces the time spent debugging multimedia assets. ### Dynamic application listing Application lists now adapt automatically to the user's screen height, making better use of vertical space on large monitors and providing a consistent experience across devices. ### Better empty states Sections such as "Applications" and "Databases" received redesigned empty states: clearer messaging, suggested next steps and helpful CTAs that make the first-time experience more guided and actionable. ### Plan downgrade now available You can now downgrade your plan directly from the **My Account** tab — fully automated, secure and transparent, with confirmation steps and an audit history. ### Export environment variables We added a one-click export button in the **Environment Variables** panel. Download all your variables in common formats (dotenv / JSON) for backups or fast migration between projects. ### GitHub upload with automatic configuration When uploading from GitHub the platform will attempt to auto-detect and configure the repository (package manager, start command, build scripts), reducing configuration errors and accelerating the first deploy. ### Search button in the file editor We implemented a native search button in the file editor optimized for mobile devices — making it easier to find code snippets directly from your phone. ### Global rate limit display fixed > We fixed an issue that in some scenarios caused a client-side exception when displaying the global rate limit. The UI is now stable and resilient. ### Website now uses the React Compiler We migrated the site to the React Compiler, improving rendering performance, reducing TTFB and making navigation smoother on pages with dynamic content. ### Snapshot filename format standardized Snapshot download filenames are now standardized to include app name, timestamp and app id for easier organization and traceability. New pattern: ``` _2025-12-31_12-59-59_.zip ``` ### Detailed plan comparison The **Pricing** page has been redesigned with a visual comparison of tiers. It's now easier to understand limits, benefits and pick the plan that fits your needs. ## Environment updates We updated and expanded runtime and language support: * **Ruby \[New runtime]** * Available for production workloads. * `recommended`/`latest`: **3.4.7**. * **Java \[Gradle & Maven support]** * `recommended`/`latest`: **JDK 25**. * **Node.js** * `recommended`: **v24.11.0** (LTS) — now adopted as default. * `latest`: **v25.1.0** — supported; in tests we observed up to **\~40% web-performance gains** in specific scenarios. * *Note: Node 25 is recommended for performance-focused workloads — test before migrating production.* * **Python** * `recommended`: **3.13.9**. * `latest`: **3.14.0**. * **C# (ASP.NET)** — `recommended`/`latest`: **9.0.10**. * **Elixir** * `recommended`/`latest`: **1.91.1**. * **Rust** * `recommended`/`latest`: **1.91.0**. * **PHP** * `recommended` & `latest`: **8.4.14**. * **Go** * `recommended` & `latest`: **1.25.4**. Notes: Ruby support was implemented in this release; Java now supports Gradle and Maven projects. Node 24 LTS is the default runtime; Node 25 is available for users who need extra performance. ## Fixes & minor adjustments * UX refinements across panels and modals (multiple friction points reduced). * Snapshot filename normalization and download improvements. * Small fixes in GitHub upload flow and repository auto-validation. * Blob now validates available capacity faster for large uploads. These updates are rolling out gradually. We're listening to the community and prioritizing changes that directly boost your productivity. ## Upload and GitHub Integration Redesign We have focused our efforts on revolutionizing the deployment and GitHub integration experience, bringing significant improvements that make the workflow simpler, more modern, and efficient. Check out the main new features that are now available: ### New Upload Experience We've created a completely rethought upload experience for modern developers. * **New upload page:** We now have a page dedicated exclusively to uploads, completely redesigned to offer a simpler, more modern, and intuitive experience. * The upload page is now available at `/upload` instead of `/dashboard/upload`. In addition to convenience, this change contributes to the site's SEO, making the upload page public and improving its indexing in search engines. ### Revolutionized GitHub Integration We have drastically simplified the process of integrating with GitHub repositories. * **Upload via GitHub (without an access token):** We've made the repository integration process even easier. You can now upload directly from GitHub without needing to manually enter an access token. * **Full integration with GitHub repositories:** You can connect your GitHub repository directly to your application, simplifying the deployment flow and making automation even more practical and secure. * **Direct connection with your GitHub account:** Connecting to GitHub is now even easier: just authenticate with your account to enjoy all integration features in a centralized and transparent way. * **Login via GitHub:** In addition to connecting for integrations, you can now use your own GitHub account to log in or create an account on our platform, making the authentication process fast, secure, and hassle-free. ### UI and SEO Improvements We have enhanced the platform's visual experience and online presence. * **Complete redesign of the "My Account" tab:** The profile and settings section has undergone a complete redesign, featuring a cleaner, more modern, and organized interface, allowing you to manage your information more simply. * **Website SEO improvement:** In addition to the new route, the site has undergone technical and content adjustments aimed at search engine optimization, ensuring better indexing performance and greater visibility on Google. ### Enhanced VSCode Extension We have improved the development experience directly from your favorite editor. * **Improved extension loading:** We have optimized the loading process of the VSCode extension, making initialization faster and more efficient for a smoother development experience. ### Modernized Snapshot System We have completely replaced the previous system with a more advanced solution. * **Complete migration from backups to snapshots:** The old backups have been replaced by the snapshot system, offering greater efficiency, faster restoration speeds, and better management of your application's version history. ### Modernized Tax Invoice System We have updated our fiscal infrastructure for greater compatibility and efficiency. * **Migration to the new ISSNet from the Goiânia City Hall:** Our electronic service tax invoice (NFSe) system has been completely migrated to use the new ISSNet from the Goiânia City Hall, ensuring greater stability, compliance, and agility in issuing service tax invoices. ### PHP + Swoole Improved Swoole support has been launched in conjunction with PHP version 8.4.12. ### Critical Fixes We have resolved important issues that affected file integrity. * **Fix in the file upload and compression process:** We identified and corrected a bug that affected the recompression of files uploaded through the platform. In some specific cases, this flaw resulted in the generation of corrupted binary files after the upload. The process has now been fully adjusted and validated to ensure that all files are stored and distributed with integrity and reliability, eliminating the risk of inconsistencies. These improvements represent a significant milestone in the evolution of Square Cloud, solidifying our position as **the most modern and intuitive platform for the new generation of developers.** ## EVEN MORE affordable plan and + DISCOUNTS! We continue our mission to listen to you and optimize every detail of the platform. We have gathered a series of **performance improvements, new features, and quality of life adjustments** that are already available and will boost your development experience. Check out what we have prepared: ## New Hobby plan and discounts = Square Cloud listening to you. Following the philosophy of going **against the market**, we brought more advantages for your pocket. * **Real-Time Downgrade:** We launched the new **instant downgrade** system. No waiting, no bureaucracy, you have full control of your plan. * **New Affordable Hobby Plan:** We introduced the Hobby plan with two tiers, with prices starting at **R\$ 9.99/month** on the annual cycle. * **MORE DISCOUNTS, BECAUSE YOU DESERVE IT:** We increased the discounts! Now it's **10% for the semiannual plan** and **15% for the annual plan**. ### Performance and speed optimizations We made everything even faster so you can focus on what matters: your code. * **Instant sync:** When updating RAM, the CPU is now adjusted in real time, with no delay. * **Ultra-fast realtime:** We reduced latency in primary loads, with an average improvement of 45ms. - We improved loading speed when interacting with bots and sites hosted on the platform. ### More control and flexibility for Your Account We upgraded customization tools so you have total autonomy. * **Editable subdomain and runtime:** Now you can edit your subdomain (`.squarecloud.app` and `.config`) and set the `RUNTIME` (javascript, typescript, etc.) directly in the application. (documentation for the `RUNTIME` field will be released soon). * **New "My Account" page and language:** Manage your information on a redesigned page and change the region/language to receive standardized emails. - We increased the limit to up to 3 username changes per day for your Square Cloud account. ### Experience and interface improvements We refined the interface for a cleaner and more productive workflow. * **Completely rewritten Logs tab:** The tab has been redesigned, including realtime, and now allows you to **delete all old records with a single click**. * **More intuitive dashboard:** We added icons for each language in the dashboard, making it easier to identify your applications. - We fixed an error that permanently redirected cookies to the login page in some cases. ### General Platform Adjustments * The API now returns the status `CONTAINER_TEMPORARILY_SUSPENDED` in cases of request abuse to ensure stability. * Inactive workspaces of users without active plans are now removed within 24 hours. These are just **some** of the new features we implemented with you in mind. Our commitment is to keep listening to the community and evolving to be **the best and most complete platform for the new generation of developers.** ## New Documentation in PT-BR and PostgreSQL Support! Once again, we listened to the community and brought some really cool news, focusing on improving the developer experience on our platform. It's time to present a series of improvements — some have been available for a few days, but may have gone unnoticed. Check them out below: ### Completely Renewed Documentation in Portuguese We created top-notch documentation, designed for Brazilian developers. * 100% in Portuguese (BR): Not a translation, but fully localized content, including images and tutorials. * Comprehensive Content: New guides, tutorials for specific scenarios, and detailed information about the platform. Check it out: **[https://docs.squarecloud.app/en/getting-started/overview](https://docs.squarecloud.app/en/getting-started/overview)** ### Enterprise-Scale PostgreSQL Support Create your PostgreSQL database with professional-level performance and security. * No limit on outbound and inbound network transfer. * Generous IOPS with NVME Enterprise. * Exclusive peer-to-peer certificate per database (mTLS). * Dedicated memory and CPU according to the plan. * Smart daily snapshots. * MySQL will be available in the coming days. * Square Cloud does not launch services that are not ready for production. ### Faster Snapshots We optimized the performance and stability of our backup system. * Performance: We doubled the internal bandwidth, processing up to 1,000 snapshots per minute. * Instant and free restoration of any snapshot from the last 30 days. ## Environment Update We are always improving our services to ensure you have access to the latest and most stable versions of the main programming languages. Check out what's new in this update! ### **New versions available:** * **JavaScript \[Node.js]** → Recommended: 22.18.0 | Latest: 24.5.0 * **Python** → Recommended: 3.13.6 | Latest: 3.13.6 * **Elixir** → Recommended: 1.18.4 | Latest: 1.18.4 * **Rust** → Recommended: 1.89.0 | Latest: 1.89.0 * **Go** → Recommended: 1.24.6 | Latest: 1.24.6 * **PHP** → Recommended: 8.4.11 | Latest: 8.4.11 \-- Improved support for Redis & MongoDB, with native support for the C-written library for Redis. What does this mean for you? * More stability and compatibility with modern applications. The updates are already available. 😄 ## General Platform Improvement (LOTS OF AMAZING NEWS!) Recently, we focused our efforts on **revolutionizing** the developer experience on our platform. It's time to present a series of **powerful new features** — some have been available for a few days, but may have gone unnoticed. Check out the improvements already live below: ### 100% Integrated Environment Variables * Now you can set environment variables directly via deploy or API. * Variables are automatically injected with a simple **restart** of the application. No need to use `.env` or extra packages! * Public routes available for **POST, PUT, DELETE, and GET** of variables. ### New Snapshot System (goodbye, manual backups) * Extremely generous limits: each plan can generate `(RAM / 256) * 2` snapshots per day. E.g.: Hobby plan with 2048MB = **16 daily snapshots** or up to **480/month**! * **Instant and FREE restoration** — recover any snapshot from the last 30 days in seconds. (gradual release for everyone in the coming days) * Square is going **against the market**: no charges, no hassle. ### Real-Time Configurable Start * Forget redeploying just to change the start script (START field in your config file). * Now you can **edit the START line directly**, restart the app, and that's it. All in real time and hassle-free. ### Advanced Databases (Redis & Mongo available!) * Create your real database with just 1 click. * **Exclusive peer-to-peer certificate** per database (no generic certificates). (mTLS) * RAM and processing from your plan, with total dedicated performance for the database. * 10GB of enterprise storage included with future expansion plans. * **Daily and automatic snapshots**. * **Intelligent and proactive snapshot system**: detects suspicious deletions and creates emergency backup (beta). * No bandwidth limitation and up to **512 simultaneous connections** per database. * Certificate and password reset in **one click**. * Databases already available: **Redis** and **MongoDB** — new databases coming soon! ### Faster and Smoother Dashboard * New "Settings" tab inside an application. * Deploys tab moved to Settings → Deploys. * Dedicated Environment Variables panel (Settings → Environment Variables). * Settings page now segmented into **5 sections** for easier navigation: General, Deploys, Environment Variables, Network, and Risk Zone. * New Pricing page and new page about Square Cloud Enterprise infrastructure and its exclusive plans (/enterprise). * New Analytics tab (viewing new data and interactive charts), with extremely accurate and improved insights for websites hosted on Square Cloud. * New application upload, more fluid and beautiful, with automatic detection of environment variables via .env file or internal context (automatic import). Oh, you can also paste variables using Ctrl+C and Ctrl+V. * The API now returns realtime records with surgical precision since the application start. These are just **some** of the improvements we are releasing for you. We keep listening to the community and working daily to make Square Cloud **the best platform for next-generation developers.** Note: we have greatly reduced and compacted the release notes, changed a lot in recent weeks, and focused on improving your experience. Thanks to everyone who participated or participates in our early access or beta test programs. @everyone ## General Security and Performance Update Recently, we have focused our efforts on improving the performance of some critical Square Cloud services. ### Security and Encryption * **Minimum TLS:** We now require TLS 1.2 as the standard for all of Square Cloud, including custom domains. * **Custom domains:** All custom domains have been configured to a minimum of TLS 1.2. * **Square Cloud proprietary domains:** For anti-phishing domains and enterprise scopes, the minimum TLS is 1.3. ### Log Management * **Application Log Limitation:** The maximum number of logs per category (logs/crash) in `.squarecloud` files has been reduced from 10 to 5. * **Log Infrastructure Change:** We have migrated our log infrastructure to a new, more modern and scalable observability stack. * **Log Coverage and Retention:** We now log 100% of requests to our main infrastructure (API, Website, Blob, etc.), with a 7 times greater data retention. ### Performance Optimization * **Asset Pre-processing:** We have improved asset pre-processing in our infrastructure, resulting in higher processing capacity (throughput). * **IAM Optimization:** We have optimized the encoding of each validation layer of IAM (Identity and Access Management). * **Blob Performance:** Direct actions on the Blob are 20-35% faster, and full logging has been implemented. ### API and Environment Improvements * **New Query for Application Status:** The `/v2/apps/status` route now accepts the `"workspaceId"` query to facilitate state data collection. * **Clearer Error Messages:** Environments now return specific error messages like `"CONTAINER_ALREADY_STARTED"` or `"CONTAINER_ALREADY_STOPPED"`, instead of the generic `"ACTION_FAILED"`, for direct scenarios. Fun facts about Square Cloud: Even though this is the Square Cloud community server, we are currently the **second largest programming server on the Brazilian Discord**, behind only Rocketseat. ### API Update – Extended Support for Workspaces We are excited to announce the addition of new API routes to facilitate the complete management of **workspaces**, **applications**, and **members**. This update provides greater control and flexibility for developers and team administrators. ### Workspaces * `GET /v2/workspaces`: Lists all workspaces of the authenticated user. * `GET /v2/workspaces/:workspaceId`: Retrieves the details of a specific workspace. * `POST /v2/workspaces`: Creates a new workspace. **Body:** `{ name: string }` **Validation:** Name must follow the regex `/^[\w ]{1,32}$/`. * `DELETE /v2/workspaces`: Removes an existing workspace. **Body:** `{ workspaceId: string }` * `DELETE /v2/workspaces/leave`: Allows a user to leave a workspace. **Body:** `{ workspaceId: string }` ### Workspaces – Applications * `POST /v2/workspaces/applications`: Associates an application with a workspace. **Body:** `{ workspaceId: string, appId: string }` * `DELETE /v2/workspaces/applications`: Removes an application from a workspace. **Body:** `{ workspaceId: string, appId: string }` ### Workspaces – Members * `GET /v2/workspaces/members/code`: Generates an invitation code for new members to join a workspace. * `POST /v2/workspaces/members`: Adds a new member to the workspace using an invitation code. **Body:** `{ workspaceId: string, code: string, group: string }` * `PATCH /v2/workspaces/members`: Updates a member's group within the workspace. **Body:** `{ workspaceId: string, memberId: string, group: string }` * `DELETE /v2/workspaces/members`: Removes a member from the workspace. **Body:** `{ workspaceId: string, memberId: string }` Workspaces now adopt Square's unique ID model (40 characters). Square no longer deletes a workspace when its creator's plan expires. By default, **we have reset all teams on the platform**, meaning: **teams created before this update milestone have been deleted**. These changes aim to make workspace management more robust, collaborative, and efficient. 🚀 General changes: * New route for GLOBAL listing of backups: `/v2/users/backups` (GET). * The global application status listing route now defaults to listing only your applications; workspace applications require the `workspaceId` query. For more technical details, consult the official API documentation. > A new documentation update is expected to be published within 24 hours. ## Environment Update We are always improving our services to ensure you have access to the latest and most stable versions of the main programming languages. Check out what's new in this update! ### New versions available: * **JavaScript \[Node.js]** → Recommended: 22.15.1 | Latest: 24.0.2 * **Python** → Recommended: 3.13.3 | Latest: 3.13.3 * **Elixir** → Recommended: 1.18.3 | Latest: 1.18.3 * **Rust** → Recommended: 1.87.0 | Latest: 1.87.0 * **PHP** → Recommended: 8.4.7 | Latest: 8.4.7 * **Go** → Recommended: 1.24.3 | Latest: 1.24.3 ### New for PHP environments: Node.js v22 updated & npm updated by default. COMPOSER\_HOME set to application (base of your project), we also improved the general interoperability of PHP environments. 1. * Extensions active by default: `pdo`, `pdo_mysql`, `pdo_pgsql`, `pdo_sqlite`, `pgsql`, `mysqli`, `mbstring`, `exif`, `pcntl`, `bcmath`, `gd`, `zip`, `opcache`, `sockets`, `intl`, `ldap`, `xml`, `tidy`, `xsl`, `gmp`, `sodium`, `curl`, `ctype`, `fileinfo`, `posix`, `simplexml`, `xmlreader`, `xmlwriter`, `dom`. 2. Libraries and dependencies have been improved, ensuring better integration with PHP frameworks. List: `build-essential`, `git`, `curl`, `wget`, `unzip`, `sqlite3`, `libonig-dev`, `libsqlite3-dev`, `libpq-dev`, `libzip-dev`, `libpng-dev`, `libjpeg-dev`, `libfreetype6-dev`, `zlib1g-dev`, `libssl-dev`, `libcurl4-openssl-dev`, `libldap2-dev`, `unixodbc-dev`, `libicu-dev`, `libxslt-dev`, `libtidy-dev`, `libmemcached-dev`, `libxml2-dev`, `libevent-dev`, `libgmp-dev`, `libreadline-dev`, `libargon2-dev`, `libsodium-dev`, `ca-certificates`, `gnupg`, `nodejs`. 💡 **What does this mean for you?** * More stability and security in all environments. * More compatibility for modern and production-focused applications. The updates are already available. 😄 Note: Redis support will be released soon in version 7.4.0, initially in open testing with users. ## Technical and general balancing changes. Over the past week, we have made a series of adjustments aimed at improving the performance and stability of our API. Here are the main highlights: `/v2/apps/status` * Now returns statuses in **real-time**, without using cache. * New limit of **15 requests per 60 seconds** (rate class: `KEEP CALM`). `/v2/apps/:appId/logs` * Reduced cooldown between requests: from **10s to 5s**. `/v2/apps/:appId/metrics` * **Increased rate and throughput**. * Output now with **compression enabled**. * New limit: **10 requests every 5 seconds**. `/v2/apps/:appId/commit` * Cooldown reduction: from **5s to 3 seconds**. POST `/v2/apps` * Cooldown reduction: from 10s → 5s → **now: 3 seconds**. DELETE `/v2/apps/:appId` * New execution limit: **1 request per second**. * This prevents human errors that could cause serious impacts on the integrity of the user's applications. We have also globally updated some important topics on Square Cloud. **1. Custom domains:** The system now **automatically removes** domains with pending, inactive, deleted, or moved DNS for more than **24h**. **2. GitHub Integration:** Global cooldown reduced between deploys of the same ID: 90s → 60s → **now: 30 seconds**. **3. Deploys (globally) and general commits:** Fixed an issue where poorly formatted requests (e.g., incorrect `Content-Type`) resulted in **proxy timeouts**. We now return a clear and developer-friendly error, with an error code for correction. **4. Invoices:** The service description now displays the **account ID**, replacing the email. This change aims to avoid validation errors caused by limitations of the Goiânia City Hall with certain characters. **5. Global compression:** Note: this was **included for free in all plans**, at no cost and with no limits. * We have enabled an extra layer of compression on our API responses, websites on our infrastructure, and web assets. * You should notice improved responses from your web applications (specifically APIs that return a lot of data for download). * Compression is applied only if possible, in the order: **ZSTD → Brotli → Gzip → \[no compression]**. (it is exactly in this order). Fun facts about Square Cloud: Did you know that Square Cloud is the largest Discord bot hosting platform in Latin America? 🥰 Note: We never really imagined we would grow so much. We also never invested heavily in marketing, which is quite evident if we analyze some numbers and work with triangulated data, we can state with good accuracy that: about **70% of our customers come from recommendations**. These improvements reinforce our commitment to the performance, clarity, and security of your experience with Square Cloud. ## User experience improvement. We took advantage of the last few days of the holiday to focus on improving the overall experience of our site, bringing important improvements that make navigation more fluid, fast, and intuitive. 1. New Redeem page. `/account/redeem` We completely removed that annoying button and modal from the control panel's home page and created an exclusive page for redeeming codes. 2. New Dashboard layout. We have significantly improved the experience on mobile devices; the control panel's home page now takes up less initial space, improving the browsing experience. We also fixed several issues that caused strangeness in the loading of some functions. 3. Actions in the context menu. It is now possible to perform quick actions such as: start, restart, and stop an application directly from the 3 dots of an application in the control panel. 4. Improved log viewing The application's 'Logs' tab has been significantly improved, providing a clearer view of the records and much faster loading. 4. Blob Calculator. The Blob service page now has a new layout and a very cool calculator, allowing you to get an idea of a future cost you might have using our Blob service. It is worth noting that the price per GB and Objects has not yet been fully defined. (There is no active billing for Blob). We have also improved the plan renewal experience and fixed several front-end bugs that impacted this action on our site. In addition, we have made optimizations that improved the overall performance of the platform. Other miscellaneous updates: 1. We improved the invoice experience; now an invoice is automatically canceled 24 hours after its creation date (in case of non-payment). 2. We improved the general stability of our API and reduced infrastructure costs by 27% using new stream handling algorithms and reducing the cost of repetitive actions. 3. We fixed a bug that resulted in an IP swap below a safe margin in the clusters, which caused a 'rebound' effect and the same application received the same IP in some specific scenarios. In simpler terms: we improved the stability of the entire network. 😌 Fun fact about Square Cloud: In the last 7 days, we processed 532 million and 59 thousand requests in our infrastructure. A very impressive number, right? 🤪 > What do you think about me bringing a random fun fact in every changelog? I think it's a cool way to bring the community closer. ## Overhaul of error pages. We have changed the functionality and improved the experience of all error pages within the web scope of our platform. 1. "This site could be yours." When accessing a subdomain (squareweb.app) that does not yet exist, visitors will see an elegant and explanatory page stating that the address is available, meaning: it can be easily activated through a deploy. A simple and intuitive way to show the potential of Square Cloud. (and obviously make your life as a developer easier) 2. "The site took too long to respond..." If your website is misconfigured (for example, listening on the wrong port or host) or experiences momentary instabilities, your visitors will no longer see a cold error screen. Instead, we automatically show a page translated into several languages, clearly explaining what happened, and better yet: with an automatic reconnection attempt after a few seconds. This reduces traffic loss and improves the perception of your site even during occasional failures. All of this is part of our commitment to delivering an increasingly intelligent, practical, and user-focused platform. 💙 3. Optimized traffic and exclusive routing. We have significantly optimized the network traffic between our clusters and proxies, reducing latency and making content delivery even more efficient and faster for all sites hosted on Square Cloud. Now, your visitors access your site more quickly, regardless of location or access volume. And for those who like technical curiosities: in the last 30 days, Square Cloud processed more than **5.41 billion requests**. This is equivalent to about **67% of the world's population**, considering the current 8 billion inhabitants of Earth. 😎 ps.: it's as if for every 2 people on planet earth, 1 and a half people (don't divide a person ok) had sent a request to our services, that's a lot 😌 ## Dashboard Update We are always improving our dashboard to ensure you have the best possible experience. Check out what's new in this update! 1. **You can now favorite applications:** Favorite applications by browser/device directly on the dashboard. Just click the 3 dots (`···`) and select the `Favorite` option. > In the future, we will sync this across all devices. 2. **You can now import your project directly via GitHub:** You can import projects from GitHub by clicking "Import via GitHub" on the upload page or by accessing the link directly: [Import via GitHub](https://squarecloud.app/en/dashboard/new?type=github). 3. **Improvement in the session disconnect function:** For security reasons, you can now disconnect all your sessions simultaneously and immediately if you suspect any abnormal activity in your account, an option available 4. **New My Account tab:** The Square Cloud account page has been completely redesigned to make your navigation simpler and more organized. It is now divided into specific sections, with dedicated routes for each feature: * **Account Information** — `/account` View and edit your personal data and account preferences. * **Blob Storage** — `/account/blob` Manage your stored files and data conveniently. * **My Invoices** — `/account/invoices` Track your payment history, plans, and download receipts. * **Account Connections** — `/account/connections` View and control all integrations connected to your account. * **Security and Authentication** — `/account/security` Manage your account code, API key, and active sessions securely. 5. **Billing history available:** You can now view all your invoices directly on the [Invoices](https://squarecloud.app/en/account/invoices) page. 6. **New design for PIX payments:** The PIX payment page has been redesigned with a more modern and intuitive design. 7. **Improvement in the Blob file manager:** Now when uploading a file to blob storage through our dashboard, if the file name field is empty, the system will automatically fill the field with the original name of the attached file. We have also improved the feedback when deleting multiple files from blob storage, offering more clarity and speed in the action. ## General Latency Update We optimized the infrastructure behind backups, deploys, and blob storage, improving distribution placement and delivering significant performance gains. Other important general improvements: 1. **Monitoring and notifications via emails.**: > Note: included for FREE in ALL plans, we do not charge for this. 😉😆 In short: we now send informational emails if your application faces RAM, CPU, or network problems, ensuring faster and more efficient responses to any incident. 2. **Complete rewrite of Blob Storage**: Usage status update: Now, usage statuses, which were previously updated every 12 hours, are updated every 1 minute, providing more real-time information. Object deletion: The object deletion route no longer allows bulk deletions of up to 100 items. The deletion of each object is done individually, preventing abuse and optimizing the load on our infrastructure. New security standard: We have implemented a new method for generating security hashes, which now generates a hash 16 times larger than the previous one, making our private assets more secure. 3. **Performance and Latency**: Asset upload: The latency for uploading assets has been reduced by an average of 23%, providing a faster experience for uploading and accessing your data. Asset retrieval: The response time when accessing asset URLs has been accelerated by up to 30% in various scenarios, due to infrastructure routing improvements and ongoing regional delivery tests. Application metrics: The **application metrics** have been rewritten and are now **returned, on average, in 200ms, compared to the previous 800ms**, providing a faster and more efficient view of your applications' performance. 4. **Future Expansion**: We are planning to further expand our global infrastructure, which will allow us to eliminate the dependency on external caches like Cloudflare, ensuring that your assets, even with a size greater than 100MB, can be delivered without additional network costs. We also fixed an error that generated an "Access Denied" return in the API, when, in fact, it should have been a "RateLimit" (429) in some cases. Now, the API behavior is appropriate for these scenarios. ## Update on Restrictions Sections In order to increase transparency and compliance with international standards, we are announcing a review of our trade restriction guidelines. From now on, we will provide more details on the prohibitions dictated by legislation such as the FCPA, IEEPA, EAR, and other relevant guidelines that influence the trade and use of our services by information technology companies. Additionally, we are expanding existing restrictions, based on practices already established by United States companies, to ensure that our operations meet the criteria of the global market. These changes aim to reinforce security, legal compliance, and transparency in international transactions, especially in relation to countries under sanctions. With resilient data center infrastructure and a strict commitment to standards, Square Cloud remains dedicated to providing a safe and compliant environment for all our users. It is important to note that, although we are a 100% Brazilian company, our operations follow the local and international legislation applicable to our services. ## General stability update We have increased the base log limit (via API) to `1000 lines`. (previously: `100 lines`). We have globally removed the `requests` parameter from our API (sent in the status route) (deprecated for \~6 months). We have reduced the ratelimit for GitHub integrations (via webhook) to `60 seconds`. (previously: `90 seconds`). Square Cloud no longer sends `SIGTERM` signals with a `5-second` deadline. As of today (03/22/2025), we send the `SIGINT` signal with a `3-second` timeout. This was done to ensure better compatibility with various frameworks and for greater overall stability. Square Cloud now fully forces permissions on all commits and initializations (no longer just on the out-of-execution scope), meaning: we force permissions even if your application is completely running/stopped equally, reducing the probability of EACCESS or similar errors. We also applied a new startup logic, reducing the overall load. ⚠️ **Addendum for Next.js users: [https://nextjs.org/blog/cve-2025-29927](https://nextjs.org/blog/cve-2025-29927)** ## Update on limits We have great news: **we have increased the API request limits** on all plans, and best of all... **at no additional cost!** 🎉 Now you can make many more requests per day! Check out the new numbers based on the daily limit increase: * **Standard:** 144,000 req/day (+14,400 requests/day added) * **Advanced:** 216,000 req/day (new plan) * **Pro:** 432,000 req/day (+216,000 requests/day added) * **Enterprise-24:** 864,000 req/day (new plan) * **Enterprise-32:** 1,152,000 req/day (+864,000 requests/day added) The **Enterprise category will now proportionally support** up to ****36,864,000 requests per day****; previously the highest limit was: 2,448,000 million. Other changes: * The Hobby plan will no longer support the workspace system (formerly teams) and will not have access to the billable [Blob](https://squarecloud.app/blob) (it will still have access to the free quota), as it is being changed to a personal use focus plan. In contrast, we have increased the member limits per workspace for all plans: * **Advanced:** will support 5 members/workspace. * **Pro:** will support 7 members/workspace. * **Enterprise-24:** will support 10 members/workspace. Enterprise 32, 48, 64, 160 and above will support: 15, 20, 30, and infinite/members per workspace. This update ensures greater scalability for your projects, allowing you to focus exactly on your maximum efficiency. 😎 ## Proxies We have completely rewritten all of Square Cloud's proxies **from scratch**, bringing a more efficient, stable, and scalable infrastructure. This change covers all proxies on the platform, including: * 🌐 **squareweb.app (subdomains)** – Better performance and lower latency for web applications. * 🔗 **Custom domains** – New optimized routing, ensuring faster response times. * 🏗 **Individual clusters** – Each cluster now has an exclusive dedicated proxy, distributing the load better. In addition to the structural improvements, **we have expanded our capacity to support more than 100 billion monthly requests without any expected issues**, a significant advance from the previous theoretical limit of approximately **23 billion**. This update ensures greater stability, security, and scalability, allowing our users to operate with maximum efficiency. 😎 ## Compliance In compliance with LGPD, GDPR, and other applicable laws, we inform you that we have removed 40,667 accounts that have been inactive for more than 730 days (2 years) from our platform. This action reinforces our commitment to privacy, data security, and regulatory compliance. ## Infrastructure We have updated our entire infrastructure to ensure greater efficiency and performance. With this update, we have improved the base latency between clusters, reducing the internal interaction response time by approximately 2 to 5 ms, which optimizes various operations, especially for more advanced users. In addition, we have made strategic improvements to our proxy flow, preparing Square Cloud to handle traffic volumes exceeding 5 billion monthly requests. Currently, our infrastructure processes about 1.3 billion requests per month, and these optimizations will ensure scalability, resilience, and improved performance for our users. ## Dashboard Our dashboard has undergone several improvements to offer a more agile, intuitive, and efficient experience. Check out the main new features: 🔹 **New improved interface** * Small visual refinements to make navigation more fluid and accessible. * Better organization of information to facilitate the management of your projects. * New exclusive section for account management ("My Account"). **Optimized performance** * We have reduced page loading times, ensuring greater speed in displaying your data. * We have improved real-time synchronization, providing faster and more accurate updates. 🛠️ **New features and adjustments** * We have improved the logging system, allowing for more detailed and efficient monitoring. * Minor bugs have been fixed to ensure more stability and reliability. **Discord Connection** Get your wonderful role by connecting your Discord account to your Square Cloud account 🙂 Go to: [https://squarecloud.app/en/account](https://squarecloud.app/en/account), scroll down the page and make the connection. \*as this is a test connection, Square may reset the connection in case of failure during this authorization period 😄 ## Environment Update We are always improving our services to ensure you have access to the latest and most stable versions of the main programming languages. Check out what's new in this update! ### New versions available: * **JavaScript \[Node.js]** → Recommended: 22.13.1 | Latest: 23.7.0 * **Python** → Recommended: 3.13.1 | Latest: 3.13.1 * **Java** → Recommended: JDK 23 | Latest: JDK 25 * **Elixir** → Recommended: 1.18.1 | Latest: 1.18.1 * **Rust** → Recommended: 1.84.1 | Latest: 1.84.1 * **PHP** → Recommended: 8.4.3 | Latest: 8.4.3 * **Go** → Recommended: 1.23.6 | Latest: 1.23.6 * **C#** → Recommended: 9.0.1 | Latest: 9.0.1 * **HTML/CSS** → Build 10-02-2025 ### New for static sites: The environment now supports the `vite.html` file, making it easier to host sites exported by **Vite**. Additionally, a `404.html` will be created by default to improve the browsing experience. 💡 **What does this mean for you?** * More stability and security in all environments. * More compatibility for modern and production-focused applications. The updates are already available. 😄 # Manage applications from the CLI Source: https://docs.squarecloud.app/en/cli-reference/apps List your Square Cloud applications, show their details, start, stop or restart them and delete the ones you no longer need with squarecloud app. `[appID]` is optional in every command on this page except `list`: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## `squarecloud app list` ```bash Usage theme={"system"} squarecloud app list [--json] ``` Prints a table of every application in your account: name, app ID, memory, cluster, language and domain (the custom domain when there is one). ```bash theme={"system"} squarecloud app list --json # Prints the raw application list as JSON. ``` ## `squarecloud app info` ```bash Usage theme={"system"} squarecloud app info [appID] [--json] ``` Shows the application ID, name, description, language, memory, cluster, owner, domain, custom domain and creation date. ```bash theme={"system"} squarecloud app info --json # Prints the raw application object as JSON. ``` ## `squarecloud app start` ```bash Usage theme={"system"} squarecloud app start [appID] ``` Starts a stopped application. ```bash Output theme={"system"} ✓ Signal START has been successfully sent to your application. ``` If the application is already running, the CLI says so (`It is already running.`) and exits with code 0. Other refusals from the platform are reported as errors. ## `squarecloud app stop` ```bash Usage theme={"system"} squarecloud app stop [appID] ``` Stops a running application. If it is already stopped, the CLI says so (`It is already stopped.`) and exits with code 0. ## `squarecloud app restart` ```bash Usage theme={"system"} squarecloud app restart [appID] ``` Restarts the application's process. To send new code and restart in one step, use [`squarecloud commit --restart`](/en/cli-reference/deploy#squarecloud-commit). ## `squarecloud app delete` ```bash Usage theme={"system"} squarecloud app delete [appID] [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Deleting an application is permanent, and the CLI doesn't take a snapshot first. To keep a copy, run [`squarecloud app snapshot create --download`](/en/cli-reference/snapshots#squarecloud-app-snapshot-create) before deleting. Asks `Delete the application ? This action is irreversible [y/N]` before deleting. Without an ID, the command targets the application in the `ID=` line of the current folder, so check the ID in the question. ```bash theme={"system"} squarecloud app delete -y # Deletes without asking, for scripts. ``` ```bash Output theme={"system"} ✓ Your application has been deleted. ``` ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `list` | [`GET /v2/users/me`](/en/api-reference/endpoint/users/me) | [`api.account.me()`](/en/sdks/js/client) | [Side bar](/en/vscode-extension/features#applications) | | `info` | [`GET /v2/apps/{app_id}`](/en/api-reference/endpoint/apps/info) | [`api.apps.get()`](/en/sdks/js/managing_application) | Click an application card | | `start` | [`POST .../start`](/en/api-reference/endpoint/apps/start) | [`api.apps.start()`](/en/sdks/js/managing_application) | [Start](/en/vscode-extension/features#applications) | | `stop` | [`POST .../stop`](/en/api-reference/endpoint/apps/stop) | [`api.apps.stop()`](/en/sdks/js/managing_application) | [Stop](/en/vscode-extension/features#applications) | | `restart` | [`POST .../restart`](/en/api-reference/endpoint/apps/restart) | [`api.apps.restart()`](/en/sdks/js/managing_application) | [Restart](/en/vscode-extension/features#applications) | | `delete` | [`DELETE /v2/apps/{app_id}`](/en/api-reference/endpoint/apps/delete) | [`api.apps.delete()`](/en/sdks/js/managing_application) | [Delete](/en/vscode-extension/features#applications) | # Log in to the Square Cloud CLI Source: https://docs.squarecloud.app/en/cli-reference/authentication Log in to the Square Cloud CLI from the browser, with an API key or through SQUARECLOUD_API_KEY in CI, check the current account and renew an expired key. Run the login command in your terminal: ```bash theme={"system"} squarecloud auth login ``` The CLI shows a short code and opens the authorization page in your browser. Type the code on the page and approve. The CLI receives its own API key, no copy and paste needed, and saves it on this machine. ```bash Output theme={"system"} ✓ Logged in as . This API key expires on . ``` A key issued this way has only the permissions the CLI's commands use and expires after **90 days**. [`auth whoami`](#squarecloud-auth-whoami) shows the date; run `squarecloud auth login` again to renew it. The key is saved in a `config.json` file readable only by you: in `%APPDATA%\Square Cloud CLI` on Windows, and in `$XDG_CONFIG_HOME/squarecloud` or `~/.config/squarecloud` on macOS and Linux. ## `squarecloud auth login` ```bash Usage theme={"system"} squarecloud auth login [--no-browser] [--token | --with-token] [-y] ``` | Flag | Description | | - | - | | `--no-browser` | Prints the authorization link without opening a browser. Use it in SSH sessions and containers, and open the link on any device. | | `--token ` | Logs in with an API key you created in the [dashboard](https://squarecloud.app/en/account/security). The key is checked before it is saved. | | `--with-token` | Reads the API key from stdin, for scripts. Can't be combined with `--token`. | | `-y`, `--yes` | Replaces the saved key of another account without asking. | ```bash theme={"system"} squarecloud auth login --token # Logs in with an existing API key. ``` ```bash theme={"system"} echo "$SQUARECLOUD_KEY" | squarecloud auth login --with-token # Reads the API key from stdin. ``` ```bash Output with an API key theme={"system"} API key saved. You are now logged in as . With great power comes great responsibility! ``` * Press `Ctrl+C` to cancel a login that is waiting for approval. * If this machine is already logged in to another account, `auth login` asks before replacing it. Pass `-y` to skip the question. * If your account has reached its API key limit, the browser login says so and continues on its own as soon as you revoke a key in the [dashboard](https://squarecloud.app/en/account/security). * Without a terminal, the command doesn't prompt: it exits with a hint. With `CI=true`, the browser login refuses to run. See [CI and scripts](#ci-and-scripts). ## `squarecloud auth whoami` ```bash Usage theme={"system"} squarecloud auth whoami [--json] ``` Shows the account you are logged in as, its plan and how many days are left before the plan expires. For a key issued by the browser login, it also shows when the key expires and its scopes; when the key comes from `SQUARECLOUD_API_KEY`, it says so instead. ```bash Output theme={"system"} You are currently logged in as on the plan. You have days left before your plan expires. Your API key expires on . Scopes: ``` With `--json`, it prints the account (ID, name, email, locale, plan and creation date) as JSON. ## `squarecloud auth logout` ```bash Usage theme={"system"} squarecloud auth logout ``` Removes the saved API key from this machine. It doesn't revoke the key: to do that, delete it in the [dashboard](https://squarecloud.app/en/account/security). When `SQUARECLOUD_API_KEY` is set, commands keep using it after a logout. ```bash Output theme={"system"} You have successfully logged out of your Square Cloud account. ``` When no account is connected, it prints `No account is connected on this machine.` and exits with code 0. ## CI and scripts In CI, don't log in at all: create an API key in the [dashboard](https://squarecloud.app/en/account/security) and set it in the `SQUARECLOUD_API_KEY` environment variable. Every command uses it instead of the saved key, and the CLI runs even on machines without a home folder. ```bash theme={"system"} export SQUARECLOUD_API_KEY= squarecloud commit --restart ``` * Without a terminal, `auth login` doesn't prompt for anything: it exits with a hint. Use `--with-token`, `--token` or `SQUARECLOUD_API_KEY`. * With `CI=true`, the browser login refuses to run, since its key expires in 90 days and only a person can renew it. More on exit codes and JSON output in [Global flags and CI](/en/cli-reference/global-flags-and-ci#scripts-and-ci). ## When the key stops working If a command says your session expired or the API key was revoked, run `squarecloud auth login` again. Commands that need an account print `You need to be logged in to run this command.` and exit with code 1 when no key is saved or set. ## Related | Task | API | JavaScript SDK | VS Code | | - | - | - | - | | Show the current account | [`GET /v2/users/me`](/en/api-reference/endpoint/users/me) | [`api.account.me()`](/en/sdks/js/client) | Status bar item | | Log in | [API keys](/en/api-reference/authentication) | [`new SquareCloudAPI(key)`](/en/sdks/js/client) | [Connect Account](/en/vscode-extension/installation#install) | # Manage databases from the CLI Source: https://docs.squarecloud.app/en/cli-reference/databases Create, inspect, resize, start, stop and delete Square Cloud databases with squarecloud db, and print or rotate their TLS certificate and password. `squarecloud db` manages the MongoDB, MySQL, PostgreSQL and Redis databases of your account. It also works as `squarecloud database`. Databases have no configuration file, so `[dbID]` is either the ID you pass or, when you omit it in a terminal, a picker of your databases. Find IDs with [`squarecloud db list`](#squarecloud-db-list). ## `squarecloud db create` ```bash Usage theme={"system"} squarecloud db create --name --memory --type --version [--json] ``` | Flag | Description | | - | - | | `--name ` | Database name, 1 to 32 characters. | | `--memory ` | Allocated memory in MB. | | `--type ` | `mongo`, `mysql`, `redis` or `postgres`. | | `--version ` | Engine version: a major version, such as `17` for PostgreSQL or `8` for MongoDB, or a full version. | All four flags are required: without them, the command prints its help. Creating a database needs a Standard, Pro or Enterprise plan. ```bash theme={"system"} squarecloud db create --name my-db --memory 1024 --type postgres --version 17 ``` ```bash Output theme={"system"} ✓ Database my-db () created successfully Save the password now: it is shown only once and cannot be recovered. PASSWORD: URL: ``` The password is shown only once. `db info` doesn't show it again; if you lose it, rotate it with [`db credentials reset password`](#squarecloud-db-credentials-reset). With `--json`, it prints the created database, password and connection URL included, as JSON. ## `squarecloud db list` ```bash Usage theme={"system"} squarecloud db list [--json] ``` Prints the name, ID, engine, memory and cluster of every database in your account. ## `squarecloud db info` ```bash Usage theme={"system"} squarecloud db info [dbID] [--json] ``` Shows the database ID, name, engine, memory, port, cluster, owner and creation date. ## `squarecloud db update` ```bash Usage theme={"system"} squarecloud db update [dbID] [--name ] [--memory ] ``` | Flag | Description | | - | - | | `--name ` | New database name. | | `--memory ` | New allocated memory in MB. | Renames the database or changes its memory. Pass at least one of the two flags: without them, the command prints its help. ```bash theme={"system"} squarecloud db update --memory 2048 ``` ## `squarecloud db start` ```bash Usage theme={"system"} squarecloud db start [dbID] ``` Starts a stopped database. If it is already running, the CLI says so (`It is already running.`) and exits with code 0. ## `squarecloud db stop` ```bash Usage theme={"system"} squarecloud db stop [dbID] ``` Stops a running database. If it is already stopped, the CLI says so (`It is already stopped.`) and exits with code 0. ## `squarecloud db status` ```bash Usage theme={"system"} squarecloud db status [dbID] [--all] [--raw] [--json] ``` | Flag | Description | | - | - | | `--all` | Shows every database instead of one: database ID, whether it is running, CPU and memory. | | `--raw` | Prints the raw numeric stats as JSON instead of the table. | Prints the database ID, CPU usage, memory, disk and status. ## `squarecloud db metrics` ```bash Usage theme={"system"} squarecloud db metrics [dbID] [--json] ``` Prints the last 24 hours of the database's CPU usage, RAM usage and network traffic, one row per 5-minute data point. ## `squarecloud db credentials certificate` ```bash Usage theme={"system"} squarecloud db credentials certificate [dbID] ``` Prints the database's TLS certificate, which clients use to connect over TLS. ```bash theme={"system"} squarecloud db credentials certificate > certificate.pem # Saves the certificate to a file. ``` ## `squarecloud db credentials reset` ```bash Usage theme={"system"} squarecloud db credentials reset [dbID] [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Rotates the password or the TLS certificate, after a `y/N` confirmation. The old one stops working immediately, so update every client that uses it. A new password is printed once; after rotating the certificate, get the new one with `db credentials certificate`. ```bash theme={"system"} squarecloud db credentials reset password ``` ## `squarecloud db delete` ```bash Usage theme={"system"} squarecloud db delete [dbID] [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Deleting a database is permanent. To keep a copy of the data, run [`squarecloud db snapshot create --download`](/en/cli-reference/snapshots#squarecloud-db-snapshot-create) first. Asks `Delete the database ? This action is irreversible [y/N]` before deleting. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `create` | [`POST /v2/databases`](/en/api-reference/endpoint/databases/create) | [`api.databases.create()`](/en/sdks/js/databases) | [Create database](/en/vscode-extension/features#databases) | | `list` | [`GET /v2/users/me`](/en/api-reference/endpoint/users/me) | [`api.account.me()`](/en/sdks/js/client) | [Databases section](/en/vscode-extension/features#databases) | | `info` | [`GET .../{database_id}`](/en/api-reference/endpoint/databases/info) | [`api.databases.get()`](/en/sdks/js/databases) | | | `update` | [`PATCH .../{database_id}`](/en/api-reference/endpoint/databases/edit) | [`api.databases.update()`](/en/sdks/js/databases) | | | `start` | [`POST .../start`](/en/api-reference/endpoint/databases/start) | [`api.databases.start()`](/en/sdks/js/databases) | [Start](/en/vscode-extension/features#databases) | | `stop` | [`POST .../stop`](/en/api-reference/endpoint/databases/stop) | [`api.databases.stop()`](/en/sdks/js/databases) | [Stop](/en/vscode-extension/features#databases) | | `status` | [`GET .../status`](/en/api-reference/endpoint/databases/status) | [`api.databases.status()`](/en/sdks/js/databases) | | | `status --all` | [`GET /v2/databases/status`](/en/api-reference/endpoint/databases/status-all) | [`api.databases.statusAll()`](/en/sdks/js/databases) | | | `metrics` | [`GET .../metrics`](/en/api-reference/endpoint/databases/metrics) | [`api.databases.metrics()`](/en/sdks/js/databases) | | | `credentials certificate` | [`GET .../credentials/certificate`](/en/api-reference/endpoint/databases/credentials/get_certificate) | [`api.databases.certificate()`](/en/sdks/js/databases) | [Download TLS certificate](/en/vscode-extension/features#databases) | | `credentials reset` | [`POST .../credentials/reset`](/en/api-reference/endpoint/databases/credentials/reset) | [`api.databases.resetCredentials()`](/en/sdks/js/databases) | | | `delete` | [`DELETE .../{database_id}`](/en/api-reference/endpoint/databases/delete) | [`api.databases.delete()`](/en/sdks/js/databases) | [Delete](/en/vscode-extension/features#databases) | Snapshots of databases are on [Snapshots](/en/cli-reference/snapshots#squarecloud-db-snapshot-create). # Upload and update apps from the CLI Source: https://docs.squarecloud.app/en/cli-reference/deploy Deploy a folder as a new Square Cloud app with squarecloud upload, send changes with squarecloud commit and check what the zip contains with squarecloud zip. * **`upload`** creates a **new** application, with a new ID. * **`commit`** sends files to an application that **already exists** and keeps its ID, domain and settings. * **`zip`** builds the same zip locally, without sending it, so you can check what goes in. `upload` and `commit` also exist under `squarecloud app` (`squarecloud app upload`, `squarecloud app commit`). New here? Start with the [Quickstart](/en/cli-reference/quickstart). ## What goes in the zip `upload`, `commit` and `zip` zip the current folder and leave out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore), in the project root, lists. It uses `.gitignore` syntax and is the same file the [VS Code extension](/en/vscode-extension/features#ignore-rules) reads. * **Always left out first:** `node_modules`, `.git`, `.github`, `.vscode`, `package-lock.json`, `pnpm-lock.yaml` and `yarn.lock`. Dependencies are installed on the platform from your manifest. To send a lockfile because you need pinned versions, add a `!` rule, such as `!package-lock.json`. * **Links:** a symbolic link to a file is zipped as that file; links to folders and broken links are skipped with a note on stderr. * **Older file names** (`.squareignore`, `.squarecloudignore`, `square.ignore`) are still read when `squarecloud.ignore` is missing, with a warning to rename the file. ## `squarecloud upload` ```bash Usage theme={"system"} squarecloud upload [--file ] [--json] ``` Zips the current folder and creates a new application from it. The folder needs a [`squarecloud.app` or `squarecloud.config`](/en/getting-started/config-file) file. | Flag | Description | | - | - | | `--file ` | Uploads a zip you already have instead of zipping the current folder. Relative and absolute paths both work. | ```bash theme={"system"} squarecloud upload # Zips the current folder and deploys it as a new application. ``` ```bash theme={"system"} squarecloud upload --file ./build/my-app.zip # Uploads an existing zip. ``` ```bash Output theme={"system"} Compressing the current directory. Uploading the zip file to Square Cloud. ✓ Application uploaded to Square Cloud! Open it at https://squarecloud.app/dashboard/applications/ ``` After a successful upload, the CLI writes `ID=` into the configuration file of the current folder, so later commands know which app you mean. See [where the app ID is saved](/en/cli-reference/quickstart#where-the-app-id-is-saved). With `--json`, stdout carries only the created application (ID, name, description, domain, cluster, memory, CPU and language) as JSON; progress messages go to stderr. ## `squarecloud commit` ```bash Usage theme={"system"} squarecloud commit [appID] [--file ] [--path ] [-r] ``` **Aliases:** `squarecloud push`, `squarecloud app commit`, `squarecloud app push` Zips the current folder and sends it to an existing application. The ID comes from the argument or from the `ID=` line of your configuration file. Unlike other commands, `commit` never opens a picker: without either, it stops with exit code 1. | Flag | Description | | - | - | | `--file ` | Sends one file instead of the current folder. A zip is extracted in the application; any other file is written under its own name. Relative and absolute paths both work. | | `--path ` | Commits into this folder of the application instead of its root. | | `-r`, `--restart` | Restarts the application after the commit. | ```bash theme={"system"} squarecloud commit # Sends the current folder to the app in the ID= line. ``` ```bash theme={"system"} squarecloud commit --restart # Sends the current folder to a specific app, then restarts it. ``` ```bash theme={"system"} squarecloud commit --file ./config.json --path settings # Sends one file into the settings folder of the app. ``` ```bash Output theme={"system"} Compressing the current directory. Committing to your application ()... Committed to your application. ``` Large commits are not cut off by a timeout. `commit` has no JSON output. ## `squarecloud zip` ```bash Usage theme={"system"} squarecloud zip ``` Zips the current folder the same way `upload` and `commit` do and saves it as `.zip` inside that folder, replacing an existing file with that name. It doesn't need a login. ```bash Output theme={"system"} ✓ Your project was zipped to ``` If the zip can't be written, the CLI prints `Couldn't zip your application.` with the reason; if an old `.zip` can't be deleted, it says so. Both exit with code 1. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `upload` | [`POST /v2/apps`](/en/api-reference/endpoint/apps/upload) | [`api.apps.create()`](/en/sdks/js/commit_and_upload) | [Upload New Application](/en/vscode-extension/features#upload-a-new-application) | | `commit` | [`POST /v2/apps/{app_id}/commit`](/en/api-reference/endpoint/apps/commit) | [`api.apps.commit()`](/en/sdks/js/commit_and_upload) | [Commit](/en/vscode-extension/features#commit-changes-to-an-existing-application) | To deploy on every push instead, see [GitHub deploys](/en/cli-reference/github-deploys). # Set up custom domains from the CLI Source: https://docs.squarecloud.app/en/cli-reference/domains Attach a custom domain to a Square Cloud website, read the DNS records to create, and list every domain and shared domain of your account from the terminal. A custom domain takes two steps: attach it to the application with `app network domain`, then create the DNS records that `app network dns` prints at your DNS provider. The help center has a [step-by-step custom domain guide](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) and explains [why a domain can take a while to propagate](https://help.squarecloud.app/en-us/article/why-hasnt-my-domain-propagated-yet-dns-f5jzoy/). `[appID]` and `--app` are optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## `squarecloud app network domain` ```bash Usage theme={"system"} squarecloud app network domain [--app ] ``` Sets the custom domain of the application, replacing the previous one. Custom domains are available on the Standard, Pro and Enterprise plans. To remove the custom domain, pass `@` as the hostname. ```bash theme={"system"} squarecloud app network domain www.example.com ``` ```bash Output theme={"system"} ✓ Custom domain www.example.com configured successfully Run 'squarecloud app network dns' to see the DNS records you need to create. ``` ## `squarecloud app network dns` ```bash Usage theme={"system"} squarecloud app network dns [appID] [--json] ``` Prints the DNS records to create for the custom domain, with the type, name, value and status of each one. Without a custom domain, it says to configure one first. ## `squarecloud app domains` ```bash Usage theme={"system"} squarecloud app domains [--json] ``` Lists every domain configured across all your applications: hostname, type and the ID of the application that owns it. ## `squarecloud app load-balancers` ```bash Usage theme={"system"} squarecloud app load-balancers [--json] ``` **Aliases:** `lb` Lists the custom domains attached to more than one application (load balancers), grouped by hostname, with the ID, name and cluster of each application sharing the domain. It starts with how many applications per domain your plan allows. ```bash theme={"system"} squarecloud app lb --json # Prints the raw load balancer list as JSON. ``` ## Related | Command | API | JavaScript SDK | | - | - | - | | `network domain` | [`POST .../network/custom`](/en/api-reference/endpoint/apps/network/custom) | [`api.apps.network.setDomain()`](/en/sdks/js/network) | | `network dns` | [`GET .../network/dns`](/en/api-reference/endpoint/apps/network/dns) | [`api.apps.network.dns()`](/en/sdks/js/network) | | `domains` | [`GET /v2/apps/domains`](/en/api-reference/endpoint/apps/domains) | [`api.apps.domains()`](/en/sdks/js/managing_application) | | `load-balancers` | [`GET /v2/apps/load-balancers`](/en/api-reference/endpoint/apps/network/load-balancers) | [`api.apps.loadBalancers()`](/en/sdks/js/managing_application) | Traffic, errors and cache of a website are on [Edge analytics](/en/cli-reference/edge-analytics). # Read edge analytics from the CLI Source: https://docs.squarecloud.app/en/cli-reference/edge-analytics Read the traffic, errors, request logs and latency of a Square Cloud website at the edge with squarecloud app network, and purge its edge cache. These commands report what Square Cloud's edge sees for a website: its `squareweb.app` domain and its custom domain. `[appID]` is optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## Time window `analytics`, `errors`, `logs` and `performance` cover the last 24 hours by default. Change the window with these flags, which take [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) times such as `2026-07-01T00:00:00Z`: | Flag | Description | | - | - | | `--start ` | Start of the window. Default: 24 hours ago. | | `--end ` | End of the window. Default: now. | The data goes back at most 7 days, and never before the application was created. ## `squarecloud app network analytics` ```bash Usage theme={"system"} squarecloud app network analytics [appID] [--start ] [--end ] [filters] [--json] ``` Prints the visits, requests and traffic of the window, followed by the top 10 countries. | Filter flag | Narrows the data to | | - | - | | `--country`, `--ip`, `--path`, `--status` | A country, client IP, path or HTTP status | | `--os`, `--browser`, `--protocol`, `--referer` | An operating system, browser, protocol or referer | | `--provider`, `--content-type`, `--bot` | A network provider, content type or bot | Each filter takes a value exactly as its breakdown in the `--json` output shows it, such as a two-letter country code (`BR`) or a three-digit status (`200`). Filters combine: the data must match all of them. ```bash theme={"system"} squarecloud app network analytics --start 2026-07-01T00:00:00Z --end 2026-07-02T00:00:00Z --country BR --status 200 # One day of Brazilian traffic answered with 200. ``` ```bash Output theme={"system"} Visits: | Requests: | Traffic: ``` ## `squarecloud app network errors` ```bash Usage theme={"system"} squarecloud app network errors [appID] [--start ] [--end ] [--include-4xx] [--json] ``` | Flag | Description | | - | - | | `--include-4xx` | Counts 4xx responses too. By default, only 5xx errors are counted. | Prints the total number of errors, split into 4xx and 5xx, and the 10 paths with the most errors. ```bash Output theme={"system"} Errors: total (<4xx> 4xx / <5xx> 5xx) ``` ## `squarecloud app network logs` ```bash Usage theme={"system"} squarecloud app network logs [appID] [--start ] [--end ] [--json] ``` Shows the edge request logs of the window: time, status, method, path, client IP and country. Available on the Pro and Enterprise plans. For your application's own output, see [`squarecloud app logs`](/en/cli-reference/logs#squarecloud-app-logs). ## `squarecloud app network performance` ```bash Usage theme={"system"} squarecloud app network performance [appID] [--start ] [--end ] [--json] ``` Shows the edge and origin latency percentiles (p50 and p95) and the 10 slowest paths with their p95 and p99. Available on the Pro and Enterprise plans. ```bash Output theme={"system"} Requests: | Edge p50/p95: / ms | Origin p50/p95: / ms ``` ## `squarecloud app network purge-cache` ```bash Usage theme={"system"} squarecloud app network purge-cache [appID] [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Purges the **entire** edge cache of the application, after a `y/N` confirmation. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `analytics` | [`GET .../network/analytics`](/en/api-reference/endpoint/apps/network/analytics) | [`api.apps.network.analytics()`](/en/sdks/js/network) | | | `errors` | [`GET .../network/errors`](/en/api-reference/endpoint/apps/network/errors) | [`api.apps.network.errors()`](/en/sdks/js/network) | [Edge errors](/en/vscode-extension/features#applications) | | `logs` | [`GET .../network/logs`](/en/api-reference/endpoint/apps/network/logs) | [`api.apps.network.logs()`](/en/sdks/js/network) | [Edge logs](/en/vscode-extension/features#applications) | | `performance` | [`GET .../network/performance`](/en/api-reference/endpoint/apps/network/performance) | [`api.apps.network.performance()`](/en/sdks/js/network) | [Edge performance](/en/vscode-extension/features#applications) | | `purge-cache` | [`POST .../network/purge_cache`](/en/api-reference/endpoint/apps/network/purge_cache) | [`api.apps.network.purgeCache()`](/en/sdks/js/network) | [Purge edge cache](/en/vscode-extension/features#applications) | Custom domains and DNS records are on [Domains](/en/cli-reference/domains). # Manage environment variables from the CLI Source: https://docs.squarecloud.app/en/cli-reference/environment-variables List, set, remove or replace the environment variables of a Square Cloud application with squarecloud app env, including loading them from a .env file. `squarecloud app env` manages the environment variables of an application. How your application reads them is covered in [Environment variables](/en/platform/environment-variables). `list` takes the app ID as its argument. `set`, `remove` and `replace` use their arguments for variables, so they take the ID with `--app`. Both are optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## `squarecloud app env list` ```bash Usage theme={"system"} squarecloud app env list [appID] [--json] ``` Prints each variable as `KEY=value`, sorted by name. ```bash theme={"system"} squarecloud app env list --json # Prints the variables as a JSON object. ``` ## `squarecloud app env set` ```bash Usage theme={"system"} squarecloud app env set KEY=VALUE... [--from-file ] [--app ] ``` | Flag | Description | | - | - | | `--from-file ` | Reads variables from a `.env` style file. `KEY=VALUE` arguments override the same keys from the file. | | `--app ` | The application to change. | Sets one or more variables and leaves the others as they are. ```bash theme={"system"} squarecloud app env set NODE_ENV=production PORT=80 # Sets two variables on the app in the ID= line. ``` ```bash theme={"system"} squarecloud app env set --from-file .env --app # Sets every variable of a .env file. ``` ```bash Output theme={"system"} ✓ Environment variables set: 2 ``` ## `squarecloud app env remove` ```bash Usage theme={"system"} squarecloud app env remove KEY... [--app ] squarecloud app env remove --all [--app ] [-y] ``` **Aliases:** `delete`, `unset` | Flag | Description | | - | - | | `--all` | Removes every variable of the application, after a confirmation. Can't be combined with variable names. | | `-y`, `--yes` | Skips the confirmation of `--all`. | | `--app ` | The application to change. | ```bash theme={"system"} squarecloud app env remove API_KEY OLD_FLAG # Removes two variables. ``` ## `squarecloud app env replace` ```bash Usage theme={"system"} squarecloud app env replace KEY=VALUE... [--from-file ] [--app ] [-y] ``` | Flag | Description | | - | - | | `--from-file ` | Reads variables from a `.env` style file. | | `-y`, `--yes` | Skips the confirmation prompt. | | `--app ` | The application to change. | Replaces the **entire** set of variables with the ones you pass: variables you don't list are removed. It asks for `y/N` confirmation first, and needs at least one variable. To remove every variable, use `remove --all`. ```bash theme={"system"} squarecloud app env replace --from-file .env --app -y # Makes the app's variables exactly the ones in .env, without asking. ``` ## Values with spaces and special characters Your application loads its variables through a shell. So that it receives each value exactly as you typed it, the CLI quotes values that contain spaces or characters such as `$`, `&`, `;` or `#`. `env list` then shows the stored value with those quotes. ```bash theme={"system"} squarecloud app env set 'GREETING=hello world' # The application reads: hello world ``` A value you wrap in one pair of quotes is sent as written, so the shell of your application can expand it. Use it to build a value from another variable: ```bash theme={"system"} squarecloud app env set 'API_URL="${HOST}:3000"' # The application reads the value of HOST followed by :3000. ``` ## The `--from-file` format * One `KEY=VALUE` per line. Blank lines, lines starting with `#` and lines without `=` are skipped. * An `export ` prefix is allowed, and a UTF-8 BOM at the start of the file is ignored. * A value in matching quotes is taken as it is between them. * In an unquoted value, anything from ` #` on is a comment: `A=foo #bar` sets `foo`. Quote values that contain ` #`. * Escape sequences and values that span several lines are not supported. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `list` | [`GET .../envs`](/en/api-reference/endpoint/apps/envs/get) | [`api.apps.envs.get()`](/en/sdks/js/environment_variables) | [Environment variables](/en/vscode-extension/features#applications) | | `set` | [`POST .../envs`](/en/api-reference/endpoint/apps/envs/add_n_edit) | [`api.apps.envs.set()`](/en/sdks/js/environment_variables) | [Environment variables](/en/vscode-extension/features#applications) | | `remove` | [`DELETE .../envs`](/en/api-reference/endpoint/apps/envs/remove) | [`api.apps.envs.delete()`](/en/sdks/js/environment_variables) | [Environment variables](/en/vscode-extension/features#applications) | | `replace` | [`PUT .../envs`](/en/api-reference/endpoint/apps/envs/overwrite) | [`api.apps.envs.replace()`](/en/sdks/js/environment_variables) | | # Manage app files from the CLI Source: https://docs.squarecloud.app/en/cli-reference/files List, read, write, move and delete the files of a running Square Cloud application with squarecloud app file, without a commit. Binary files stay intact. `squarecloud app file` is a remote file manager: it changes files in the application directly, without a commit. Every subcommand takes the application with `--app `, which is optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). `read` and `write` transfer binary files unchanged. ## `squarecloud app file list` ```bash Usage theme={"system"} squarecloud app file list [path] [--app ] [--json] ``` Lists a folder of the application (the root when you omit `path`): type, name, size and last modification. ```bash theme={"system"} squarecloud app file list /logs --app # Lists the logs folder of a specific app. ``` ## `squarecloud app file read` ```bash Usage theme={"system"} squarecloud app file read [-o ] [-y] [--app ] ``` | Flag | Description | | - | - | | `-o`, `--output ` | Saves the content to a local file instead of printing it. Asks before overwriting an existing file. | | `-y`, `--yes` | Overwrites an existing local file without asking. | | `--app ` | The application to read from. | ```bash theme={"system"} squarecloud app file read config.json # Prints the file to stdout. ``` ```bash theme={"system"} squarecloud app file read config.json -o ./config.backup.json # Saves it locally. ``` A new local file created by `-o` is readable only by you (0600 permissions), since application files often hold secrets. ## `squarecloud app file write` ```bash Usage theme={"system"} squarecloud app file write [--from ] [--app ] ``` | Flag | Description | | - | - | | `--from ` | Reads the content from a local file. Without it, the content comes from stdin. | | `--app ` | The application to write to. | Creates the file, or overwrites it when it exists. ```bash theme={"system"} squarecloud app file write config.json --from ./config.json ``` ```bash theme={"system"} cat ./config.json | squarecloud app file write config.json --app # Writes stdin as the file content. ``` ## `squarecloud app file move` ```bash Usage theme={"system"} squarecloud app file move [--app ] ``` **Aliases:** `mv`, `rename` ```bash theme={"system"} squarecloud app file mv old-name.txt new-name.txt ``` ## `squarecloud app file delete` ```bash Usage theme={"system"} squarecloud app file delete [-y] [--app ] ``` **Aliases:** `rm` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | | `--app ` | The application to change. | Asks for `y/N` confirmation, then deletes the file. ```bash theme={"system"} squarecloud app file rm old-log.txt -y ``` ## Related | Command | API | JavaScript SDK | | - | - | - | | `list` | [`GET .../files`](/en/api-reference/endpoint/apps/filemanager/list) | [`api.apps.files.list()`](/en/sdks/js/managing_files) | | `read` | [`GET .../files/content`](/en/api-reference/endpoint/apps/filemanager/content) | [`api.apps.files.read()`](/en/sdks/js/managing_files) | | `write` | [`PUT .../files`](/en/api-reference/endpoint/apps/filemanager/put) | [`api.apps.files.write()`](/en/sdks/js/managing_files) | | `move` | [`PATCH .../files`](/en/api-reference/endpoint/apps/filemanager/patch) | [`api.apps.files.move()`](/en/sdks/js/managing_files) | | `delete` | [`DELETE .../files`](/en/api-reference/endpoint/apps/filemanager/delete) | [`api.apps.files.delete()`](/en/sdks/js/managing_files) | To send a whole folder in one step, use [`squarecloud commit`](/en/cli-reference/deploy#squarecloud-commit). # Deploy from GitHub with the CLI Source: https://docs.squarecloud.app/en/cli-reference/github-deploys Link a GitHub repository to a Square Cloud app with squarecloud app deploy, through the GitHub App or a webhook, and list the deploys each push started. `squarecloud app deploy` connects an application to GitHub so that a push deploys it. There are two ways to do it: * **The Square Cloud GitHub App** (`app deploy github link`): install the app on your repository, then link the repository and a branch. * **A webhook** (`app deploy webhook`): give a GitHub access token and add the URL the CLI prints to your repository's webhooks. The help center walks through the GitHub side: [connect your GitHub repository](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/), or set up an [automated deploy with GitHub Actions](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). `[appID]` and `--app` are optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## `squarecloud app deploy github link` ```bash Usage theme={"system"} squarecloud app deploy github link [--app ] ``` Links a repository and branch through the Square Cloud GitHub App. The app must be installed on the repository through your GitHub account, and your GitHub account needs write access to it. ```bash theme={"system"} squarecloud app deploy github link octocat/hello-world main # Links octocat/hello-world, branch main, to the app in the ID= line. ``` ```bash Output theme={"system"} ✓ Repository octocat/hello-world (branch main) linked successfully ``` To link another repository or branch, unlink the current one first. ## `squarecloud app deploy github unlink` ```bash Usage theme={"system"} squarecloud app deploy github unlink [--app ] ``` Removes the GitHub App link from the application. ## `squarecloud app deploy webhook` ```bash Usage theme={"system"} squarecloud app deploy webhook [--app ] squarecloud app deploy webhook --remove [--app ] ``` | Flag | Description | | - | - | | `--remove` | Removes the configured webhook. No token needed. | Creates a webhook deploy integration from a GitHub access token (`ghp_...` or `github_pat_...`) and prints the URL to add as a webhook in your repository settings. ```bash theme={"system"} squarecloud app deploy webhook --app ``` ```bash Output theme={"system"} ✓ Webhook created successfully; add it to your GitHub repository: ``` ## `squarecloud app deploy current` ```bash Usage theme={"system"} squarecloud app deploy current [appID] [--json] ``` Shows the Git integration configured for the application: the linked repository and branch, the webhook URL, or `No Git integration configured for this application`. ```bash Output theme={"system"} GitHub App: octocat/hello-world (branch main) ``` ## `squarecloud app deploy list` ```bash Usage theme={"system"} squarecloud app deploy list [appID] [--json] ``` Lists the most recent deploys started by Git pushes, one row per commit, with the latest state of each: the first 8 characters of the commit, its date, its state and the branch. ```bash theme={"system"} squarecloud app deploy list --json # Prints the raw timelines: one array of events per deploy. ``` ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `github link` | [`POST .../deploy/github-app`](/en/api-reference/endpoint/apps/deploy/github-app-link) | [`api.apps.deploys.linkGithubApp()`](/en/sdks/js/deploys) | [Link GitHub repository](/en/vscode-extension/features#applications) | | `github unlink` | [`DELETE .../deploy/github-app`](/en/api-reference/endpoint/apps/deploy/github-app-unlink) | [`api.apps.deploys.unlinkGithubApp()`](/en/sdks/js/deploys) | [Unlink GitHub repository](/en/vscode-extension/features#applications) | | `webhook` | [`POST .../deploy/webhook`](/en/api-reference/endpoint/apps/deploy/webhooks) | [`api.apps.deploys.setWebhook()`](/en/sdks/js/deploys) | | | `current` | [`GET .../deployments/current`](/en/api-reference/endpoint/apps/deploy/info) | [`api.apps.deploys.current()`](/en/sdks/js/deploys) | | | `list` | [`GET .../deployments`](/en/api-reference/endpoint/apps/deploy/list) | [`api.apps.deploys.list()`](/en/sdks/js/deploys) | | # Global flags, exit codes and CI Source: https://docs.squarecloud.app/en/cli-reference/global-flags-and-ci Use the Square Cloud CLI's global flags, JSON output, exit codes and debug tracing, check platform health, and run the CLI safely in scripts and CI. ## `squarecloud help` ```bash Usage theme={"system"} squarecloud help [command] squarecloud [command] --help ``` Lists every command, or explains one. Help follows your [system language](/en/cli-reference/installation#language). ```bash Output theme={"system"} A command line application to manage your Square Cloud applications Usage: squarecloud COMMAND [flags] squarecloud [command] Available Commands: app Manage your applications with these commands auth Manage your Square Cloud login with these commands commit Make a commit for your application db Manage the databases of your account help Help about any command status Check the Square Cloud platform health upload Upload a new application workspace Manage your team workspaces zip Zip the current folder Flags: -h, --help Show help for this command --json Output raw JSON -v, --version Print the CLI version Use "squarecloud [command] --help" for more information about a command. ``` ## Global flags | Flag | Description | | - | - | | `--json` | Prints raw, machine-readable JSON on commands that print data (`list`, `info`, `status`, `logs`, `auth whoami`, `upload`, ...). Commands without JSON output (`app start`, `app delete`, `commit`, `zip`, ...) reject the flag with an error. | | `-h`, `--help` | Shows help for any command. | | `-v`, `--version` | Prints the CLI version. Only on `squarecloud` itself. | Destructive commands also accept `-y`/`--yes` to skip their `y/N` confirmation. The pages of each command list it. ## `squarecloud status` ```bash Usage theme={"system"} squarecloud status [--json] ``` Checks whether the Square Cloud platform is operating normally. It works without logging in. For one application or database, use [`squarecloud app status`](/en/cli-reference/status-and-metrics#squarecloud-app-status) or [`squarecloud db status`](/en/cli-reference/databases#squarecloud-db-status). ```bash Output theme={"system"} ✓ ``` When the platform reports a problem, the line starts with `X` instead. See also the [status page](https://status.squarecloud.app/). ## Debugging * Set **`SQUARECLOUD_DEBUG=1`** to trace every API request to stderr: method, path, status and duration. Headers, query strings and bodies are never logged, so the output is safe to share. * Read requests are retried automatically after a network error or when the platform is briefly busy. * **Ctrl+C** cancels the request in flight; a second Ctrl+C exits a command that is waiting for input. ```bash theme={"system"} SQUARECLOUD_DEBUG=1 squarecloud app list ``` ## Scripts and CI The CLI behaves predictably when it runs without a person at the keyboard: * **Authentication:** set `SQUARECLOUD_API_KEY` instead of running `auth login`. See [Authentication](/en/cli-reference/authentication#ci-and-scripts). * **Pass IDs explicitly.** The application and database pickers need a terminal. See [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). * **Exit codes:** every failure exits with code `1`, including when the CLI was installed through npm. Check exit codes, not message text. * **Confirmations fail closed.** Answering no, or running a command that asks for confirmation without a terminal and without `-y`, exits with code `1` and changes nothing. The commands that ask are `app delete`, `app env replace`, `app env remove --all`, `app file delete`, `app file read -o` over an existing file, `app network purge-cache`, `app snapshot restore`, `db delete`, `db snapshot restore`, `db credentials reset`, `workspace delete`, `workspace leave`, `workspace member remove`, and `auth login` when it would replace another account's key. * **stdout carries only results.** Errors, the "not logged in" message, confirmation prompts, failure lines and the update notice go to stderr. With `upload --json`, progress messages go to stderr too. * **Parse `--json`, not tables.** On non-English systems, table headers and `info` labels are translated. To force English, run with `LC_ALL=en_US.UTF-8`. * **Already in that state is success.** Starting a running app or database, or stopping a stopped one, says so and exits with code `0`. To deploy from GitHub Actions, see the help center's [automated deploy workflow](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). ## Related | Command | API | JavaScript SDK | | - | - | - | | `status` | [`GET /v2/service/status`](/en/api-reference/endpoint/service/status) | [`api.service.status()`](/en/sdks/js/client) | # Install the Square Cloud CLI Source: https://docs.squarecloud.app/en/cli-reference/installation Install the Square Cloud CLI on macOS, Linux, WSL or Windows with one command, check that it runs, update it and choose the language of its messages. The Square Cloud CLI is a command-line tool to deploy and manage your applications, databases and workspaces from the terminal. ## Install Square Cloud CLI installation

```bash macOS, Linux and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli ``` * **Install script:** downloads the latest release, verifies it against the release checksums and copies `squarecloud` to `/usr/local/bin`, using `sudo` when you are not root. It works under plain `sh` and supports x86 (64 and 32-bit), arm64 and ARMv7. On Windows, run it inside WSL, or use npm. * **npm package:** needs [Node.js](https://nodejs.org/) and npm, so install a current LTS release of Node.js first. It installs on x64 and arm64 (Apple Silicon, Windows on ARM, Linux) and on ARMv7 Linux. If the binary can't be downloaded, `npm install` fails instead of leaving a CLI that can't run. ## Verify the installation Open a new terminal and run: ```bash theme={"system"} squarecloud --version ``` It prints `Square Cloud CLI version` followed by the installed version. Next, log in with [`squarecloud auth login`](/en/cli-reference/authentication). The folder that holds the CLI is not in your `PATH`, or the terminal was opened before the install. 1. Close the terminal and open a new one: a terminal reads `PATH` only when it starts. 2. **npm:** run `npm prefix -g`. On Windows, the folder it prints (usually `%AppData%\npm`) must be in your `PATH`; on macOS and Linux, its `bin` subfolder must be. Add it in your system settings or shell profile. 3. **Install script:** check that `/usr/local/bin` is in your `PATH` with `echo $PATH`, and add it to your shell profile if it is missing. Check that Node.js and npm are installed with `node --version` and `npm --version`. If they are not, install Node.js from [nodejs.org](https://nodejs.org/), open a new terminal and run the install command again. ## Update the CLI Run the install command again: ```bash macOS, Linux and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` The CLI checks for a newer release at most once a day, only in a terminal, and prints the notice on stderr, so it never mixes with `--json` output. ## Language Messages, help and flag descriptions follow your system language, detected on every run: English, Portuguese, Spanish, German, French, Italian, Japanese and Chinese. The `LANGUAGE`, `LC_ALL`, `LC_MESSAGES` or `LANG` variable wins when set; otherwise the CLI uses the OS display language (on Windows, the display language, not the regional format). A language without a translation falls back to English. To pick a language for a single run: ```bash theme={"system"} LC_ALL=pt_BR squarecloud --help ``` ## Next steps Deploy your first application from the terminal. Log in from the browser, with an API key or in CI. # Read app logs from the CLI Source: https://docs.squarecloud.app/en/cli-reference/logs Print the latest logs of a Square Cloud application with squarecloud app logs, or follow its output and status changes live in the terminal with app realtime. `[appID]` is optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). ## `squarecloud app logs` ```bash Usage theme={"system"} squarecloud app logs [appID] [--json] ``` Prints the most recent logs of the application and exits. ```bash theme={"system"} squarecloud app logs # Logs of the app in the ID= line, or pick one. ``` ```bash theme={"system"} squarecloud app logs --json # Prints {"logs": "..."} instead of plain text. ``` ## `squarecloud app realtime` ```bash Usage theme={"system"} squarecloud app realtime [appID] ``` Connects to the application's live stream and stays connected until you press `Ctrl+C`. * Log lines are printed as the application wrote them. Lines the application wrote to stderr go to stderr, so you can separate them with a redirect. * The status appears as `[status] ` only when it changes. ```bash theme={"system"} squarecloud app realtime 2> errors.log # Follows the app live and saves its stderr lines to errors.log. ``` ```bash Output theme={"system"} Connected to the realtime stream of (Ctrl+C to exit) [status] running ``` `realtime` has no JSON output. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `logs` | [`GET .../logs`](/en/api-reference/endpoint/apps/logs) | [`api.apps.logs()`](/en/sdks/js/managing_application) | [Show logs](/en/vscode-extension/features#applications) | | `realtime` | [`GET .../realtime`](/en/api-reference/endpoint/apps/realtime) | [`api.apps.realtime()`](/en/sdks/js/realtime) | [Toggle realtime stream](/en/vscode-extension/features#applications) | For edge request logs of a website, see [`squarecloud app network logs`](/en/cli-reference/edge-analytics#squarecloud-app-network-logs). # Deploy your first app with the CLI Source: https://docs.squarecloud.app/en/cli-reference/quickstart Install the Square Cloud CLI, log in, deploy a project with squarecloud upload, read its logs and ship every later change with squarecloud commit. This guide takes a project from your machine to a running application on Square Cloud, then shows how to ship a change. It takes a few minutes. ```bash macOS, Linux and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows (needs Node.js) theme={"system"} npm install -g @squarecloud/cli ``` Check that it works with `squarecloud --version`. If the command is not found, see [Installation](/en/cli-reference/installation#verify-the-installation). ```bash theme={"system"} squarecloud auth login ``` The CLI shows a short code and opens the authorization page in your browser. Type the code there and approve. The [Authentication](/en/cli-reference/authentication) page covers API keys and CI. In the root of your project, create a `squarecloud.app` file. It tells Square Cloud which file to run, how much memory to reserve and which runtime version to use: ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My first app ``` For a website, add `SUBDOMAIN=` to publish it at `.squareweb.app`. Every key is explained in the [configuration file guide](/en/getting-started/config-file). From the project folder, run: ```bash theme={"system"} squarecloud upload ``` The CLI zips the folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists (plus `node_modules`, `.git` and lockfiles by default), and creates a new application: ```bash Output theme={"system"} Compressing the current directory. Uploading the zip file to Square Cloud. ✓ Application uploaded to Square Cloud! Open it at https://squarecloud.app/dashboard/applications/ ``` It also writes the new application's ID into your configuration file, so the next commands know which app you mean: ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My first app ID= ``` ```bash theme={"system"} squarecloud app status squarecloud app logs ``` No ID needed: both read the `ID=` line. To follow the output live, run `squarecloud app realtime` and press `Ctrl+C` to stop. Edit your code, then send the folder to the same application and restart it: ```bash theme={"system"} squarecloud commit --restart ``` `upload` creates a new application every time; `commit` updates the one you already have and keeps its ID, domain and settings. ## How the CLI finds your app Commands that act on one application show `[appID]` in their usage: the ID is optional. The CLI picks the application in this order: 1. **The ID you pass.** It is the first argument, or `--app ` on commands whose arguments are something else: `app env set`, `remove` and `replace`, every `app file` command, `app deploy webhook`, `app deploy github link` and `unlink`, and `app network domain`. 2. **The `ID=` line** of the `squarecloud.app` file in the current folder (or `squarecloud.config`; when both exist, `squarecloud.app` wins). 3. **A picker** listing your applications, when the CLI runs in a terminal. Use the arrow keys and `Enter`; `Esc` cancels. A few commands work differently: * `commit` never opens the picker. Without an argument or an `ID=` line, it stops with exit code 1 and asks for one. * `app snapshot restore` always takes the application ID as its first argument. * Databases have no configuration file: `db` commands take the database ID or open a picker of your databases. * `workspace` commands that act on a workspace always take its ID. To find an ID, run [`squarecloud app list`](/en/cli-reference/apps#squarecloud-app-list). In scripts and CI, always pass the ID or keep the `ID=` line: the picker needs an interactive terminal. ### Where the app ID is saved `upload` writes `ID=` only when the folder already has a configuration file, which the upload needs anyway. It changes that one line and keeps your other keys and comments as they are. Square Cloud ignores the line when it reads the file, so it can stay in the zip. Running `upload` again from the same folder creates another application and points the `ID=` line at it. To update the application you have, use `commit`. To work with a different application from this folder, edit or delete the line. ## Next steps Every flag of upload, commit and zip, and what goes in the zip. Set variables from the terminal or load them from a .env file. Deploy on every push through the Square Cloud GitHub App. JSON output, exit codes and running the CLI in pipelines. # Back up and restore snapshots from the CLI Source: https://docs.squarecloud.app/en/cli-reference/snapshots Create, download, list and restore snapshots of Square Cloud applications and databases with squarecloud app snapshot and squarecloud db snapshot. A snapshot is a backup of an application's files or a database's data. `squarecloud app snapshot` and `squarecloud db snapshot` work the same way: `create` makes one, `list` shows the ones stored, `restore` puts one back. For `create`, the app ID is optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). The database ID is optional too: without it, the CLI opens a picker of your databases. ## `squarecloud app snapshot create` ```bash Usage theme={"system"} squarecloud app snapshot create [appID] [--download] ``` | Flag | Description | | - | - | | `--download` | Saves the snapshot in the current folder as `Square Cloud - Snapshot .zip` instead of printing a download link. | ```bash theme={"system"} squarecloud app snapshot create --download ``` ```bash Output theme={"system"} ✓ Your snapshot was created. Download it at: ``` For a large application, the snapshot can still be generating when the command returns: the CLI says so, and the snapshot shows up in `snapshot list` in a few minutes. A download is saved readable only by you (0600 permissions), and a failed `--download` removes the partial file. ## `squarecloud app snapshot list` ```bash Usage theme={"system"} squarecloud app snapshot list [snapshotID] [--json] ``` Without an argument, prints one row per snapshot of your applications, with the snapshot ID, how many versions it has, their total size and the last update. Recent snapshot IDs start with the application ID and end with tags such as `_javascript_manual`. Pass a snapshot ID from that list to see its versions and their **version IDs**, which `restore` needs: ```bash theme={"system"} squarecloud app snapshot list # One row per version: snapshot ID, version ID, size, last update. ``` With `--json`, the output keeps the same filter. Listing snapshots needs an active plan. ## `squarecloud app snapshot restore` ```bash Usage theme={"system"} squarecloud app snapshot restore [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Replaces the application's current files with a snapshot version. Take `` and `` from [`app snapshot list`](#squarecloud-app-snapshot-list). It asks for `y/N` confirmation first. ```bash Output theme={"system"} ✓ Restore started successfully ``` ## `squarecloud db snapshot create` ```bash Usage theme={"system"} squarecloud db snapshot create [dbID] [--download] ``` | Flag | Description | | - | - | | `--download` | Saves the snapshot in the current folder as `Square Cloud - DB Snapshot .zip` instead of printing a download link. | Works like `app snapshot create`, for a database. ## `squarecloud db snapshot list` ```bash Usage theme={"system"} squarecloud db snapshot list [snapshotID] [--json] ``` Without an argument, one row per snapshot of your databases. With a snapshot ID, one row per version, with the version IDs `restore` takes. ## `squarecloud db snapshot restore` ```bash Usage theme={"system"} squarecloud db snapshot restore [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Replaces the database's current data with a snapshot version, after a `y/N` confirmation. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `app snapshot create` | [`POST .../snapshots`](/en/api-reference/endpoint/apps/snapshots/create) | [`api.apps.snapshots.create()`](/en/sdks/js/snapshots) | [Download snapshot](/en/vscode-extension/features#applications) | | `app snapshot list` | [`GET /v2/users/snapshots`](/en/api-reference/endpoint/users/snapshots) | [`api.account.snapshots()`](/en/sdks/js/client) | [Restore snapshot](/en/vscode-extension/features#applications) | | `app snapshot restore` | [`POST .../snapshots/restore`](/en/api-reference/endpoint/apps/snapshots/restore) | [`api.apps.snapshots.restore()`](/en/sdks/js/snapshots) | [Restore snapshot](/en/vscode-extension/features#applications) | | `db snapshot create` | [`POST .../snapshots`](/en/api-reference/endpoint/databases/snapshots/create) | [`api.databases.snapshots.create()`](/en/sdks/js/snapshots) | | | `db snapshot list` | [`GET /v2/users/snapshots`](/en/api-reference/endpoint/users/snapshots) | [`api.account.snapshots()`](/en/sdks/js/client) | | | `db snapshot restore` | [`POST .../snapshots/restore`](/en/api-reference/endpoint/databases/snapshots/restore) | [`api.databases.snapshots.restore()`](/en/sdks/js/snapshots) | | # Check app status and metrics Source: https://docs.squarecloud.app/en/cli-reference/status-and-metrics Check the CPU, memory, disk and uptime of one or every Square Cloud application with squarecloud app status, and print the last 24 hours with app metrics. `[appID]` is optional: see [how the CLI finds your app](/en/cli-reference/quickstart#how-the-cli-finds-your-app). For databases, use [`squarecloud db status`](/en/cli-reference/databases#squarecloud-db-status). ## `squarecloud app status` ```bash Usage theme={"system"} squarecloud app status [appID] [--all] [--raw] [--json] ``` | Flag | Description | | - | - | | `--all` | Shows every application instead of one: app ID, whether it is running, CPU and memory. | | `--raw` | Prints the raw numeric stats as JSON instead of the table. | Prints the app ID, CPU usage, memory, disk, status and uptime of one application. ```bash theme={"system"} squarecloud app status --all # One row per application. ``` ```bash theme={"system"} squarecloud app status --json # The formatted values (such as "0.5%" and "120MB") as JSON. ``` ```bash theme={"system"} squarecloud app status --raw # The same stats as plain numbers, as JSON. ``` ## `squarecloud app metrics` ```bash Usage theme={"system"} squarecloud app metrics [appID] [--json] ``` Prints the last 24 hours of the application's CPU usage, RAM usage and network traffic, one row per 5-minute data point. Metrics are collected only for applications with 512 MB of memory or more. ```bash theme={"system"} squarecloud app metrics --json # Prints the raw data points as JSON. ``` ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `status` | [`GET .../status`](/en/api-reference/endpoint/apps/status) | [`api.apps.status()`](/en/sdks/js/managing_application) | [Application card](/en/vscode-extension/features#applications) | | `status --all` | [`GET /v2/apps/status`](/en/api-reference/endpoint/apps/status-all) | [`api.apps.statusAll()`](/en/sdks/js/managing_application) | Status bar item | | `metrics` | [`GET .../metrics`](/en/api-reference/endpoint/apps/metrics) | [`api.apps.metrics()`](/en/sdks/js/managing_application) | [Show 24h metrics](/en/vscode-extension/features#applications) | # Manage workspace members from the CLI Source: https://docs.squarecloud.app/en/cli-reference/workspace-members Invite people to a Square Cloud workspace with a single-use code, change their permission group and remove them with squarecloud workspace member. People join a workspace with an invite code that they generate themselves: The person who wants to join runs `squarecloud workspace member invite-code` and sends the code to the workspace owner. The code works once and expires after 5 minutes. The owner runs `squarecloud workspace member add` with the workspace ID, the code and a permission group. ## Permission groups `` is one of: | Group | What the member can do | | - | - | | `admin` | Full control of the shared applications: environment variables, snapshots, custom domains and deploy settings included. | | `maintain` | Operational work: commits, start, stop and restart, files, DNS and cache purges. | | `manager` | Monitoring and control: start, stop and restart, and deploy information. No commits, files or network changes. | | `view` | Read only. | The owner's own group is `owner`, which can't be given to anyone else. The help center has more on [workspace permissions](https://help.squarecloud.app/en-us/article/workspace-permissions-collaborators-12ahei1/). ## `squarecloud workspace member invite-code` ```bash Usage theme={"system"} squarecloud workspace member invite-code ``` Generates your own single-use invite code, valid for 5 minutes. ```bash Output theme={"system"} Your invite code (single-use, valid for 5 minutes): ``` ## `squarecloud workspace member add` ```bash Usage theme={"system"} squarecloud workspace member add ``` Adds the person who generated `` to the workspace, with the given permission group. Only the workspace owner can add members, up to the member limit of the owner's plan. ```bash theme={"system"} squarecloud workspace member add maintain ``` ## `squarecloud workspace member update` ```bash Usage theme={"system"} squarecloud workspace member update ``` Changes a member's permission group. Take the member ID from [`workspace info`](/en/cli-reference/workspaces#squarecloud-workspace-info). ## `squarecloud workspace member remove` ```bash Usage theme={"system"} squarecloud workspace member remove [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Removes a member from the workspace, after a `y/N` confirmation. Only the workspace owner can remove members. To leave a workspace yourself, use [`workspace leave`](/en/cli-reference/workspaces#squarecloud-workspace-leave). ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `invite-code` | [`GET .../members/code`](/en/api-reference/endpoint/workspace/members/code) | [`api.workspaces.members.inviteCode()`](/en/sdks/js/workspaces) | [Copy My Invite Code](/en/vscode-extension/features#workspaces) | | `add` | [`POST .../members`](/en/api-reference/endpoint/workspace/members/invite) | [`api.workspaces.members.add()`](/en/sdks/js/workspaces) | | | `update` | [`PATCH .../members`](/en/api-reference/endpoint/workspace/members/perms) | [`api.workspaces.members.update()`](/en/sdks/js/workspaces) | | | `remove` | [`DELETE .../members`](/en/api-reference/endpoint/workspace/members/kick) | [`api.workspaces.members.remove()`](/en/sdks/js/workspaces) | | # Manage workspaces from the CLI Source: https://docs.squarecloud.app/en/cli-reference/workspaces Create, inspect, leave and delete Square Cloud workspaces with squarecloud workspace, and choose which of your applications each workspace can see. A workspace shares applications with a team. `squarecloud workspace` also works as `squarecloud ws`. Every command takes the workspace ID, which `workspace list` and `workspace create` print. To add people, see [Workspace members](/en/cli-reference/workspace-members); the help center explains [what each member can do](https://help.squarecloud.app/en-us/article/workspace-permissions-collaborators-12ahei1/). ## `squarecloud workspace create` ```bash Usage theme={"system"} squarecloud workspace create ``` Creates a workspace and prints its ID. ```bash theme={"system"} squarecloud workspace create "My Team" ``` ```bash Output theme={"system"} ✓ Workspace My Team () created successfully ``` ## `squarecloud workspace list` ```bash Usage theme={"system"} squarecloud workspace list [--json] ``` Shows the name, workspace ID, member count, application count and creation date of every workspace you own or joined. ## `squarecloud workspace info` ```bash Usage theme={"system"} squarecloud workspace info [--json] ``` Shows the workspace ID, name, owner and creation date, followed by a table of its members (name, member ID, group and join date) and a table of its shared applications (name, app ID, language and memory), when it has any. ## `squarecloud workspace app add` ```bash Usage theme={"system"} squarecloud workspace app add ``` Shares one of your applications with a workspace you own, so its members can work on it. A workspace holds up to 100 applications. ## `squarecloud workspace app remove` ```bash Usage theme={"system"} squarecloud workspace app remove ``` Stops sharing the application with the workspace. Only the workspace owner can do it. ## `squarecloud workspace leave` ```bash Usage theme={"system"} squarecloud workspace leave [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Removes you from a workspace someone else owns, after a `y/N` confirmation. The workspace itself stays. The owner can't leave their own workspace: delete it instead. ## `squarecloud workspace delete` ```bash Usage theme={"system"} squarecloud workspace delete [-y] ``` | Flag | Description | | - | - | | `-y`, `--yes` | Skips the confirmation prompt. | Deleting a workspace is permanent: its member list and application sharing go with it. The applications themselves stay in their owners' accounts. Only the owner can delete a workspace. The command asks for `y/N` confirmation first. ## Related | Command | API | JavaScript SDK | VS Code | | - | - | - | - | | `create` | [`POST /v2/workspaces`](/en/api-reference/endpoint/workspace/create) | [`api.workspaces.create()`](/en/sdks/js/workspaces) | [Create workspace](/en/vscode-extension/features#workspaces) | | `list` | [`GET /v2/workspaces`](/en/api-reference/endpoint/workspace/list) | [`api.workspaces.list()`](/en/sdks/js/workspaces) | [Workspaces section](/en/vscode-extension/features#workspaces) | | `info` | [`GET /v2/workspaces/{workspaceId}`](/en/api-reference/endpoint/workspace/get) | [`api.workspaces.get()`](/en/sdks/js/workspaces) | | | `app add` | [`POST .../applications`](/en/api-reference/endpoint/workspace/apps/add) | [`api.workspaces.apps.add()`](/en/sdks/js/workspaces) | | | `app remove` | [`DELETE .../applications`](/en/api-reference/endpoint/workspace/apps/remove) | [`api.workspaces.apps.remove()`](/en/sdks/js/workspaces) | | | `leave` | [`DELETE /v2/workspaces/leave`](/en/api-reference/endpoint/workspace/leave) | [`api.workspaces.leave()`](/en/sdks/js/workspaces) | [Leave](/en/vscode-extension/features#workspaces) | | `delete` | [`DELETE /v2/workspaces`](/en/api-reference/endpoint/workspace/delete) | [`api.workspaces.delete()`](/en/sdks/js/workspaces) | [Delete](/en/vscode-extension/features#workspaces) | # squarecloud.app Configuration File Reference Source: https://docs.squarecloud.app/en/getting-started/config-file Configure your app with the squarecloud.app file: MAIN, MEMORY, VERSION, DISPLAY_NAME, RUNTIME, START, SUBDOMAIN and AUTORESTART, with bot and site examples. ## What is the configuration file? The configuration file tells Square Cloud how to run your application: which file to start, how much memory to reserve, which runtime version to use and, for a website, which subdomain to publish. It is a plain text file with one `KEY=VALUE` pair per line. ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My first app ``` ## Creating the configuration file Create a file named `squarecloud.app` or `squarecloud.config` at the root of your project. Both names work the same way. When you upload a zip, the file must sit at the top level of the zip, not inside a subfolder, or the deploy fails with `MISSING_CONFIG`. On **macOS**, we recommend the `squarecloud.config` name. The [VS Code extension](/en/vscode-extension/features#config-file-intellisense) autocompletes every key below and underlines invalid values as you type. ## Configuration parameters `MEMORY`, `VERSION` and `DISPLAY_NAME` are always required. `MAIN` is required unless you set `RUNTIME`. | Parameter | Required | Editable after deploy | Limit | Purpose | | - | - | - | - | - | | [`MAIN`](#main) | Unless `RUNTIME` is set | No | 32 characters | File that starts the application. | | [`MEMORY`](#memory) | Yes | Yes | Your plan's free RAM | RAM reserved for the application, in MB. | | [`VERSION`](#version) | Yes | No | `recommended` or `latest` | Runtime version. | | [`DISPLAY_NAME`](#display_name) | Yes | Yes | 32 characters | Name shown in the dashboard. | | [`DESCRIPTION`](#description) | No | Yes | 280 characters | Short description. | | [`AUTORESTART`](#autorestart) | No | Yes | `true` or `false` | Restart the application after a crash. | | [`SUBDOMAIN`](#subdomain) | No | Only on websites | 63 characters | Publishes the application as a website. | | [`RUNTIME`](#runtime) | No | No | See the table | Runtime, when `MAIN` can't tell it. | | [`START`](#start) | No | Yes | 256 characters | Custom start command. | Editable parameters can be changed in the dashboard after the deploy. Changing a non-editable parameter requires uploading the application again. ### MAIN The file that starts your application, relative to the project root. ```systemd theme={"system"} MAIN=index.js ``` ```systemd theme={"system"} MAIN=src/bot/main.py ``` * The file extension selects the runtime: `.js` runs on Node.js, `.ts` on TypeScript, `.py` on Python, and so on. * The file must exist in your upload and can't be empty. * Up to 32 characters: letters, digits, `_`, `.`, `/` and `-`, no spaces. A missing `MAIN` (without `RUNTIME`) fails with `MISSING_MAIN`; a file that doesn't exist, has no extension or breaks the rules above fails with `INVALID_MAIN`. ### MEMORY The RAM reserved for your application, in megabytes. It also sets your application's vCPUs and bandwidth. ```systemd theme={"system"} MEMORY=512 ``` The value must be at least the [minimum for your project type](/en/platform/limitations-and-restrictions#minimum-resource-requirements), and no more than the RAM your plan still has free. Otherwise the deploy fails with `INSUFFICIENT_MEMORY`. ### VERSION The runtime version: `recommended` or `latest`. Any other value, including an exact version number, fails the deploy with `INVALID_VERSION`. ```systemd theme={"system"} VERSION=recommended ``` Use `recommended` unless you need a feature that only the newest release has. The versions behind each value are listed in the [runtime versions table](/en/runtimes/introduction#versions). ### DISPLAY\_NAME The name shown in the dashboard, the CLI and the API. ```systemd theme={"system"} DISPLAY_NAME=Admin bot ``` Up to 32 characters: letters without accents, digits, spaces, `-` and `_`. Anything else, such as accented letters or emoji, fails with `INVALID_DISPLAY_NAME`. ### DESCRIPTION A short description of the application, up to 280 characters (`INVALID_DESCRIPTION` beyond that). ```systemd theme={"system"} DESCRIPTION=This bot helps with your daily tasks. ``` ### AUTORESTART Restarts the application automatically after a crash. Accepts `true` or `false`, and defaults to `false`, so turn it on for bots and anything that must stay online. ```systemd theme={"system"} AUTORESTART=true ``` An automatic restart happens only when all of these are true: * The application exited with status `1`, the usual exit code of an unhandled error in Node.js and Python. * It had been running for at least 60 seconds, so an app that crashes right at boot isn't restarted in a loop. * It hasn't been restarted automatically in the last hour. * The logs don't show an error a restart can't fix: an invalid bot token, a missing module, a syntax or TypeScript type error, or a failed dependency install. A restart keeps the app online through a transient error, but the underlying bug still needs a fix in your code. See also the help center article on [auto restart](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). ### SUBDOMAIN Publishes the application as a website at `https://.squareweb.app`. ```systemd theme={"system"} SUBDOMAIN=mysite ``` * Up to 63 characters: letters, digits and hyphens, not starting or ending with a hyphen. The name is stored in lowercase. * A name that is already in use, reserved (such as `admin` or `api`) or invalid fails with `INVALID_SUBDOMAIN`. * A website needs more RAM than a bot: see the [minimum RAM](/en/platform/limitations-and-restrictions#minimum-resource-requirements). * Your server must listen on port `80` and host `0.0.0.0` (see [website doesn't load](/en/platform/troubleshooting/app-wont-start#website-doesnt-load)). Decide at the first upload whether the application is a website. On a website you can change the subdomain later, but you can't remove it (`CANNOT_SET_SUBDOMAIN`). An application deployed without `SUBDOMAIN` can't become a website: upload it again as a new application with `SUBDOMAIN` set. To serve the site on your own domain, see [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) in the help center. ### RUNTIME Sets the runtime explicitly, instead of deriving it from the extension of `MAIN`. An unknown value fails with `INVALID_RUNTIME`. ```systemd theme={"system"} RUNTIME=nodejs ``` | Runtime | Accepted values | | - | - | | Node.js | `nodejs`, `javascript` | | TypeScript | `typescript` | | Python | `python` | | C# / .NET | `csharp`, `dotnet`, `c#` | | Elixir | `elixir` | | Java | `java` | | Rust | `rust` | | Ruby | `ruby` | | PHP | `php` | | Go | `go`, `golang` | | Static HTML/CSS | `static`, `html` | With `RUNTIME` set you can leave out `MAIN`. In that case, also set `START`: most runtimes start the application by running the `MAIN` file. ### START A custom start command. It replaces the default command, which runs your `MAIN` file. ```systemd theme={"system"} START=npm run start ``` * Up to 256 characters (`INVALID_START` beyond that). * Dependencies are still installed before the command runs. * The command is read from the file on every start, so you can change it by editing `squarecloud.app` in the dashboard and restarting. Only call scripts that exist in your project. `START=npm run build && npm run start`, for example, fails on an Express app without a `build` script in `package.json`. Leave `START` out when the default command is enough. ### ID You don't write this key yourself. After `squarecloud upload`, the Square Cloud CLI adds `ID=` to the file, so later commands such as `squarecloud commit` know [which application to target](/en/cli-reference/quickstart#how-the-cli-finds-your-app). Square Cloud ignores it when deploying. ## Examples ### Bot ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=Robin bot DESCRIPTION=Moderation and music for my server. AUTORESTART=true ``` ### Website or API ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My site DESCRIPTION=My site is really cool! SUBDOMAIN=mysite AUTORESTART=true ``` The site answers at `https://mysite.squareweb.app`. ### Next.js A framework that needs a build step uses `START`. Here `MAIN` only selects the Node.js runtime, so point it at your actual config file (such as `next.config.mjs`); the build and start scripts come from `package.json`. ```systemd squarecloud.app theme={"system"} MAIN=next.config.js MEMORY=2048 VERSION=recommended DISPLAY_NAME=Nextjs site SUBDOMAIN=nextjs START=npm run build && npm run start AUTORESTART=true ``` ## Next steps Keep tokens and connection strings out of your code and your zip. Choose which files the CLI and VS Code leave out of the upload. Versions, dependency files and how each runtime starts your app. What each deploy error means and how to fix it. # Docs: Host Discord Bots, Websites, APIs and Databases Source: https://docs.squarecloud.app/en/getting-started/overview Square Cloud docs: deploy Discord bots, websites, APIs and managed databases in minutes, with guides for Node.js, Python and more, plus CLI and API references.

New Blob Storage update: private files, share links and S3 → # Your code,
live in seconds.

Host bots, websites, APIs, databases and files on infrastructure built for developers. Add one configuration file, upload your project and Square Cloud takes care of the rest, from logs to real-time metrics.

Start building Configuration file

Square Cloud is a paid platform: every plan runs on dedicated resources from your very first deploy. Compare plans

Everything your project needs to run

Pick what you're building. Each service has its own guide, limits and best practices.

Bot hosting Discord, WhatsApp and Telegram bots online around the clock, with optional automatic restarts. Websites and APIs Frontends, APIs and full-stack apps on a squareweb.app subdomain or your own domain. Databases Managed MongoDB, PostgreSQL, MySQL and Redis, with TLS and snapshots. Blob Storage Object storage with a global CDN, private files, share links and an S3 API.

From code to production in three steps

Add a configuration file A squarecloud.app file tells us your main file, memory and runtime version.

Upload your project Send a zip through the dashboard, the CLI, the VS Code extension or the API, or deploy from GitHub.

Go live Your app starts in seconds, with logs, real-time metrics and optional automatic restarts.

squarecloud.app

MAIN=index.js

MEMORY=512

VERSION=recommended

DISPLAY\_NAME=My first app

SUBDOMAIN=my-first-app

Automate everything

Manage apps, databases and files from your terminal, your editor or your own code.

REST API Every dashboard action, available over HTTP. CLI Deploy, restart and follow logs from your terminal. SDKs Official JavaScript, Python and Go libraries. VS Code extension Upload, commit and follow logs without leaving your editor.

Start here

QuickstartYour first deploy in under 5 minutes.

Host a Discord botPut a discord.js or discord.py bot online 24/7.

Deploy a websitePublish a site or API on squareweb.app.

Configuration fileEvery squarecloud.app parameter explained.

RuntimesSupported languages and versions.

Create a databaseDeploy a managed database and connect your app.

Plans and pricingResources and features of each plan.

TroubleshootingFix the most common deploy and runtime errors.

Discord communityOver 100,000 developers ready to help.

Ready to put your project online?

Create your account, choose a plan and deploy in minutes.

Create account Sign in

# Quickstart: Deploy Your First App Source: https://docs.squarecloud.app/en/getting-started/quick-start Put your first app online on Square Cloud in minutes: write a small web server, add the configuration file, zip it and deploy from the dashboard or the CLI. This guide deploys a small Node.js web server so you can see the whole flow end to end: three files, one zip and one upload. The steps are the same for a bot or for another language. ## Before you begin Square Cloud is a paid platform: an active plan is required to deploy, so your project runs on production-grade infrastructure from day one. Create your account, then [select the plan](https://squarecloud.app/en/pricing) that's right for you (see [what each plan includes](/en/platform/plans)). If you've never used Square before, sign up to get started. If you already have an account, log in to get started. ## Create the project Create a folder with these three files. `index.js` answers every request with a short message. It reads the port and host from the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`: ```javascript index.js theme={"system"} const http = require("node:http"); const port = process.env.PORT || 3000; const host = process.env.HOST || "0.0.0.0"; http .createServer((req, res) => { res.writeHead(200, { "Content-Type": "text/plain" }); res.end("Hello from Square Cloud!"); }) .listen(port, host, () => { console.log(`Listening on http://${host}:${port}`); }); ``` Every Node.js project needs a `package.json`: Square Cloud installs the packages it lists before starting your app. This example has none, but the file must exist and can't be empty. ```json package.json theme={"system"} { "name": "hello-square", "version": "1.0.0", "private": true, "main": "index.js", "scripts": { "start": "node index.js" } } ``` `squarecloud.app` tells Square Cloud which file to run, how much memory to reserve and which runtime version to use. `SUBDOMAIN` publishes the app as a website at `https://.squareweb.app`, so pick a name nobody has taken yet. ```systemd squarecloud.app theme={"system"} MAIN=index.js MEMORY=512 VERSION=recommended DISPLAY_NAME=Hello Square SUBDOMAIN=hello-square-yourname ``` Every field is explained in the [configuration file reference](/en/getting-started/config-file). The [VS Code extension](/en/vscode-extension/features#config-file-intellisense) autocompletes and checks this file as you type. A website must listen on port **80** and host **0.0.0.0**. A server bound to `localhost`, `127.0.0.1` or another port (such as 3000 or 8080) can't be reached, and the site shows a timeout page. Reading `PORT` and `HOST`, as `index.js` does, gets this right on Square Cloud and still runs on port 3000 on your machine. Deploying a bot instead? Leave out `SUBDOMAIN`, add `AUTORESTART=true`, and keep the token in an [environment variable](/en/platform/environment-variables), never in the code. The [Discord bot tutorial](/en/tutorials/bots/discord) walks through a complete bot. ## Zip the project Deploying with the CLI? Skip this section: `squarecloud upload` zips the folder for you. Open the project folder and select everything inside it. `squarecloud.app` must sit at the top level of the zip: if you compress the folder itself, the files end up inside a subfolder and the deploy fails with `MISSING_CONFIG`. Right-click the selected files and choose **Compress to ZIP file** (Windows 11) or **Send to** → **Compressed (zipped) folder**. Control-click the selected files and choose **Compress**. Right-click the selected files and choose **Compress**, or run `zip -r ../app.zip .` inside the folder. The zip can be up to **100 MB**. Leave out `node_modules`, virtual environments and build caches: dependencies are installed on the server, and those folders are [deleted on deploy](https://help.squarecloud.app/en-us/article/which-files-are-deleted-on-deploy-1j0krik/) anyway. ## Deploy Upload the zip in the dashboard, or deploy with one command from the CLI. ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. Once the app is running, `https://hello-square-yourname.squareweb.app` (with your subdomain) answers `Hello from Square Cloud!`. Want a deploy on every push? [Connect a GitHub repository](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) or use the [GitHub Actions workflow](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). ## Next steps Every `squarecloud.app` field: memory, start command, subdomain and automatic restarts. Store tokens and connection strings outside your code. Fix upload errors, sites that don't load and apps that won't start. Upload, commit and follow logs without leaving your editor. ### Guides for your language Each guide covers the dependency file, the start command and the common pitfalls of its runtime. # squarecloud.ignore: Exclude Files from Your Deploy Source: https://docs.squarecloud.app/en/getting-started/squarecloud-ignore Use squarecloud.ignore to leave files out of CLI and VS Code deploys: .gitignore syntax, default exclusions like node_modules, pattern rules and examples. ## What is the `squarecloud.ignore` file? The `squarecloud.ignore` file lists the files and folders to leave out when you upload or commit an application. The Square Cloud CLI (`upload`, `commit` and `zip`) and the Square Cloud VS Code extension read the same file, with the same rules and the same defaults, so a project is packaged the same way by both. It uses `.gitignore` syntax: comments, wildcards, folder-only and root-only rules, and `!` to bring a file back. ## Creating the file Create a file named `squarecloud.ignore` in the root of your project. ```gitignore theme={"system"} # Test output and logs coverage/ *.log !keep.log ``` The file must be named exactly `squarecloud.ignore`. `.gitignore` is not read in its place: it often lists files the application needs to run, such as `.env`. ## Always left out These paths are ignored before your own rules, so you don't need to list them: * `node_modules` * `.git`, `.github` and `.vscode` * `package-lock.json`, `pnpm-lock.yaml` and `yarn.lock` Bring any of them back with a `!` rule. ### Lockfiles Lockfiles stay out of the zip by default, so Square Cloud installs your dependencies from the version ranges in `package.json`. When you need the exact versions your lockfile pins, bring it back: ```gitignore theme={"system"} !package-lock.json ``` ## Syntax Each line is a rule. A matching file or folder is left out of the upload. | Pattern | Matches | | - | - | | `file.txt` | A file or folder with this name at any depth. | | `/config.json` | `config.json` at the project root only. | | `logs/` | Every folder named `logs` and its contents, but not a file named `logs`. | | `*.log` | Names ending in `.log`. `*` never crosses a `/`. | | `?` | Exactly one character, such as `file?.txt`. | | `[abc]` | One of the listed characters, such as `backup[12].zip`. | | `**/cache/`, `logs/**`, `a/**/b` | Any number of folders, including none. | | `!keep.log` | Brings back a file that an earlier rule left out. | | `# comment` | A comment; it does not exclude anything. | | `\#notes.txt`, `\!important`, `\*` | A `\` makes the next character literal. | How the rules are applied: * **The last matching line wins**, so put `!` rules after the rules they undo. * **A file inside an ignored folder can't be brought back.** To keep one file of a folder, ignore the folder's contents (`logs/*`) instead of the folder (`logs/`), then add `!logs/keep.log`. * **Matching ignores case**: `Dist/` also matches `dist`. * Only trailing spaces are trimmed from a rule, never tabs. Escape a trailing space you want to keep with `\ `. Use `/` for folder separators in patterns, including on Windows. ## Common examples Exclude development tools and generated files while keeping everything the application needs to run: ```gitignore theme={"system"} # Tooling .idea/ # Generated files coverage/ __pycache__/ *.log # Temporary files *.tmp *.cache ``` Don't ignore a file your application reads at runtime. If your code loads secrets from a `.env` file and you list `.env` here, the application starts without them and a bot fails with an invalid token. Move those values to the application's [environment variables](/en/platform/environment-variables) first; after that, leaving `.env` out of the upload is safe. ## How it is applied The CLI and the VS Code extension read `squarecloud.ignore` when preparing the files for upload or commit. Files that match a rule are left out of the zip sent to Square Cloud. * A symbolic link to a file is uploaded as the file it points to. Links to folders and broken links are skipped. * The CLI still reads the older names (`.squareignore`, `.squarecloudignore` and `square.ignore`) when `squarecloud.ignore` is missing, and asks you to rename the file. Keep files required at runtime, such as the `MAIN` file from your [configuration file](/en/getting-started/config-file), outside the ignored paths. The dashboard upload doesn't read this file: when you build the zip yourself, leave those files out of it. # Environment Variables and Secrets Source: https://docs.squarecloud.app/en/platform/environment-variables Store tokens, API keys and connection strings as environment variables on Square Cloud from the dashboard, the CLI or the API, and read them in your code. Keep bot tokens, API keys and database passwords out of your source code. Set them as environment variables on the application, and your code reads them at runtime like any other variable. ## Set variables Environment variables belong to one application. They survive restarts and commits, but a new upload creates a new application without them, so set them again there. 1. Open your application in the [dashboard](https://squarecloud.app/en/dashboard) and go to **Settings** → **Environment Variables**. 2. Add each key and value, or import an existing `.env` file. 3. Click **Save**. The dashboard asks whether to restart the application: restart it so the app picks up the new values. When you upload a new application in the dashboard, you can also add variables on the upload screen, before the first start. Run the commands from your project folder. The CLI targets the application whose `ID` is in your `squarecloud.app`. To target another one, pass `--app ` (for `list`, pass the ID as its argument). ```bash theme={"system"} # Add or update variables (the others stay as they are) squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info # Send every line of a local .env file squarecloud app env set --from-file .env # List the current variables squarecloud app env list # Remove one variable squarecloud app env remove LOG_LEVEL # Restart to apply the changes squarecloud app restart ``` `squarecloud app env replace` swaps the whole set for the one you pass, after a confirmation. Every command and flag is covered in [environment variables from the CLI](/en/cli-reference/environment-variables); to install the CLI and log in, see the [CLI quickstart](/en/cli-reference/quickstart). In the [Square Cloud extension](/en/vscode-extension/features), right-click your application in the side bar and choose **Environment variables** to list, add, edit or delete them. Restart the application afterwards to apply the changes. Send the variables to [`POST /v2/apps/{app_id}/envs`](/en/api-reference/endpoint/apps/envs/add_n_edit) with an API key that has the `envs:write` scope: ```bash theme={"system"} curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"envs": {"DISCORD_TOKEN": "your-token"}}' ``` The same path also [lists](/en/api-reference/endpoint/apps/envs/get) (`GET`), [replaces](/en/api-reference/endpoint/apps/envs/overwrite) (`PUT`) and [removes](/en/api-reference/endpoint/apps/envs/remove) (`DELETE`) variables. The API doesn't restart the application: call the [restart endpoint](/en/api-reference/endpoint/apps/restart) afterwards. Variables are loaded when the application starts. After any change, restart the application, or it keeps running with the old values. ## Read them in your code ```javascript Node.js theme={"system"} const token = process.env.DISCORD_TOKEN; if (!token) { throw new Error("DISCORD_TOKEN is not set"); } ``` ```python Python theme={"system"} import os token = os.environ.get("DISCORD_TOKEN") if not token: raise RuntimeError("DISCORD_TOKEN is not set") ``` Failing fast when a variable is missing gives you a clear message in the logs instead of a confusing error later, such as an invalid token. ## Variables Square Cloud sets for you Your application starts with these variables already defined: | Variable | Value | Use it to | | - | - | - | | `PORT` | `80` | Choose the port your web server listens on. | | `HOST` | `0.0.0.0` | Choose the address your web server binds to. | | `SQUARECLOUD_APP_ID` | Your application ID | Identify the application at runtime. | | `NODE_ENV` | `production` | Tell Node.js libraries they run in production (Node.js and TypeScript runtimes). | Don't override `PORT` or `HOST` on a website: the platform only reaches a server on port 80 and host `0.0.0.0`. Because `NODE_ENV` is `production`, `npm install` skips `devDependencies`. If your `START` command builds the project (for example with `typescript` or `vite`), list those build tools under `dependencies` in `package.json`. ## How variables reach your app Square Cloud stores the variables in a `.squarecloud/.env` file inside the application and loads them with a shell every time the application starts, before dependencies are installed and your `START` command or `MAIN` file runs. Two consequences: * **Names** should use letters, digits and underscores, and not start with a digit. * **Values** with spaces or shell characters such as `$`, `&`, `;` or `|` must be quoted, or the shell cuts or expands them. The dashboard and `squarecloud app env set` quote them for you. In the VS Code extension or the API, wrap such a value in single quotes yourself: type `'p@ss word$1'`, or send `"PASSWORD": "'p@ss word$1'"` in the API body. The limits are 256 variables per application, 1,024 characters per name and 4,096 characters per value. Static websites (HTML/CSS) don't support environment variables and return `STATIC_APP_ENV_NOT_SUPPORTED`. ## Keep secrets out of your upload If your code loads a `.env` file itself (for example with `dotenv`), that file has to be in the upload. Listing `.env` in [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) then starts the app without its secrets, and a bot fails with an invalid token. The safer setup: move each value from your `.env` into the application's environment variables, as shown above. Once they are set, you can leave `.env` out of the upload and out of your Git repository. `dotenv` doesn't overwrite variables that already exist, so the same code keeps working on your machine and on Square Cloud. Never commit tokens or passwords to a public repository. If one leaks, revoke it at the provider (for example, reset the bot token in the Discord Developer Portal) and set the new value here. ## Next steps Set `MAIN`, `MEMORY`, `START` and the other fields of `squarecloud.app`. Deploy a bot that reads its token from an environment variable. Fix an invalid token, missing intents and bots that go offline. Connect with a `DATABASE_URL` and the right SSL settings. # Resource Limits: RAM, CPU, Bandwidth and Storage Source: https://docs.squarecloud.app/en/platform/limitations-and-restrictions Square Cloud resource limits: minimum RAM per project, vCPUs by RAM, dedicated bandwidth, 10 GB NVMe storage and the LACK_OF_RAM and LACK_OF_CPU statuses. Square Cloud implements container-based resource limits to ensure isolation, stability, and fair distribution of infrastructure across applications. ## Minimum resource requirements Each project hosted on the Square Cloud Platform has specific minimum resource requirements to ensure optimal performance: * **Bots:** Minimum of 256 MB RAM required. * **Websites:** Minimum of 512 MB RAM required. * **Cache Databases:** Minimum of 512 MB RAM required. * **General Databases:** Minimum of 1 GB RAM required. ### Why do RAM minimums exist? Containers have mandatory operational overhead: language runtime, OS libraries, and network buffers. Below 256 MB, the kernel's OOM Killer tends to terminate processes during boot or garbage collection, making the application inviable. **Technical implications:** * Each container consumes 1 dynamic IPv4 and NVMe storage IOPS * Minimum allocations prevent resource fragmentation (noisy neighbor effect) * Daily snapshot formula: `(Total RAM / 256) * 2` (approximate; the exact per-plan allowance may be lower on higher tiers) **Impact Data:** After implementing the 256 MB minimum limit, application stability increased drastically, reducing the crash rate due to OOM (Out of Memory) by **97.7%**. ## CPU allocation Short answer: CPU is allocated based on configured RAM. Increasing RAM typically grants more vCPUs. ### Rules #### Single vCPU plans Applications on 1 vCPU plans receive full capacity without throttling. #### Multicore plans (≥2 vCPU) * Performance floor: applications with ≥512 MB RAM receive at least 2 vCPUs. * Proportional scaling: * Hobby (≤2 vCPU): +1 vCPU per 512 MB RAM * Standard / Pro / Enterprise: +1 vCPU per 1 GB (1024 MB) RAM ### Examples | Plan | Plan capacity | Configured RAM | vCPUs allocated | | - | - | -: | -: | | Standard | 4 GB / 4 vCPU | 1 GB | 2 vCPUs (floor) | | Standard | 4 GB / 4 vCPU | 4 GB | 4 vCPUs (max) | | Enterprise | 128 GB / 16 vCPU | 2 GB | 2 vCPUs | | Enterprise | 128 GB / 16 vCPU | 16 GB | 16 vCPUs | ### Throttling and safety limits The system enforces the plan vCPU limit and applies leveling to keep distribution fair. Short-term elasticity may grant extra vCPUs during spikes but is not guaranteed. Prohibited CPU uses: * Cryptocurrency mining * Unrestricted, intensive ML workloads without authorization * Deliberate resource abuse These uses break the [policy against abuse, crypto mining and spam](https://help.squarecloud.app/en-us/article/policy-against-abuse-crypto-mining-and-spam-vih8tf/). Separately, an application that keeps all of its vCPUs busy is stopped with [`LACK_OF_CPU`](#lack_of_cpu). ## Network limits Every application gets **dedicated bandwidth**, the same for upload and download, that scales proportionally to the RAM allocated: **+50 Mbps per 256 MB**. It is reserved for your container, never shared with neighbours, and traffic is never metered or billed. Some examples: | RAM allocated | Bandwidth | | -: | -: | | 256 MB | 50 Mbps | | 512 MB | 100 Mbps | | 1 GB | 200 Mbps | | 2 GB | 400 Mbps | | 4 GB | 800 Mbps | For sustained high-throughput workloads, support can set up a dedicated cluster. **Boot turbo.** Every start gets a burst well above the plan's bandwidth, so installing dependencies, pulling models or rebuilding caches is fast regardless of your allocation. Databases have their own dedicated bandwidth, in both directions, sized to their RAM. ## Storage limits All projects receive **10 GB NVMe** storage by default. Characteristics: * Enterprise-grade NVMe * Persistent across deploys and restarts * High IOPS and throughput ## Limit exceeded statuses When an application goes over its resources, Square Cloud stops it, writes a `[SQUARE-SHIELD]` line with the reason to its logs and sends you an email. This table is the reference the other pages link to; the fixes are below it. | Log line | What happened | What Square Cloud does | | - | - | - | | `[SQUARE-SHIELD] LACK_OF_RAM` | The application used all of its RAM. | Stops the application. | | `[SQUARE-SHIELD] LACK_OF_CPU` | The application kept all of its vCPUs busy across consecutive checks. | Stops the application. Databases are never stopped for CPU. | | `[SQUARE-SHIELD] ABUSE_REQUESTS` | The application sent requests to Discord or to `squareweb.app` sites at an abusive rate for a sustained period. | Stops the application, and starting it fails with `CONTAINER_TEMPORARILY_SUSPENDED` for a short period. | The help center explains the alert emails in [downtime alerts: RAM, CPU and request blocks](https://help.squarecloud.app/en-us/article/downtime-alert-ram-cpu-and-request-blocks-12ivqus/). ### LACK\_OF\_RAM The application reached its allocated RAM, so the process was stopped to protect the host. How to fix: 1. Find memory leaks with a profiler (Node.js: `--inspect`, Python: `memory_profiler`). See [memory leaks in Node.js](https://help.squarecloud.app/en-us/article/memory-leak-in-nodejs-how-to-find-and-fix-it-1bvgprf/). 2. Reduce in-memory caches or move them to Redis. 3. Increase the application's RAM in the dashboard, or raise `MEMORY` in the [configuration file](/en/getting-started/config-file#memory). ### LACK\_OF\_CPU The application used all of its vCPUs for a sustained period, so the process was stopped. How to fix: 1. Profile CPU hotspots (Node.js: `0x`, Python: `cProfile`). See [CPU at 100%: optimization tips](https://help.squarecloud.app/en-us/article/cpu-at-100-optimization-tips-nvjqse/). 2. Optimize hot loops, database queries and I/O-bound operations. 3. Increase RAM to get more vCPUs (see [CPU allocation](#cpu-allocation)). 4. Move heavy work to asynchronous workers or batch jobs. Trade-off: increasing RAM to gain CPU raises costs. Measure whether optimizing the code is cheaper than scaling up. ### CONTAINER\_TEMPORARILY\_SUSPENDED The logs showed `[SQUARE-SHIELD] ABUSE_REQUESTS`: the application sent requests to Discord or to `squareweb.app` sites at an abusive rate for a sustained period. This is almost always an infinite loop, a retry without a delay or a missing cache, not real popularity. The application was stopped, and until the block ends, starting it fails with `CONTAINER_TEMPORARILY_SUSPENDED`. How to fix: 1. Read the email and the last logs to find the code that sends the requests. 2. Cache what you fetch, add a delay between retries and respect the rate-limit headers of the API you call. See [Discord API rate limits](https://help.squarecloud.app/en-us/article/discord-api-rate-limits-429-error-how-to-avoid-them-mkkz7n/). 3. Wait a moment and start the application again. # Infrastructure, Uptime and Security Source: https://docs.squarecloud.app/en/platform/overview Square Cloud infrastructure: SOC 2 and ISO 27001 certified New York data center, 10 Gbps per server, multi-layer DDoS protection and 99.99% uptime. ## Power, flexibility and security Square Cloud is the foundation of an ecosystem of products and services designed to simplify the management of your applications, websites and projects. Operating as a centralized hub, our platform offers an intuitive and integrated experience so you can focus on what really matters: creating and innovating. ### Our vision and commitment We were born with the goal of creating an extremely flexible cloud platform, capable of adapting to the dynamic needs of businesses of all sizes. This vision is symbolized in our logo, where the angular squares represent our adaptability and commitment to continuous evolution. * The design directly references a Docker container, the technology that underpins our infrastructure. This choice reflects our dedication to offering efficient, scalable solutions aligned with the best practices in the cloud universe. Our commitment is to provide a platform that not only meets but exceeds the expectations of every developer who trusts in our infrastructure. Built by developers, for developers, Square Cloud offers an exceptional user experience that transforms ideas into tangible results. ### Robust and secure infrastructure To ensure maximum performance and protection, we operate with cutting-edge infrastructure located in a data center in New York, a highly secure and resilient environment. **High-Speed Network and Advanced Protection:** * **10 Gbps connectivity per server:** Ensures ultra-fast data transfer and minimal latency for your applications. * **Multi-layer DDoS protection:** A robust defense system that protects your projects against denial-of-service attacks, ensuring availability. * **24/7 monitoring:** Our network is continuously monitored by specialists to prevent failures and maintain performance at optimal levels. **Physical Security and Redundancy:** * **Controlled Access:** Strict biometric and access card controls ensure that only authorized personnel enter the facilities. * **Redundant Power Systems:** Multiple backup systems guarantee service continuity, even during main electrical grid failures. * **Fire Protection and Structural Resilience:** The data center features advanced fire suppression systems (pre-action sprinklers and FM200) and was built to withstand extreme weather conditions. **Additional features of our infrastructure:** * **Resize on demand**: raise or lower an application's RAM from the dashboard whenever your workload changes; its vCPUs and bandwidth follow the RAM (see [limits and restrictions](/en/platform/limitations-and-restrictions)). Resources never change on their own, so your bill stays predictable. * **Load balancing**: on Standard and higher plans, attach one custom domain to several applications to spread traffic between them. * **Agility**: Rapid deployment of solutions and updates, ensuring minimal downtime. We use our container orchestration technology, "Square Orchestrator," to optimize resource allocation and application deployment, resulting in greater efficiency and speed. ### Uptime and reliability Reliability is not a promise here. It is a measured track record: * **99.99% uptime** across the platform, backed by redundant power, multi-layer DDoS protection and 24/7 monitoring. * **Deployments in seconds:** your application goes from upload to running without maintenance windows. * **Real customer results:** Zennify reduced infrastructure costs by **43%** and has run with **100% uptime for 19 months** on Square Cloud. * **4.9/5 across 402 reviews** on [Google and Trustpilot](https://www.trustpilot.com/review/squarecloud.app): independent, third-party feedback from developers running production workloads. ### Certifications and compliance The security and integrity of your data are our priority. That is why Square Cloud runs in a data center that holds internationally recognized certifications for the most rigorous security practices: * **SSAE-16 SOC 2 and SOC 2 Type II:** the data center's security controls, availability, processing integrity and data confidentiality are rigorously audited and approved. * **ISO 27001:** the data center follows global best practices for an Information Security Management System (ISMS), with a systematic and continuous approach to data protection. On top of that certified foundation, Square Cloud adds its own protection: multi-layer DDoS mitigation and 24/7 monitoring of the platform. The Square Cloud platform combines advanced features with cutting-edge infrastructure, ready to boost your projects in a scalable, secure, and high-performance environment. RAM, vCPU, bandwidth and storage rules, and the statuses shown when an app goes over them. Resources and features of each plan. # Plans and Pricing: Hobby, Standard, Pro, Enterprise Source: https://docs.squarecloud.app/en/platform/plans Square Cloud pricing plans and cost: Hobby, Standard, Pro and Enterprise, with the RAM, vCPU, Blob storage and features of each tier. Square Cloud is a paid platform with dedicated resources on every plan: you always know what you'll pay upfront, with no metered surprises on bandwidth or usage. ## Plans | Plan | Price (BRL/month) | RAM (apps + databases) | vCPU | Blob storage | Highlights | | - | -: | - | - | - | - | | **Hobby** | from R\$12.49 | 1-2 GB | 1-2 | 5-15 GB | Website/bot hosting, [GitHub deployment](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/), WAF firewall, auto-restart, real-time metrics, unlimited traffic | | **Standard** (most popular) | from R\$44.99 | 4-8 GB | 4 | 30-100 GB | Everything in Hobby + database hosting, custom domains, team workspaces, dynamic IPv4, email notifications, 10 Gbps network | | **Pro** | from R\$124.99 | 12-24 GB | 6-12 | 200-250 GB | Everything in Standard + daily snapshots, priority support, turbo processing, performance analytics, HTTP logs, Blob custom metadata and password-protected share links | | **Enterprise** | from R\$299.90 | 32-1024 GB | 16 | 250 GB | Everything in Pro + custom resources, dedicated account manager, custom terms, Blob expiries under 7 days and files without edge cache | Each plan comes in several sizes: the price grows with the RAM you pick. ### How the RAM is shared Your plan's RAM is one pool. Every application and database you create reserves part of it, and you can split it any way you like, as long as each project gets at least its [minimum RAM](/en/platform/limitations-and-restrictions#minimum-resource-requirements). For example: * **Hobby with 1 GB**: four bots with 256 MB each, or two websites with 512 MB each. * **Standard with 4 GB**: a 1 GB PostgreSQL database, a 1 GB website and eight bots with 256 MB each. There is no separate limit on the number of projects: the RAM decides how many fit. ## Which plan should I choose? * **A Discord bot, a website or an API** → **Standard**. It's the first tier with managed databases and custom domains, leaves room for your project to grow, and it's the most popular plan. A single light bot or small site also runs on Hobby. * **Multiple production apps or a team workspace** → **Pro**. Daily snapshots, priority support and performance analytics matter once you're running more than one serious app. * **Large-scale or custom infrastructure needs** → **Enterprise**. Custom RAM/vCPU allocation and a dedicated account manager. Prices are in BRL and billed monthly or annually (20% off with annual billing). The live source of truth for pricing is [squarecloud.app/en/pricing](https://squarecloud.app/en/pricing): figures on this page may lag a live promotion. For per-plan technical specs (exact vCPU/RAM allocation rules, network and storage limits), see [Platform limits and restrictions](/en/platform/limitations-and-restrictions). ## Frequently asked questions No, and you won't miss it: the **Hobby** plan costs \*\*R$12.49/month**, about R$0.42 a day, and less than R\$10/month on the yearly cycle (20% off). For that, your project runs on dedicated RAM and CPU, NVMe storage, a WAF firewall and optional automatic restarts from day one, and it never goes to sleep. We recommend **Standard**, from **R$44.99/month**: 4 GB of RAM and 4 vCPUs leave room for the bot to grow, plus a managed database for its data. A small bot with no database also runs on **Hobby**, from **R$12.49/month**, since a bot needs at least 256 MB of RAM. Bots with heavy memory or CPU needs may need Pro. Yes. You manage your subscription from the dashboard: see [how to upgrade, downgrade or cancel](https://help.squarecloud.app/en-us/article/how-to-upgrade-downgrade-or-cancel-your-account-1gmpw5p/) in the help center. When an application exceeds its allocated RAM (or the kernel signals an out-of-memory condition), the process is terminated immediately with a `LACK_OF_RAM` status to protect host stability. See [Platform limits and restrictions](/en/platform/limitations-and-restrictions#lack_of_ram) for how to diagnose and fix it. # Troubleshooting: Fix Common Square Cloud Errors Source: https://docs.squarecloud.app/en/platform/troubleshooting Fix common Square Cloud errors: upload rejections, sites that don't load, EADDRINUSE, missing modules, Discord bot login failures and database SSL errors. Your app failed to deploy, start or answer? Find the exact error below. Each page is organized by the literal error message or status code Square Cloud shows in your logs, the dashboard, the CLI or the API, with what it means, why it happens and how to fix it. FILE\_TOO\_LARGE, INSUFFICIENT\_MEMORY, MISSING\_CONFIG, INVALID\_MAIN, INVALID\_VERSION, INVALID\_DEPENDENCY and KEEP\_CALM. A timeout page, "This site couldn't be found" or a site that works locally but not on Square Cloud. EADDRINUSE, Cannot find module, ModuleNotFoundError, better-sqlite3 bindings and apps that stop right after starting. Invalid token, disallowed intents, Lavalink code 1006 and bots that go offline after working locally. "Host is not allowed to connect", MongoNetworkError, Atlas IP allowlists, timeouts, ECONNREFUSED and SSL/TLS errors. LACK\_OF\_RAM, LACK\_OF\_CPU and CONTAINER\_TEMPORARILY\_SUSPENDED: what stops an app and how to fix it. ## Related guides * [Configuration file](/en/getting-started/config-file): every field of `squarecloud.app` and the errors each one can raise. * [Environment variables](/en/platform/environment-variables): set tokens and connection strings, and apply them with a restart. * [squarecloud.ignore](/en/getting-started/squarecloud-ignore): make sure the CLI and VS Code don't leave out a file your app needs. * [Help center](https://help.squarecloud.app/en-us/): step-by-step articles on domains, GitHub deploys, time zones and more. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # App Won't Start: Deploy, Site and Boot Errors Source: https://docs.squarecloud.app/en/platform/troubleshooting/app-wont-start Fix a Square Cloud app that won't deploy, start or load: upload errors, timeouts on port 80, EADDRINUSE, Cannot find module, INVALID_DEPENDENCY and UTC times. If your application is rejected at upload, crashes at boot or never answers, the error code or the console log almost always names the exact problem. Match it below. ## Upload and deploy errors These codes come back from the dashboard, the CLI or the API when Square Cloud rejects an upload. Nothing is deployed, so fix the cause and upload again. | Code | What it means | How to fix | | - | - | - | | `FILE_TOO_LARGE` | The zip is larger than 100 MB. | Leave out `node_modules`, build output and large media. Store big files in [Blob Storage](/en/services/blob) instead. | | `INSUFFICIENT_MEMORY` | `MEMORY` is below the minimum for the project type, or higher than the RAM your plan still has free. | Check the [minimum RAM](/en/platform/limitations-and-restrictions#minimum-resource-requirements). To free RAM, delete an application you don't use, lower another one's RAM, or upgrade your plan. | | `MISSING_CONFIG` | There is no `squarecloud.app` or `squarecloud.config` at the top level of the zip, or it is empty. | Zip the contents of your project folder, not the folder itself. | | `MISSING_MEMORY`, `MISSING_DISPLAY_NAME`, `MISSING_VERSION` | A required field is missing from the configuration file. | Add it. See the [configuration file](/en/getting-started/config-file#configuration-parameters). | | `MISSING_MAIN`, `INVALID_MAIN` | `MAIN` is missing, points to a file that isn't in the zip, is empty or breaks the naming rules. | Check the [`MAIN` rules](/en/getting-started/config-file#main). | | `INVALID_VERSION` | `VERSION` isn't `recommended` or `latest`. | Use one of the two values. | | `INVALID_RUNTIME`, `INVALID_START` | `RUNTIME` has an unknown value, or `START` is longer than 256 characters. | See [`RUNTIME`](/en/getting-started/config-file#runtime) and [`START`](/en/getting-started/config-file#start). | | `INVALID_DISPLAY_NAME`, `INVALID_DESCRIPTION` | The name has characters outside letters, digits, spaces, `-` and `_`, or is longer than 32 characters; or the description is longer than 280. | See [`DISPLAY_NAME`](/en/getting-started/config-file#display_name). | | `INVALID_SUBDOMAIN` | The subdomain is invalid, reserved or already taken. | Pick another name. See [`SUBDOMAIN`](/en/getting-started/config-file#subdomain). | | `INVALID_DEPENDENCY` | The dependency file is missing or empty. | See [INVALID\_DEPENDENCY](#invalid_dependency) below. | | `FAILED_EXTRACT` | The file isn't a valid zip archive. | Create the zip again with your system's compress option or `zip -r`. | | `KEEP_CALM` | You repeated an action too quickly. | See [KEEP\_CALM](#keep_calm) below. | ### INVALID\_DEPENDENCY **What it means:** the upload has no dependency file for its language, or the file is empty. Square Cloud checks that this file exists at the root of the zip before it installs anything. **How to fix:** put the dependency file at the root of the zip, next to `squarecloud.app`, and make sure it isn't empty: `package.json` (Node.js, Bun, Deno), `requirements.txt` or `pyproject.toml` (Python), `Cargo.toml` (Rust), `Gemfile` (Ruby), `go.mod` or `go.work` (Go) or `mix.exs` (Elixir). Then upload again. A misspelled package or version shows up later, as an install error in the logs. ### KEEP\_CALM **What it means:** you, or an automation, repeated an action too quickly, such as a restart, an upload or a snapshot. **How to fix:** wait a moment and try again. The rejected action simply didn't run: `KEEP_CALM` never stops or affects a running application. If a snapshot fails with `DAILY_SNAPSHOTS_LIMIT_REACHED` instead, your plan's daily snapshot allowance is used up until the next day. ## Website doesn't load **What it means:** the application is deployed, but opening its address shows one of these pages instead of your site: * **"The website took too long to respond"**: Square Cloud found your application but got no answer from it. * **"This site couldn't be found"**: no website is published at that address. **How to fix a timeout:** 1. Make your server listen on port `80` and host `0.0.0.0`. A server bound to `localhost`, `127.0.0.1` or any other port (3000, 5173, 8080...) can't be reached. The runtime sets the `PORT` and `HOST` environment variables to these values, so read them: ```javascript Node.js (Express) theme={"system"} app.listen(process.env.PORT || 3000, process.env.HOST || "0.0.0.0", () => { console.log("Server running"); }); ``` ```python Python (Flask) theme={"system"} import os app.run(host=os.environ.get("HOST", "0.0.0.0"), port=int(os.environ.get("PORT", 3000))) ``` 2. Open the logs: if the application crashed or is still installing dependencies or building, the site can't answer yet. Fix the error shown there, or wait for the build to finish. 3. Check that `MEMORY` gives the build enough room: a framework build that runs out of RAM stops the application with [`LACK_OF_RAM`](/en/platform/limitations-and-restrictions#lack_of_ram). **How to fix "This site couldn't be found":** 1. Check the address: it's `https://.squareweb.app`, with the subdomain from your configuration file. 2. If you just deployed, wait up to a minute for the address to be published. 3. An application deployed without `SUBDOMAIN` isn't a website and can't become one: upload it again as a new application with [`SUBDOMAIN`](/en/getting-started/config-file#subdomain) set. 4. On a custom domain, the DNS may still be propagating. See [why your domain hasn't propagated yet](https://help.squarecloud.app/en-us/article/why-hasnt-my-domain-propagated-yet-dns-f5jzoy/). ## EADDRINUSE (port already in use) **What it means:** the app tries to bind the same network port twice. **Why it happens:** two servers are started in the code, or a `listen(...)` call gets created again inside an event handler (for example, on every request or every reconnect) instead of once at startup. **How to fix:** 1. Start **one** web server, **once**, listening on port `80` and host `0.0.0.0`. 2. Search your code for more than one `.listen()` (Node.js) or `run()` (Python/Flask/Django) call and remove the duplicate. 3. Make sure the listen call sits at the top level of your startup file, not inside a callback that can fire more than once. ## "Cannot find module" (Node.js) and ModuleNotFoundError (Python) **What it means:** a package your code imports isn't installed. **Why it happens:** * The library isn't listed in `package.json`'s `dependencies` (Node.js) or in `requirements.txt`/`pyproject.toml` (Python), so it never gets installed on the platform, even if it works on your machine. * In Node.js, the package is only in `devDependencies`. Applications run with `NODE_ENV=production`, so `npm install` skips development dependencies. **How to fix:** 1. Add the missing package to `dependencies` (or your Python dependency file) with a valid version. 2. Confirm the dependency file itself is included in the zip you uploaded. 3. Restart the application. For Node.js, dependencies are only installed when `node_modules` doesn't exist: delete `node_modules` (and `package-lock.json`, if you uploaded one) in the dashboard's file manager, then restart for a clean reinstall. ## better-sqlite3 / native bindings errors **What it means:** an error like `Could not locate the bindings file` when your app uses `better-sqlite3` (directly, or through `quick.db`). **Why it happens:** the installed `better-sqlite3` version predates the platform's current Node.js LTS, so its prebuilt native binding doesn't match the runtime. **How to fix:** 1. Update `better-sqlite3` to `12.5.0` or later (if you use `quick.db`, update it to `9.1.7` or later). 2. Delete `node_modules` **and** `package-lock.json`. 3. Restart the application for a clean reinstall that rebuilds the native bindings against the current runtime. ## Stopped by a resource limit If the logs end with `[SQUARE-SHIELD] LACK_OF_RAM`, `LACK_OF_CPU` or `ABUSE_REQUESTS`, or starting the application fails with `CONTAINER_TEMPORARILY_SUSPENDED`, Square Cloud stopped it for going over its resources. The [status table](/en/platform/limitations-and-restrictions#limit-exceeded-statuses) explains each one and how to fix it. ## Times are off by a few hours Applications run in UTC. A job scheduled for 09:00 runs at 09:00 UTC, and the times your code prints to the logs are in UTC. Convert times in your code, or see [how to change your application's time zone](https://help.squarecloud.app/en-us/article/how-to-change-your-applications-timezone-y525ae/) in the help center. ## Related guides * [Configuration file](/en/getting-started/config-file): every field and the error it raises. * [Environment variables](/en/platform/environment-variables): set secrets, then restart to apply them. * [Discord bot errors](/en/platform/troubleshooting/discord-bot-errors) and [database connection errors](/en/platform/troubleshooting/database-connection-errors). Still stuck after checking the logs against the errors above? Our support team can look at the specific crash with you. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Database Connection Errors: SSL, MySQL, MongoDB Source: https://docs.squarecloud.app/en/platform/troubleshooting/database-connection-errors Fix database connection errors on Square Cloud: MySQL Host is not allowed, MongoNetworkError, Atlas IP whitelist, timeouts, ECONNREFUSED and SSL/TLS issues. Most database connection failures on Square Cloud come down to one of three things: a missing SSL certificate, an IP allowlist that doesn't account for a dynamic IP, or wrong credentials. Match the exact error below. ## "Host 'X' is not allowed to connect to this MySQL server" **What it means:** the MySQL client rejects the connection with this exact message. **Why it happens:** Square Cloud's hosted databases **require SSL** for every connection. This error appears when the connection is attempted without the certificate loaded, not because of a firewall/host allowlist as the message implies. **How to fix:** 1. Open the database in the Square Cloud dashboard and download the certificate files (CA, cert, key, usually 2-3 fields). 2. Load them in your client's SSL/TLS configuration: * **GUI clients** (MySQL Workbench, DBeaver, HeidiSQL): configure the downloaded certificate files in the client's SSL tab, then connect with the host/port/user/password shown in the dashboard. * **Code (Prisma ORM):** convert the client cert+key into a `.p12`: ```bash theme={"system"} openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt ``` Then set: ``` DATABASE_URL=mysql://USER:PASSWORD@HOST:PORT/DB?sslidentity=./client.p12&sslpassword=PASSWORD ``` Ship `client.p12` inside the app's zip and set `DATABASE_URL` in the application's [environment variables](/en/platform/environment-variables), then restart the application. 3. Verify the username and password match what's shown in the dashboard, and restart the database if the certificate was only just generated. Never commit `certificate.pem` or `client.p12` to a public repository, keep it out of version control, but do include it in the deploy `.zip` when your app reads it from disk. ## MongoNetworkError and MongoDB Atlas IP whitelist failures **What it means:** an externally-hosted MongoDB Atlas cluster (not a Square Cloud managed database) refuses the connection with `MongoNetworkError: connection ... closed`, even though the credentials are correct. **Why it happens:** Square Cloud application containers use a **dynamic IPv4 address that changes on every restart**. A MongoDB Atlas IP allowlist configured for a single static IP will work until the next restart, then silently break. **How to fix, choose one:** 1. **Recommended if you need external Atlas:** in Atlas → Network Access, add `0.0.0.0/0` to allow connections from any IP, and compensate for the wider allowlist with strong credentials (long random password, dedicated database user, connection string kept only in [environment variables](/en/platform/environment-variables)). See also [MongoDB Atlas with a dynamic IP](https://help.squarecloud.app/en-us/article/mongodb-atlas-whitelist-dynamic-ip-y0q0sg/). 2. **Recommended overall:** move the database to a [Square Cloud managed database](/en/services/databases) instead of an external Atlas cluster. Hosting the database next to the app removes the IP-allowlist problem entirely and gives near-zero latency. ## Connection timeout and ECONNREFUSED **What it means:** the app hangs until it times out, or fails immediately with `ECONNREFUSED`, when trying to reach a database. **Why it happens, as a rule of thumb:** * A **timeout** (the connection hangs, no immediate rejection) usually means a firewall or IP allowlist on the destination database is blocking the connection. Many external providers block datacenter/foreign IPs by default. * An immediate **ECONNREFUSED** or "authentication failed" usually means the host/port is reachable but the credentials, database name, or port number are wrong. **How to fix:** 1. If connecting to an external provider (not a Square Cloud managed database), allow Square Cloud's ASNs on the destination firewall: `398395` and `26548`. Where only IP-based allowlisting is supported (like MongoDB Atlas), use `0.0.0.0/0` with strong credentials instead, since the source IP is dynamic. 2. Double-check host, port, username, and password against what the provider or the Square Cloud dashboard shows. 3. URL-encode any special characters in the connection string (`@`, `:`, `/`, etc. inside a password will break parsing if left raw). 4. Check whether the provider's driver requires an explicit `ssl=true` (or similar) parameter in the connection string. ## SSL/TLS connection errors **What it means:** the client fails to establish a TLS handshake with the database, or fails right after with an authentication-looking error that's actually a certificate problem. **Why it happens:** Square Cloud managed databases require SSL on every connection. Each database engine expects the certificate in a slightly different shape: * **Redis:** the protocol must be `rediss://` (two s's), never `redis://`. Shape: `rediss://default:PASSWORD@HOST:PORT`. `node-redis` also accepts `socket: { tls: true, ca: fs.readFileSync("certificate.pem") }`; Python's `redis` library takes `ssl_ca_certs`/`ssl_certfile`/`ssl_keyfile` (the combined `certificate.pem` downloaded from the dashboard works for all of them). * **Drizzle ORM (Postgres):** a standard `pg` `Pool` with `ssl: { ca, cert, key }`, all loaded via `fs.readFileSync` from the combined `certificate.pem`, and the same `ssl` object in `drizzle.config.ts`. * **JDBC (Java):** the client key must be converted to PK8/DER format and referenced in the JDBC URL's SSL properties. **How to fix:** re-download the certificate from the database's page in the dashboard (an old or partial certificate file is a common cause), confirm the connection string uses the TLS-enabled protocol/scheme for your engine, and restart the database if you just created it. ## Related guides * [Create and connect a managed database](/en/tutorials/how-to-deploy-your-database): the full setup, with connection examples. * [Databases](/en/services/databases): engines, versions and what each plan includes. * [Environment variables](/en/platform/environment-variables): keep the connection string out of your code. * [Connection problems, firewalls and IP blocks](https://help.squarecloud.app/en-us/article/connection-problems-firewall-and-ip-blocks-1kedujc/) in the help center. If the error message doesn't match anything above, our support team can help diagnose the exact connection failure. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Discord Bot Errors: Invalid Token, Intents, Lavalink Source: https://docs.squarecloud.app/en/platform/troubleshooting/discord-bot-errors Fix Discord bot errors on Square Cloud: LoginFailure and TokenInvalid, disallowed intents, Message Content Intent, Lavalink code 1006 and bots going offline. Discord bot errors on Square Cloud usually trace back to the token, the gateway intents, or a version mismatch with Lavalink. Match the exact message below. ## "LoginFailure: Improper token has been passed" / TokenInvalid **What it means:** Discord rejected the token your bot logs in with. The exact message depends on the library: * **discord.py:** `discord.errors.LoginFailure: Improper token has been passed.` * **discord.js v14:** `Error [TokenInvalid]: An invalid token was provided.` * **older discord.js:** `Error [TOKEN_INVALID]: An invalid token was provided.` * **other libraries:** an HTTP `401 Unauthorized` on login. **Why it happens:** * The token was regenerated or revoked in the Discord Developer Portal. Generating a new token instantly invalidates the old one everywhere it's used. * The token string has extra spaces or quotes copied in by accident. * The code is reading the wrong environment variable, or the variable isn't set on Square Cloud. **How to fix:** 1. Go to the [Developer Portal](https://discord.com/developers/applications) → your application → **Bot** → **Reset Token**. 2. Update the token in the application's [environment variables](/en/platform/environment-variables) (dashboard **Settings** → **Environment Variables**, or `squarecloud app env set`). Never commit the token in a file that gets uploaded in the zip. 3. Double-check there are no stray spaces or quotes around the value. 4. Update the library (`discord.js@latest` or `pip install -U discord.py`). 5. Restart the application, so it loads the new value. Never hardcode your bot token in source files. Always read it from an environment variable set in the dashboard. ## "Used disallowed intents" / Message Content Intent **What it means:** the bot logs in and appears online, but ignores every message, or the gateway rejects the connection with "used disallowed intents". **Why it happens:** since 2022, **Message Content** is a privileged intent. Without it explicitly enabled in both places, message content arrives empty (or the gateway connection is refused if your code declares an intent that isn't enabled for the app). **How to fix, in both places:** 1. Discord Developer Portal → your application → **Bot** → **Privileged Gateway Intents** → enable **Message Content Intent**. 2. Declare it in code as well: ```javascript theme={"system"} // discord.js const client = new Client({ intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent, ], }); ``` ```python theme={"system"} # discord.py intents = discord.Intents.default() intents.message_content = True client = commands.Bot(command_prefix="!", intents=intents) ``` 3. Restart the application. Once a bot passes 100 servers, privileged intents (including Message Content) also require approval from Discord, requested from the same Developer Portal page. ## Lavalink connection closed with code 1006 **What it means:** the bot's Lavalink client closes the WebSocket abnormally with code 1006, often preceded by "Unexpected server response: 400". **Why it happens:** this is a version mismatch. Lavalink v4 is REST-based and is incompatible with a client wrapper built for v3, so the handshake fails and the socket closes with 1006. **How to fix:** 1. Align your bot's Lavalink client wrapper version with the Lavalink server's major version (v3 client with v3 server, v4 client with v4 server). 2. On Square Cloud, the Lavalink server itself binds port `80`, but your bot must connect to it through the edge on port `443` with `secure: true`. 3. Restart both the Lavalink application and the bot application after fixing the version mismatch. For the full Lavalink hosting setup (config file, port, deployment), see the [Lavalink server tutorial](/en/tutorials/how-to-create-your-lavalink-server). ## Bot goes offline after working locally **What it means:** the bot logs in fine when you run it on your machine, but goes offline (or restarts repeatedly) once deployed. **Why it happens, most commonly:** * An unstable connection at the gateway level with no reconnect handling. * Conflicting or incompatible dependency versions between what you tested locally and what's in your dependencies file. * The bot was stopped for going over its RAM or CPU, or for flooding the Discord API. In that case the logs show a `[SQUARE-SHIELD]` line and you get an email: see the [status table](/en/platform/limitations-and-restrictions#limit-exceeded-statuses). **How to fix:** 1. Check the application's logs in the dashboard first, they show the actual crash reason. 2. Add error handlers so a transient error doesn't crash the process: `process.on("unhandledRejection", ...)` and `client.on("error", ...)` in discord.js, equivalent handling in discord.py. 3. Add `AUTORESTART=true` to your `squarecloud.app` so Square Cloud restarts the bot after a crash. It's off by default, and it only restarts in the cases listed in [`AUTORESTART`](/en/getting-started/config-file#autorestart). It keeps the bot alive through transient errors, but it never fixes an invalid token, a syntax error or a missing dependency: those still need a fix in the code. 4. Watch for Discord API rate limits (429): the global limit is about 50 requests/second per bot token, with tighter per-route buckets (channel create/edit allows roughly 2 changes per 10 minutes per channel). Cache aggressively, use an async queue that respects the `X-RateLimit-Remaining`/`X-RateLimit-Reset-After` headers, and use webhooks for mass sends. A bot that keeps flooding Discord is stopped with [`ABUSE_REQUESTS`](/en/platform/limitations-and-restrictions#container_temporarily_suspended). ## Related guides * [Discord bot hosting tutorial](/en/tutorials/bots/discord): set up and deploy a bot from scratch. * [Environment variables](/en/platform/environment-variables): store the token outside your code. * [App won't start](/en/platform/troubleshooting/app-wont-start): upload errors, missing modules and other boot failures. If the logs don't point to a clear cause, our support team can help you dig further. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Supported Languages and Runtimes Source: https://docs.squarecloud.app/en/runtimes/introduction Check the languages and versions Square Cloud supports, how RUNTIME or MAIN selects the runtime, how dependencies install and what each runtime image includes. A **runtime** on Square Cloud is the complete, isolated environment your application runs inside: the language interpreter or virtual machine, the system libraries it links against, the tooling it can shell out to, and the security boundary that keeps it separated from every other application on the host. You never build or maintain that environment. You ship your source code and a small [configuration file](/en/getting-started/config-file); Square Cloud detects the language, resolves your dependencies, provisions an isolated container and runs it. The same pipeline powers Discord/WhatsApp/Telegram bots, websites and APIs, background workers and long-running services, on the same fast, hardened infrastructure. ## Supported languages Beyond the languages above, most other stacks and libraries run out of the box. The runtime images are built to be permissive: if your language installs on Linux, it very likely runs on Square Cloud. ## Versions Every runtime ships two update channels, selectable through the `VERSION` field in your configuration file: * **`recommended`**: the version we harden and run in production for the majority of applications. Choose it unless you have a specific reason not to. * **`latest`**: the newest release, for teams that need a just-shipped language feature. `VERSION` accepts only these two values: any other value, including an exact version number, fails the deploy with `INVALID_VERSION`. | Language | `recommended` | `latest` | | - | - | - | | Node.js \[JS & TS] | 24.21.0 | 26.9.0 | | Python | 3.14.7 | 3.14.7 | | Java | JDK 25 | JDK 25 | | Elixir | 1.20.4 | 1.20.4 | | Rust | 1.98.1 | 1.98.1 | | Ruby | 4.0.7 | 4.0.7 | | PHP | 8.5.10 | 8.5.10 | | Go | 1.27.1 | 1.27.1 | | .NET/C# | 10.0.12 | 10.0.12 | Choose `recommended` unless you need a feature that only `latest` has. See the [configuration file](/en/getting-started/config-file) reference for the `RUNTIME` and `VERSION` fields. ## How a deploy works From upload to a live process, every deploy runs through the same deterministic pipeline: Square Cloud takes the language from the `RUNTIME` field of your configuration file or, when it is not set, from the extension of the `MAIN` file: `.js` for Node.js, `.ts` for TypeScript, `.py` for Python, `.go` for Go, `.jar` for Java, and so on. It then checks that the language's dependency file is at the root of your upload: `package.json` for Node.js and TypeScript, `requirements.txt` or `pyproject.toml` for Python, `go.mod` or `go.work` for Go, `Cargo.toml` for Rust, `Gemfile` for Ruby and `mix.exs` for Elixir. If it is missing or empty, the deploy fails with `INVALID_DEPENDENCY`. Dependencies are installed **server-side**, inside the container, before your app starts: `npm install` when there is no `node_modules` folder (a `node_modules` folder at the root of your upload is discarded), `pip install` for Python, `bundle install` for Ruby and `mix deps.get` for Elixir, while Go, Rust and .NET download their packages when they build your code. You don't need to ship `node_modules` or a virtualenv inside the `.zip`. Java is the exception: the default command runs a JAR you built (`java -jar MAIN`), so upload the compiled `.jar`. An isolated container is created with the CPU and memory declared in your configuration file. Resources are enforced at the kernel level, so one application can never starve another on the same host. Without `START`, Square Cloud runs the language's default command, such as `node MAIN`, `python MAIN`, `go run MAIN` or `java -jar MAIN` (Rust and Elixir build and run the whole project with `cargo run --release` and `mix run --no-halt`). Need a build step or a custom command? Set `START` and it runs verbatim. ## Inside every runtime image Each image starts from the official image of its language and adds the system tools applications commonly need: Node.js and Python apps run on the same image, which ships both Node.js and Python 3.14, so a bot can call a script written in the other language. The PHP image also includes Node.js 24 and npm for asset builds. ffmpeg is preinstalled in the Node.js, Python, Java, Go, Rust, Ruby, Elixir and .NET images, and the Node.js and Python image also includes headless Chromium, ready for media bots, web scraping, and PDF or screenshot generation without extra setup. Applications run as a non-root user inside an isolated container. A compromised dependency stays contained, with no privileged access to the host. No interpreter needed? Set `RUNTIME=static` to serve a plain HTML/CSS/JS site directly, with the same CDN and TLS as any other application. ## Isolation and security Every application is a fully isolated container with kernel-enforced CPU and memory limits, never a shared process. Running unprivileged means an application cannot reach the host or its neighbors, and resource caps guarantee that a spike in one project has no effect on the performance of another. This is the same model that lets Square Cloud host tens of thousands of workloads on shared clusters without them interfering with each other. ## Next steps Master `MAIN`, `START`, `RUNTIME`, `VERSION` and `MEMORY`: the fields that control your runtime. Step-by-step setup for Node.js, Bun, Deno, Python, Go, Rust, Java, static HTML and more. # Official SDKs for JavaScript, Python and Go Source: https://docs.squarecloud.app/en/sdks/introduction Official Square Cloud SDKs for JavaScript, Python and Go, plus the Blob Storage SDK: pick one, install it, set your API key and make a first call. ## Choose your SDK All SDKs are open source and available on [GitHub](https://go.squarecloud.app/github). They have **zero runtime dependencies** and return the API's own data, field names included. } href="/en/sdks/js/client"> `@squarecloud/api` v6. Apps, databases, workspaces, deploys, network, realtime, snapshots and AI, on Node.js, Deno, Bun and edge runtimes. } href="/en/sdks/py/client"> `squarecloud-api` v5. The same coverage, with a sync and an async client, using only the standard library. `sdk-api-go` v3. The same coverage, with `context` on every call and one error type. `@squarecloud/blob` v4. Uploads up to 10 GiB, private objects, links, shares, rules and the S3 gateway, on Node.js and in the browser. ## At a glance | SDK | Package | Version | Runtime | Install | | - | - | - | - | - | | JavaScript | `@squarecloud/api` | 6.0.0 | Node.js 22+, Deno, Bun, edge | `npm install @squarecloud/api` | | Python | `squarecloud-api` (import `squarecloud`) | 5.0.0 | Python 3.11+ | `pip install squarecloud-api` | | Go | `github.com/squarecloudofc/sdk-api-go/v3` | 3.0.0 | Go 1.22+ | `go get github.com/squarecloudofc/sdk-api-go/v3` | | Blob Storage | `@squarecloud/blob` | 4.0.0 | Node.js 20+ and browsers | `npm install @squarecloud/blob` | ## Quickstart Make your first call in a few minutes. Each program below prints your account name and how many apps your API key can see. Create a key in your [account security settings](https://squarecloud.app/en/account/security). Treat it like a password: keep it out of your source code. The examples read the key from `SQUARECLOUD_API_KEY`. Set it in the terminal where you run them: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` ```powershell theme={"system"} $env:SQUARECLOUD_API_KEY = "your-api-key" ``` ```bash theme={"system"} npm install @squarecloud/api ``` ```javascript index.mjs theme={"system"} 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`); ``` ```bash theme={"system"} node index.mjs ``` ```bash theme={"system"} pip install squarecloud-api ``` ```python main.py theme={"system"} import os from squarecloud import SquareCloud with SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client: me = client.account.me() print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps") ``` ```bash theme={"system"} python main.py ``` ```bash theme={"system"} go mod init example.com/hello go get github.com/squarecloudofc/sdk-api-go/v3 ``` ```go main.go theme={"system"} package main import ( "context" "fmt" "log" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) func main() { c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) me, err := c.Account.Me(context.Background()) if err != nil { log.Fatal(err) } fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications)) } ``` ```bash theme={"system"} go run . ``` The program prints your account name and the number of apps the key can see: ```text theme={"system"} Hi Jane, you have 3 apps ``` A 401 `ACCESS_DENIED` error means the key is wrong, revoked or expired. If the variable is not set, the program stops before sending anything. ## What each SDK covers The **JavaScript**, **Python** and **Go** SDKs cover the whole [Square Cloud API](/en/api-reference/authentication): the same 67 operations, plus downloading snapshot files. They share the same page structure, the same examples and the same behavior: * one error class, with the HTTP status and the API's error code; * a 30-second timeout, and at least 120 seconds for calls the server holds open; * retries only for failures that are safe to repeat, never for a `429`; * `-` ids to act on apps shared through a workspace. The **Blob Storage** SDK covers the [Blob API](/en/blob-reference/authentication) and the [S3 gateway](/en/blob-reference/s3-compatibility). It is a separate package with its own client, credentials and error codes. ## Error references Each SDK page on errors covers its error class, retries and rate limits. The error codes themselves come from the API: the [API error reference](/en/api-reference/errors) lists every one, and the [Blob API errors reference](/en/blob-reference/errors) lists the Blob Storage codes. | SDK | Errors, retries and rate limits | | - | - | | JavaScript | [`SquareCloudAPIError`](/en/sdks/js/errors) | | Python | [`SquareCloudAPIError`](/en/sdks/py/errors) | | Go | [`*APIError`](/en/sdks/go/errors) | | Blob Storage | [`SquareCloudBlobError`](/en/sdks/blob/errors) | ## Upgrading Every API SDK release above is a rewrite. See the migration guides: [JavaScript v5 → v6](/en/sdks/js/migrating_to_v6), [Python v4 → v5](/en/sdks/py/migrating_to_v5), [Go v2 → v3](/en/sdks/go/migrating_to_v3) and [Blob v3 → v4](/en/sdks/blob/migrating_to_v4). Square Cloud keeps improving its SDKs and adding new languages. If yours is missing, [let us know](https://go.squarecloud.app/github). ## Next steps Call the REST API directly, with curl. Deploy and manage apps from the terminal. Upload a file to Blob Storage with curl. # JavaScript SDK: quickstart and client Source: https://docs.squarecloud.app/en/sdks/js/client Install the Square Cloud JavaScript SDK (@squarecloud/api v6), create a client with your API key and follow its conventions: ids, workspace apps and timeouts. This page documents **`@squarecloud/api` v6**, a rewrite of the SDK. Coming from v5? Read the [v5 → v6 migration guide](/en/sdks/js/migrating_to_v6). ## 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](#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 ```bash theme={"system"} npm install @squarecloud/api ``` ```bash theme={"system"} pnpm add @squarecloud/api ``` ```bash theme={"system"} yarn add @squarecloud/api ``` ```bash theme={"system"} bun add @squarecloud/api ``` ```bash theme={"system"} deno add npm:@squarecloud/api ``` ## API key and scopes Create a key at [squarecloud.app/account/security](https://squarecloud.app/en/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`](/en/sdks/js/errors) 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: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` ```powershell theme={"system"} $env:SQUARECLOUD_API_KEY = "your-api-key" ``` ## Creating the client ```typescript theme={"system"} 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`); ``` ```javascript theme={"system"} 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: ```text theme={"system"} Hi Jane, you have 3 apps ``` An empty or whitespace-only key throws a `TypeError` in the constructor, before any request. ### Options ```typescript theme={"system"} 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](#timeouts). | | `maxRetries` | `2` | Retries of safe failures only (up to 3 attempts). A negative value counts as `0`. See [Retries](/en/sdks/js/errors#retries). | | `userAgent` | `squarecloud-sdk-js/` | 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](#account) and [Snapshots](/en/sdks/js/snapshots) | | `api.service` | `status()` | [Platform status](#platform-status) | | `api.apps` | Get, delete, status, lifecycle, logs, metrics, domains, load balancers | [Managing applications](/en/sdks/js/managing_application) | | `api.apps.create` / `commit` | Uploads | [Commit and upload](/en/sdks/js/commit_and_upload) | | `api.apps.files` | File manager | [Managing files](/en/sdks/js/managing_files) | | `api.apps.envs` | Environment variables | [Environment variables](/en/sdks/js/environment_variables) | | `api.apps.deploys` | Webhook and GitHub App deploys | [Deploys](/en/sdks/js/deploys) | | `api.apps.network` | Analytics, logs, DNS, custom domain, cache | [Network](/en/sdks/js/network) | | `api.apps.realtime` | Live logs and status | [Realtime](/en/sdks/js/realtime) | | `api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot` | Backups | [Snapshots](/en/sdks/js/snapshots) | | `api.databases` | Managed databases | [Databases](/en/sdks/js/databases) | | `api.workspaces` | Workspaces, members and shared apps | [Workspaces](/en/sdks/js/workspaces) | | `api.ai` | `chat()` | [AI](/en/sdks/js/ai) | The only runtime exports are `SquareCloudAPI`, `SquareCloudAPIError` and `BASE_URL`. Every other export (`App`, `RuntimeStats`, `ErrorCode`, ...) is a type: ```typescript theme={"system"} 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](/en/api-reference/authentication) 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: ```typescript theme={"system"} const { restart, logs } = api.apps; await restart(appId); console.log(await logs(appId)); ``` ### Workspace apps Every `appId` also accepts the composite form `-` to act on an app shared with you through a [workspace](/en/sdks/js/workspaces). `workspaces.get()` and `workspaces.list()` return raw ids; you build the composite id yourself: ```typescript theme={"system"} 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](/en/sdks/js/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`. ```typescript theme={"system"} 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. ```typescript theme={"system"} 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](/en/sdks/js/snapshots#account-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. ```typescript theme={"system"} 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 Status, lifecycle, logs and metrics. Error class, retries and rate limits. Base URL, authentication and a first request. Deploy and manage apps from the terminal. # JavaScript SDK: upload and commit files Source: https://docs.squarecloud.app/en/sdks/js/commit_and_upload Create applications from a zip with apps.create() and send files to an existing application with apps.commit(), from a path, a Blob or bytes. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Accepted inputs `apps.create()` and `apps.commit()` take: | Input | Where | Notes | | - | - | - | | A file path (`string`) | Node.js, Deno, Bun | Opened with `fs.openAsBlob` and streamed from disk, never read into memory | | `Blob` / `File` | Everywhere | The name of a `File` is used as the filename | | `Uint8Array` (or `Buffer`) | Everywhere | | On edge runtimes and in the browser, pass a `Blob`, `File` or `Uint8Array`: a path only works where `node:fs` exists. Uploads are **limited to 100 MB**. A larger file fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Uploads are streamed and have **no timeout**: pass a `signal` to cancel one. ## Creating an application `apps.create(file)` deploys a `.zip` that contains a [`squarecloud.app`](/en/getting-started/config-file) configuration file at its root. ```typescript theme={"system"} const app = await api.apps.create("./bot.zip"); console.log(app.id, app.name, app.ram, app.cpu, app.language.name, app.language.version); console.log(app.domain); // ".squareweb.app" for web apps, absent otherwise console.log(app.cluster); // the cluster the app was placed on ``` | Field | Description | | - | - | | `id` | The new app's id | | `name` | Name from the config file | | `description` | Present only when set | | `domain` | Full `.squareweb.app` host; absent for non-web apps | | `cluster` | Cluster the app was placed on | | `ram` / `cpu` | Allocated resources | | `language` | `{ name, version }` | ## Committing to an application `apps.commit(appId, file, { path, filename, signal })` uploads a file into an existing app: * A `.zip` is **unpacked** at `path` (the app root by default). * Any other file lands at `path/`. The filename is `filename`, else the file's own name (path or `File`), else `commit.zip`. ```typescript theme={"system"} // Unpack a zip at the root await api.apps.commit(appId, "./build.zip"); // Unpack a zip into /src await api.apps.commit(appId, "./patch.zip", { path: "/src" }); // A single file from memory: /src/index.js await api.apps.commit(appId, new Blob([code]), { path: "/src", filename: "index.js" }); ``` A commit does not restart the app. Call [`apps.restart()`](/en/sdks/js/managing_application#start-stop-and-restart) to apply it. ## Cancelling an upload ```typescript theme={"system"} const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 120_000); try { await api.apps.create("./bot.zip", { signal: controller.signal }); } finally { clearTimeout(timer); } ``` An aborted upload rejects with the signal's `reason`. ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | The file is over 100 MB (checked locally) | | 400 | `INVALID_FILE`, `INVALID_FILENAME` | No file, or a file name with path separators, `..` or control characters | | 400 | `INVALID_PATH` | `path` contains traversal or shell metacharacters (commit) | | 400 | `INSUFFICIENT_MEMORY` | Less than 256 MB of available memory on the plan (create) | | 400 | `COMMIT_FAILED` | The commit could not be applied (commit) | | 400 | `UPLOAD_FAILED`, `STORAGE_UPLOAD_FAILED`, `CLUSTER_SELECTION_FAILED` | The upload could not be processed (create) | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance (create) | | 503 | `UPLOAD_BUSY` | Too many uploads in progress: retried automatically | A local path that cannot be opened throws the file system error, not a `SquareCloudAPIError`. See [Errors](/en/sdks/js/errors) for the full list. ## Next steps List, read, write, move and delete app files. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: environment variables Source: https://docs.squarecloud.app/en/sdks/js/environment_variables Read, add, replace and remove the environment variables of a Square Cloud application with api.apps.envs in the JavaScript SDK (@squarecloud/api). Environment variables live on `api.apps.envs`. Every method takes the app id first and returns the app's variables as a plain `Record`. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. Static apps have no environment variables: every method answers 400 `STATIC_APP_ENV_NOT_SUPPORTED`. A change takes effect on the next [restart](/en/sdks/js/managing_application#start-stop-and-restart). ## Reading the variables ```typescript theme={"system"} const envs = await api.apps.envs.get(appId); console.log(envs.NODE_ENV); ``` ## Adding or updating variables `envs.set(appId, envs)` adds the given keys and overwrites the ones that already exist. Other variables are kept. It returns every variable after the change. ```typescript theme={"system"} const envs = await api.apps.envs.set(appId, { NODE_ENV: "production", LOG_LEVEL: "info", }); ``` ## Replacing every variable `envs.replace(appId, envs)` replaces **all** variables with the given set. Keys not in the object are removed. ```typescript theme={"system"} await api.apps.envs.replace(appId, { NODE_ENV: "production" }); ``` ## Removing variables `envs.delete(appId, keys)` removes the given keys and returns the remaining variables. ```typescript theme={"system"} const remaining = await api.apps.envs.delete(appId, ["LOG_LEVEL"]); ``` ## Limits and errors | Status | Code | When | | - | - | - | | 400 | `STATIC_APP_ENV_NOT_SUPPORTED` | The app is static | | 400 | `INVALID_ENV_CONTENT` | The variables are not a valid object (or, for `delete`, an empty list) | | 400 | `TOO_MANY_ENV_VARS` | The result would have more than 256 variables | | 400 | `ENV_NAME_TOO_LONG` | A key is over 1024 characters | | 400 | `ENV_CONTENT_TOO_LONG` | A value is over 4096 characters | | 400 | `READ_FAILED` | The cluster could not read the variables | ## Next steps Deploy on every push, with a webhook or the GitHub App. The REST endpoints behind these methods. The same actions from the terminal. Set variables from the dashboard, CLI or API and read them at runtime. # JavaScript SDK: manage applications Source: https://docs.squarecloud.app/en/sdks/js/managing_application Fetch, inspect and control your applications with @squarecloud/api: details, status, start, stop, restart, logs, metrics, domains, load balancers and deletion. Every method on this page lives on `api.apps` and takes the app id first. An `appId` can also be the composite `-` of an app shared through a [workspace](/en/sdks/js/workspaces). ```typescript theme={"system"} import { SquareCloudAPI } from "@squarecloud/api"; const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!); const appId = "abc123def456abc123def456"; ``` To list your apps, use [`api.account.me()`](/en/sdks/js/client#account): its `applications` array has every app the key can see. ## Getting an application ```typescript theme={"system"} const app = await api.apps.get(appId); console.log(app.id, app.name, app.language, app.ram, app.cluster, app.created_at); ``` | Field | Type | Description | | - | - | - | | `id` | `string` | App id | | `name` | `string` | Display name | | `desc` | `string?` | Description | | `owner` | `string` | Owner's user id | | `cluster` | `string` | Cluster the app runs on | | `ram` | `number` | Allocated RAM in MB | | `language` | `string` | Runtime language | | `domain` | `string \| null?` | Default `.squareweb.app` host; absent or `null` for non-web apps | | `custom` | `string \| null?` | Custom domain; absent or `null` when none is set | | `created_at` | `string` | Creation date (ISO 8601) | ## Status `status(appId)` returns the live state with **formatted** values: ```typescript theme={"system"} const status = await api.apps.status(appId); console.log(status.status); // e.g. "running", "exited" console.log(status.running); // true console.log(status.cpu); // "0.5%" console.log(status.ram); // "120.4MB" (RAM in use) console.log(status.storage, status.network.total, status.network.now); console.log(status.uptime); // Unix ms of the last start, null when stopped ``` Pass `{ raw: true }` to get **numbers** instead (`cpu` in %, `ram` in MB, `network.total` and `network.now` as `[in, out]` byte pairs): ```typescript theme={"system"} const raw = await api.apps.status(appId, { raw: true }); console.log(raw.cpu, raw.ram, raw.network.total); // 0.5 120.4 [1024, 2048] ``` `uptime` is a **timestamp** (when the app started), not a duration. Use `Date.now() - status.uptime` for how long it has been up. ### Status of every application `statusAll()` returns one summary per app the key can see, in a single request. `cpu` and `ram` are only present while the app runs. ```typescript theme={"system"} for (const { id, running, cpu, ram } of await api.apps.statusAll()) { console.log(id, running ? `${cpu} ${ram}` : "stopped"); } // Only the apps of one workspace const shared = await api.apps.statusAll({ workspaceId }); ``` ## Start, stop and restart ```typescript theme={"system"} await api.apps.start(appId); await api.apps.stop(appId); await api.apps.restart(appId); ``` The server holds these calls open until the container acts, so they wait at least 120 s before timing out. When the platform refuses the action, the call throws a `SquareCloudAPIError` with status **409**, a `code` and an **empty** message: | Code | Meaning | | - | - | | `CONTAINER_ALREADY_STARTED` | `start` on a running app | | `CONTAINER_ALREADY_STOPPED` | `stop` on a stopped app | | `CONTAINER_TEMPORARILY_SUSPENDED` | The app is suspended | | `CONTAINER_NOT_FOUND` | The container does not exist on the cluster | | `CONTAINER_INSUFFICIENT_DISK_SPACE` | Not enough disk to start | | `CONTAINER_NETWORK_CONFLICT` | Network conflict on the cluster | | `ACTION_FAILED` | The cluster could not perform the action | "Already started" and "already stopped" are errors too. If they mean success for you, handle them: ```typescript theme={"system"} import { SquareCloudAPIError } from "@squarecloud/api"; try { await api.apps.start(appId); } catch (error) { if (!(error instanceof SquareCloudAPIError && error.code === "CONTAINER_ALREADY_STARTED")) { throw error; } } ``` ## Logs `logs(appId)` returns the latest console output as one string (`""` when there is none). ```typescript theme={"system"} console.log(await api.apps.logs(appId)); ``` For a live stream of logs, use [Realtime](/en/sdks/js/realtime). ## Metrics `metrics(appId)` returns the last 24 hours, one point every 5 minutes, **newest first**. ```typescript theme={"system"} const [latest] = await api.apps.metrics(appId); console.log(latest.date, latest.cpu, latest.ram, latest.net); ``` ## Domains and load balancers `domains()` lists the default and custom hostnames of every app. `loadBalancers()` lists the domains shared by several apps, with your plan's limit. ```typescript theme={"system"} for (const { app_id, hostname, type } of await api.apps.domains()) { console.log(app_id, hostname, type); // type: "subdomain" | "custom" } const { limit, balancers } = await api.apps.loadBalancers(); for (const { hostname, apps } of balancers) { console.log(hostname, apps.map((app) => app.id)); } ``` To set a custom domain, see [Network](/en/sdks/js/network#custom-domain). ## Deleting an application ```typescript theme={"system"} await api.apps.delete(appId); ``` Deletion is permanent. Create a [snapshot](/en/sdks/js/snapshots) first if you may need the files again. ## Next steps Create an app from a zip or send files to one. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: app file manager Source: https://docs.squarecloud.app/en/sdks/js/managing_files List, read, write, move and delete the files of an application with api.apps.files. Content travels as base64, so binary files round-trip byte for byte. The file manager lives on `api.apps.files`. Every method takes the app id first, then a path inside the app. Paths are at most **256 characters**. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Listing a directory `files.list(appId, path?)` lists a directory (the app root when `path` is omitted). ```typescript theme={"system"} for (const entry of await api.apps.files.list(appId, "/src")) { console.log(entry.type, entry.name, entry.size, entry.lastModified); } ``` | Field | Type | Description | | - | - | - | | `name` | `string` | Entry name | | `type` | `"file" \| "directory"` | Entry kind | | `size` | `number?` | Size in bytes. Absent on some directory entries | | `lastModified` | `number \| null?` | Unix ms (may carry a fraction); `null` when unreadable | A directory that does not exist is 404 `FILE_NOT_FOUND`. A path the file manager does not expose is 403 `BLOCKED_PATH`. ## Reading a file `files.read(appId, path)` returns the file's bytes as a `Uint8Array`. Files are limited to **10 MB**: a larger one is 413 `FILE_TOO_LARGE`. ```typescript theme={"system"} const bytes = await api.apps.files.read(appId, "/config.json"); const text = new TextDecoder().decode(bytes); console.log(JSON.parse(text)); ``` ## Writing a file `files.write(appId, path, content, { signal })` creates or overwrites a file. * A `string` is sent as plain text. * A `Uint8Array` is sent as base64, so any binary content round-trips. * Empty content (`""` or empty bytes) creates an empty file. ```typescript theme={"system"} // Text await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false })); // Binary const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer()); await api.apps.files.write(appId, "/assets/logo.png", image); ``` Content over **10 MB** fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Content over **1 MiB** is sent without a timeout, like an upload: pass `{ signal }` to cancel it. For larger files, use [`apps.commit()`](/en/sdks/js/commit_and_upload). Writing does not restart the app. Call [`apps.restart()`](/en/sdks/js/managing_application#start-stop-and-restart) to apply the change. ## Moving or renaming a file ```typescript theme={"system"} await api.apps.files.move(appId, "/config.json", "/config.old.json"); ``` ## Deleting a file ```typescript theme={"system"} await api.apps.files.delete(appId, "/config.old.json"); ``` ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | `write` content over 10 MB (checked locally) | | 400 | `INVALID_PATH` | The path fails validation (traversal, invalid characters, too long), or `move` to the same path | | 400 | `DELETE_FAILED`, `RENAME_FAILED` | The cluster could not delete or rename the file | | 403 | `BLOCKED_PATH` | The path is not exposed by the file manager | | 403 | `PERMISSION_DENIED` | Your workspace role cannot touch a restricted file (such as `.env`) | | 404 | `FILE_NOT_FOUND` | The file or directory does not exist | | 413 | `FILE_TOO_LARGE` | `read` of a file over 10 MB | | 429 | `KEEP_CALM` | More than 10 writes in 5 seconds | See [Errors](/en/sdks/js/errors) for the codes every call can return. ## Next steps Read and change the variables of an app. The REST endpoints behind these methods. The same actions from the terminal. # Blob Storage: S3-Compatible Object Storage with CDN Source: https://docs.squarecloud.app/en/services/blob S3-compatible object storage with a global CDN, private files, temporary and share links, and no transfer fees. Included in every Square Cloud plan. ## Why choose Square Cloud Blob Storage? As the **largest bot hosting platform in Latin America**, trusted by **80 of the 100 largest Brazilian Discord servers**, we built Blob Storage to solve a problem our own community kept hitting: **Discord's CDN was never meant to be a storage backend**, and links break, expire or get rate-limited. Blob Storage replaces that with an object store designed for durability. The design is simple on purpose: **S3-compatible object storage is the source of truth** for your files, and a **global CDN** delivers them from the edge. You get the **11-nines durability** of an S3 design with the read latency of a global cache, and every plan includes **generous storage**. ## Key features **Zero ingress and egress fees.** Upload and serve as much as you need: you pay for storage, never for bandwidth. Public files are served from a **global CDN**, at the edge, close to your users wherever they are. Store files **without a public URL** and hand them out through [temporary links or share links](/en/blob-reference/links-and-sharing). Switch any file between public and private at any time. Links that **expire**, can be **revoked**, cap the **number of downloads** and, on Pro and Enterprise, ask for a **password**. Use **aws-cli, boto3, rclone** or any AWS SDK through the [S3 gateway](/en/blob-reference/s3-compatibility), with credentials derived from your API key. Your server mints an [upload token](/en/blob-reference/endpoint/upload-tokens) and the **browser uploads directly**, without ever seeing your API key. Set defaults (visibility, expiry, cache), limits (size, file types) and **automatic deletion after N days** for everything under a prefix with [account settings](/en/blob-reference/endpoint/settings-put). [Copy, move and rename](/en/blob-reference/endpoint/copy) files without downloading them, and [change headers](/en/blob-reference/endpoint/update) (cache, disposition, metadata) in place. ## How it works Files come in through the REST API, the browser (with an upload token) or any S3 tool. Each file is either **public** or **private**, and goes out through a public URL, a temporary link or a share link. ## Storage and pricing Storage comes with your plan, and there are no transfer fees: you only ever pay for what stays stored above the quota. ### Included storage Every plan includes storage at no extra cost, and it grows with the plan: | Plan | Storage included | | - | - | | Hobby-1 | **5 GB** | | Hobby-2 | **15 GB** | | Standard-4 | **30 GB** | | Standard-6 | **50 GB** | | Standard-8 | **100 GB** | | Pro-12 | **200 GB** | | Pro-16 and up, Enterprise included | **250 GB** | ### Reaching your quota When your usage reaches the included quota, **new uploads are refused** with `STORAGE_QUOTA_EXCEEDED` until you free space or upgrade your plan. Everything already stored keeps being served normally. Storage held **above** the quota (for example after a plan downgrade) is priced at: **R\$ 0.20 per started GiB** beyond your included quota. [Account Stats](/en/blob-reference/endpoint/stats) reports your current usage, this month's average and the estimated cost of any storage held beyond the quota. Blob Storage is **only available** with an **active plan**. An account without an active plan can still list, download, delete and make files private. When a plan expires or is canceled, stored files enter a **deletion queue**, so renew as soon as possible: files already deleted can't be recovered. ### Features by plan Every plan gets the full API: public and private files, temporary links, share links, the S3 gateway, upload tokens and rules per prefix. A few options depend on the plan, and all of them answer the same `403 UPGRADE_REQUIRED` code, with a `message` naming the plan (or the limit) that applies: | Feature | Available on | | - | - | | Rules per prefix | **5** on Hobby and Standard, **10** on Pro, **20** on Enterprise | | Uploads without the 1-per-second limit | Pro and Enterprise | | Custom metadata (up to 5 keys, 512 bytes) | Pro and Enterprise | | Password-protected share links | Pro and Enterprise | | Expiries and automatic deletion under 7 days (down to 1 hour) | Enterprise | | Files served without edge cache (`no-cache`) | Enterprise | ## Public and private files Every object is either **public** or **private**, and its `id` says which: `pub//` or `prv//`. * **Public files** have a permanent CDN URL: `https://blob.squarecloud.dev/pub//`. * **Private files** have no public URL (`url` is `null`). You read them through a [temporary link](/en/blob-reference/endpoint/download), a [share link](/en/blob-reference/endpoint/shares-create), the API or the [S3 gateway](/en/blob-reference/s3-compatibility). * Legacy files, uploaded before the September 2026 update, keep their original id `/`, and every route accepts it. Their original URL on `https://public-blob.squarecloud.dev//` keeps working for **30 days, until October 25, 2026**: move them with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`) to get a URL on `blob.squarecloud.dev`. Read [Links and sharing](/en/blob-reference/links-and-sharing) for how publishing, unpublishing and the different kinds of links behave. ## Supported file types Practically **any file type is accepted**, including formats with no registered MIME type: `.bam`, `.vcf`, `.fasta`, `.fastq`, `.parquet`, `.h5`, `.npy` and so on. The stored extension comes from the **filename you upload**, and compound compression suffixes are preserved (`reads.fastq.gz` stays `.fastq.gz`). The only exception is a denylist of **executables and installers** (`.exe`, `.msi`, `.bat`, `.apk` and similar), refused with `BLOCKED_FILE_TYPE`. **Serving is safe by design**: the served `Content-Type` is derived server-side, never from the client. Unknown formats and browser-renderable types (`.html`, `.svg`, `.xml`) are always served as **downloads** (`application/octet-stream`), so malicious uploads never render in the browser. ## Performance and durability Blob Storage went through **extensive benchmarks** before launch. Key findings: * **Latency**: files are received in **\~11 ms** on average. * **Durability**: designed for **99.999999999% (11 nines)**. * **Edge delivery**: public files are cached at the CDN edge, so repeated reads never travel back to the origin. * **Health check**: `https://blob.squarecloud.dev/pub/status` answers `OK` and is never cached, so you can point your monitoring at it. **Note**: Benchmark results come from controlled tests and vary with **geographic location**, **file size**, **network quality** and **peak usage**. For the most accurate numbers, test from your production environment. **Regional Limitations**: Users in **Africa** and some **Asian regions** may see higher latencies due to **physical distance from data centers** and **local network infrastructure**. ## How to host your files Create an API key with the `blob:write` scope in your [account settings](https://squarecloud.app/en/account/security). See [Authentication](/en/blob-reference/authentication). Send files up to **100 MB** to [Object Post](/en/blob-reference/endpoint/post). Larger files, up to **10 GiB**, go through the [chunked upload flow](/en/blob-reference/endpoint/chunked-init). Prefer S3 tools? Point them at the [S3 gateway](/en/blob-reference/s3-compatibility) instead. Use the `url` from the response for public files, or create a [temporary link](/en/blob-reference/endpoint/download) or a [share link](/en/blob-reference/endpoint/shares-create) for private ones. For a first upload and download with curl, follow the [Blob Storage API quickstart](/en/blob-reference/quickstart). Using JavaScript? The [Blob SDK](/en/sdks/blob/client) (`@squarecloud/blob`) handles simple and multipart uploads, links, shares, rules and the S3 gateway for you, on Node.js and in the browser. ## Frequently asked questions Blob Storage is available on any **plan**, Hobby and up, each with its own included storage quota (see the table above). See [Plans and Pricing](/en/platform/plans) for the full comparison. New uploads are refused with `STORAGE_QUOTA_EXCEEDED` until you delete objects or upgrade your plan. Everything already stored keeps being served normally. Storage held above the quota (for example after a downgrade) is priced at **R\$ 0.20 per started GiB**, and [Account Stats](/en/blob-reference/endpoint/stats) shows the estimate at any time. A [temporary link](/en/blob-reference/endpoint/download) is valid for **up to 24 hours** and **cannot be revoked**: use it to hand a file to a user right now. A [share link](/en/blob-reference/endpoint/shares-create) lasts **up to 30 days**, **can be revoked**, can cap the number of downloads and, on Pro and Enterprise, can ask for a password. See [Links and sharing](/en/blob-reference/links-and-sharing). Yes. The [S3 gateway](/en/blob-reference/s3-compatibility) at `https://s3-blob.squarecloud.app` works with aws-cli, boto3, rclone and the AWS SDKs. Get the access key pair from [S3 Credentials](/en/blob-reference/endpoint/s3-credentials): it is derived from your API key, so revoking the key revokes the pair. Every plan gets rules per prefix (5 on Hobby and Standard, 10 on Pro, 20 on Enterprise). Custom metadata and password-protected share links need **Pro or Enterprise**. Expiries and automatic deletion under 7 days, and files served without edge cache, need **Enterprise**. Outside those plans the request is refused with `403 UPGRADE_REQUIRED`, and its `message` names the plan that unlocks the feature. For 30 days. Legacy files, uploaded before the September 2026 update, keep their URL on `public-blob.squarecloud.dev` until **October 25, 2026**, and their id `/` keeps working on every route. To keep a public link after that, move the file with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`): new files are served from `blob.squarecloud.dev/pub/...`, and their id starts with `pub/` or `prv/`. # Bot Hosting 24/7: Discord, WhatsApp and Telegram Bots Source: https://docs.squarecloud.app/en/services/bots Host a Discord, WhatsApp or Telegram bot 24/7 on Square Cloud: isolated containers, auto-restart, real-time logs and deploys from the dashboard, CLI or GitHub. ## Why choose Square Cloud? We are the **largest bot hosting platform in Latin America**, trusted by **80 of the 100 largest Brazilian Discord servers**. A bot lives or dies by its uptime and its latency to the Discord, WhatsApp and Telegram gateways, so every layer of our stack, from the hardware to the network edge, is tuned to keep your process online and responsive 24/7. Every bot runs on **enterprise NVMe SSDs** behind **10Gbps** uplinks, in an isolated container with **kernel-enforced CPU and RAM**, so a neighbor's traffic spike never becomes your latency problem. **CLI**, **JavaScript, Python and Go SDKs**, a **[VS Code extension](/en/vscode-extension/installation)** and **GitHub Actions/Webhooks** for CI/CD. Deploy from your terminal, your editor or a `git push`. A **Cloudflare-fronted** edge plus **Square Shield** keeps your bot within the platform API rate limits (Discord and others), preventing the bans and cooldowns that take a bot offline. **One-click restore points** included at no extra cost. Roll back a broken deploy in seconds, with no data loss and no downtime. **Proven at scale:** our reputation was earned running the bots behind some of the busiest communities in Latin America: the kind of sustained, high-event-rate load that quietly exposes weak infrastructure. Yours runs on the same clusters. *** ## Supported environments Build with the platform and language you already use. ### Platforms Discord, WhatsApp, Telegram, Slack and X have a step-by-step guide with code: pick a card to open it. ### Languages Most other languages and libraries run out of the box too. See [supported languages and runtimes](/en/runtimes/introduction). *** ## Main features ### Infrastructure built for always-on workloads Each cluster runs on **enterprise NVMe SSDs** with **10Gbps uplinks**, and your bot runs in an isolated, unprivileged container with dedicated CPU and RAM caps. Isolation is what turns "fast on paper" into fast in production: your process is never fighting a noisy neighbor for I/O or CPU, so response times stay low even under sustained event load. ### Square Shield: staying inside the rate limits Discord, WhatsApp and Telegram ban bots that exceed their gateway and REST rate limits. **Square Shield** sits between your bot and those APIs, monitoring request patterns to keep you within the allowed budget. That is the difference between a bot that scales cleanly and one that gets cooldowned offline at the worst moment. ### Operate with full visibility Restore points let you roll back a bad deploy in seconds, with no data loss and no downtime. Pro and Enterprise plans add automatic daily snapshots on top. Stream your application's stdout/stderr live to debug in production the moment something misbehaves, without redeploying. Track CPU, RAM and network consumption in real time from the dashboard, so you can right-size resources and catch regressions before your users do. ### Development tools Deploy and manage your bot from wherever you work: Deploy, restart, follow logs and manage your applications straight from the terminal. Start with the [CLI quickstart](/en/cli-reference/quickstart). ```bash theme={"system"} npm install -g @squarecloud/cli squarecloud auth login ``` Manage and deploy your applications without leaving your code editor. See how to [install the VS Code extension](/en/vscode-extension/installation). Continuous deployment for your bot: [connect your GitHub repository](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) and every `push` updates the application automatically, or deploy from a workflow with [GitHub Actions](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). Deploying with GitHub Actions needs an [API key](/en/api-reference/authentication) stored in your repository secrets, never in the code. ## How to host my bot? Create a `squarecloud.app` file at the root of your project. It tells **Square Cloud** which file to run, how much memory to reserve and which runtime to use. The [configuration file guide](/en/getting-started/config-file) explains every field. Add `AUTORESTART=true` so your bot restarts on its own after a crash. Keep your dependencies file in the project: `package.json` for Node.js, `requirements.txt` or `pyproject.toml` for Python. Square Cloud installs everything it lists on the server. Leave out built-in modules, such as `fs` in Node.js or `random` in Python, since they come with the language. Compress your code, the configuration file and the dependencies file into a `.zip`. Leave out `node_modules`, lockfiles such as `package-lock.json` and other generated files: dependencies are installed on the server, and a smaller upload deploys faster. The CLI and the VS Code extension leave lockfiles out for you. Need pinned versions? Add `!package-lock.json` to your [squarecloud.ignore](/en/getting-started/squarecloud-ignore) file. Send the `.zip` on the [upload page](https://squarecloud.app/en/dashboard/new). Square Cloud installs the dependencies, sets up the environment from your configuration file and starts your bot. ## Something went wrong? Fix a deploy that fails or crashes on boot: missing modules, `INVALID_DEPENDENCY`, a port already in use or not enough RAM. Invalid tokens, disallowed intents, Lavalink disconnects and a bot that goes offline after working locally. ## Frequently asked questions We recommend the **Standard** plan, from **R$44.99/month** with 4 GB of RAM and 4 vCPUs, which leaves room for busy servers and traffic spikes. A lighter bot also runs on the **Hobby** plan, from **R$12.49/month**: a bot needs at least 256 MB of RAM. See [Plans and Pricing](/en/platform/plans) for the full comparison. Yes. Your bot runs in an isolated container with dedicated CPU and RAM, and Square Cloud's infrastructure averages **99.99% uptime** across the platform. Set `AUTORESTART=true` in your [configuration file](/en/getting-started/config-file) so the bot also restarts on its own after a crash: it is off by default. # Managed Databases: PostgreSQL, MySQL, MongoDB, Redis Source: https://docs.squarecloud.app/en/services/databases Managed PostgreSQL, MySQL, MongoDB and Redis databases: TLS-only connections, NVMe storage, one-click snapshots and no bandwidth fees, from the Standard plan. ## Why choose Square Cloud? Managed PostgreSQL, MySQL, MongoDB and Redis instances, provisioned in a couple of clicks and reachable over an encrypted, certificate-authenticated connection. You get a production database without tuning a server, managing backups or paying for the bandwidth your app moves. Instances run on **enterprise NVMe SSDs**, where random-read latency dominates real-world query performance, so indexed lookups and write-heavy workloads stay fast. **No ingress or egress charges.** Read and write as much as your application needs without a metered-bandwidth bill, a cost that quietly dominates on most cloud providers. **One-click restore points** included at no extra cost. Recover from a bad migration or accidental delete without leaving the dashboard. Instances **only accept SSL/TLS connections** with Square Cloud-managed certificates. Plaintext connections are refused, so your data is encrypted in transit without any extra configuration. ## Supported databases Every engine comes configured and ready to connect. ### Versions | Engine | Version | | :-: | :-: | | PostgreSQL | 17 | | MySQL | 9 | | MongoDB | 8 | | Redis | 8 | ## How do I host my database? You need an **active [Standard plan or higher](/en/platform/plans)**. For a full walkthrough with connection code in Node.js and Python, follow [Create and connect a managed database](/en/tutorials/how-to-deploy-your-database). In short: Open the [Databases](https://squarecloud.app/en/dashboard/databases) page and click "Create Database". Pick the engine and fill in the name and the RAM. Click "Create". In a few seconds the database is ready, and its connection details are on its page in the dashboard. ## How do I connect to my database? Databases only accept encrypted connections authenticated with a certificate. To connect: Open the database in the dashboard, copy the connection URL (host, port, username and password) and download the certificates. Connect with your preferred client or library, with SSL/TLS enabled and the certificates set as the CA (root) certificate and as the client certificate and key. Most clients only need the `.pem`. Some ask for the `.key` and `.cert` files separately, or for a `.p12`. You're ready to store and query data. Follow the database's performance and usage in the Square Cloud dashboard. ## Something went wrong? Fix SSL/TLS errors, timeouts, `ECONNREFUSED`, MySQL "Host is not allowed" and MongoDB network errors. ## Frequently asked questions PostgreSQL, MySQL, MongoDB and Redis, all pre-configured and ready to connect. Database hosting requires an **active [Standard plan or higher](/en/platform/plans)**. # Website and API Hosting: Node.js, Python, Static Sites Source: https://docs.squarecloud.app/en/services/sites Website and API hosting behind Cloudflare: included squareweb.app subdomain, auto-renewing TLS, global CDN, WAF and custom domains on Standard and up. ## Why choose Square Cloud? Every site is served from behind Cloudflare's global network, with free TLS, a free CDN and DDoS protection wired in by default: the same production-grade edge whether you deploy a static landing page or a full framework SSR app. You configure a subdomain; we handle certificates, caching and routing. Every site sits behind the **Cloudflare WAF** with **Square Shield** on top: DDoS mitigation, bot filtering and free, auto-renewing TLS included at no extra cost. **Enterprise NVMe SSDs** and **10Gbps** uplinks, with your app in an isolated container. Paired with a **free global CDN**, static assets are cached at the edge and served close to every visitor. **Bring your own domain, certificate handled for you**: [attach a domain you already own](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) (Standard and up), create the DNS records the dashboard shows at your DNS provider, and Square Cloud issues and renews the TLS certificate as soon as they propagate. **One-click restore points**, included at no extra cost. Recover from a broken deploy in seconds with no data loss and **zero downtime**. ## Supported environments Host your site with the stack you already use. Start with the [website and API hosting guide](/en/tutorials/how-to-deploy-your-website), then pick your framework below: each card opens a step-by-step guide with code. ### Frameworks ### APIs and backends Not on the list? Virtually any other framework or library runs too: if it starts a web server on port 80, it runs on Square Cloud. ### Languages ## Developer ecosystem Deploy and manage your site from wherever you work: * **[Square Cloud CLI](/en/cli-reference/quickstart):** deploy, restart and follow logs from the terminal. * **[VS Code extension](/en/vscode-extension/installation):** manage your applications without leaving the editor. * **GitHub:** every push to your repository can deploy automatically, by [connecting your GitHub repository](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) or from a [GitHub Actions workflow](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). * **[SDKs](/en/sdks/introduction) and [REST API](/en/api-reference/introduction):** automate anything the dashboard does. ## How to host my website? Create a `squarecloud.app` file at the root of your project. The [configuration file guide](/en/getting-started/config-file) explains every field. A website also needs: * **SUBDOMAIN:** the address of your site. `SUBDOMAIN=test` serves it at `test.squareweb.app`. * **MEMORY:** the RAM reserved for it, **512 MB at least**. Set `SUBDOMAIN` before the first upload. An application deployed without it can't become a website later: you would have to upload it again as a new application. Keep your dependencies file in the project: `package.json` for Node.js, `requirements.txt` or `pyproject.toml` for Python. Square Cloud installs everything it lists on the server. Leave out built-in modules, such as `fs` in Node.js or `random` in Python, since they come with the language. Compress your code, the configuration file and the dependencies file into a `.zip`. Leave out `node_modules`, `__pycache__`, lockfiles such as `package-lock.json` and other generated files: dependencies are installed on the server, and a smaller upload deploys faster. The CLI and the VS Code extension leave lockfiles out for you. Need pinned versions? Add `!package-lock.json` to your [squarecloud.ignore](/en/getting-started/squarecloud-ignore) file. Your app must listen on **port 80** and host **`0.0.0.0`**. The runtime images already set the `PORT` and `HOST` [environment variables](/en/platform/environment-variables) to these values, so a server that reads them needs no change. Visitors reach your site over HTTPS, and Square Cloud handles the certificate. Send the `.zip` on the [upload page](https://squarecloud.app/en/dashboard/new). Square Cloud installs the dependencies, sets up the environment from your configuration file and puts your site online. ## Something went wrong? Fix a deploy that fails or crashes on boot: a port already in use, missing modules, `INVALID_DEPENDENCY` or not enough RAM. Find the fix for an error code or a symptom across apps, bots and databases. ## Frequently asked questions We recommend the **Standard** plan, from **R$44.99/month** with 4 GB of RAM and 4 vCPUs, which also unlocks custom domains. A lighter site also runs on the **Hobby** plan, from **R$12.49/month**: a website needs at least 512 MB of RAM. See [Plans and Pricing](/en/platform/plans) for the full comparison. Yes. Every web deploy includes a `*.squareweb.app` subdomain at no extra cost, as part of your plan. It's ready to use as soon as you set the `SUBDOMAIN` field in your configuration file. Custom domains are available from the **Standard** plan and up. Square Cloud does not register or sell domain names: the feature connects a domain you already own at a registrar, one hostname per application (such as `example.com` or `www.example.com`). Follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) for the DNS records, and see [why a domain hasn't propagated yet](https://help.squarecloud.app/en-us/article/why-hasnt-my-domain-propagated-yet-dns-f5jzoy/) if it doesn't load. To attach it from code, use [Set Custom Domain](/en/api-reference/endpoint/apps/network/custom). # Deploy a Django App with Gunicorn Source: https://docs.squarecloud.app/en/tutorials/api/django Deploy a Django app on Square Cloud: read settings from env vars, serve static files with WhiteNoise, and run Gunicorn on port 80 with a START command. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Python runtime](/en/articles/getting-started-with-python). Tested with Django 6 on Python 3.13 in September 2026. ## Create the project You need Python and pip on your machine. If you don't have them, download Python from the [official Python website](https://www.python.org/downloads/). ### Installing libraries Install Django, the Gunicorn production server and WhiteNoise, which serves your static files: ```bash theme={"system"} pip install django gunicorn whitenoise ``` ### Developing project Create a new Django project and enter its folder: ```bash theme={"system"} django-admin startproject mysite cd mysite ``` This creates `manage.py` and a `mysite/` package with `settings.py`, `urls.py` and `wsgi.py`. To add a basic route, edit `mysite/urls.py`: ```python mysite/urls.py theme={"system"} from django.contrib import admin from django.http import HttpResponse from django.urls import path def index(request): return HttpResponse("Hello, World!") urlpatterns = [ path("", index), path("admin/", admin.site.urls), ] ``` ### Configuring settings for production Never hardcode secrets in your code. In `mysite/settings.py`, read the secret key and the production flags from environment variables, trust your site's HTTPS origin and enable WhiteNoise. Keep the rest of the generated settings as they are: ```python mysite/settings.py theme={"system"} import os from pathlib import Path BASE_DIR = Path(__file__).resolve().parent.parent SECRET_KEY = os.environ["DJANGO_SECRET_KEY"] DEBUG = os.environ.get("DJANGO_DEBUG", "False") == "True" ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").split(",") # HTTPS address of your site, required for forms (CSRF) behind the Square Cloud proxy CSRF_TRUSTED_ORIGINS = ["https://mysite.squareweb.app"] MIDDLEWARE = [ "django.middleware.security.SecurityMiddleware", "whitenoise.middleware.WhiteNoiseMiddleware", # right after SecurityMiddleware # ... keep the other middleware generated by Django ] STATIC_URL = "static/" STATIC_ROOT = BASE_DIR / "staticfiles" STORAGES = { "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"}, "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"}, } ``` Replace `mysite.squareweb.app` with your subdomain or custom domain. Then set these [environment variables](/en/platform/environment-variables) in your application, from the dashboard or with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set): | Variable | Value | | - | - | | `DJANGO_SECRET_KEY` | A long random value, for example the output of `python -c "import secrets; print(secrets.token_urlsafe(50))"` | | `DJANGO_DEBUG` | `False` (never `True` in production) | | `DJANGO_ALLOWED_HOSTS` | Your domain, for example `mysite.squareweb.app`. Separate multiple domains with commas | To run the project locally, set `DJANGO_SECRET_KEY` (any value) and `DJANGO_DEBUG=True` in your terminal, then run `python manage.py runserver`. Then list your dependencies in a `requirements.txt` file next to `manage.py`. Square Cloud installs them with pip before starting the app. It must list at least: ```txt requirements.txt theme={"system"} django gunicorn whitenoise ``` ## Choose a production server Django's built-in development server (`runserver`) is not suitable for production use. Use Gunicorn, a production-ready WSGI server, started by the `START` command below. For worker settings and other options, see the Gunicorn guide: Gunicorn is a Python WSGI HTTP server for UNIX. It's a pre-fork worker model, which means that it forks multiple worker processes to handle requests. This makes it a great choice for running python web applications in production. ## Port and host The `START` command below binds Gunicorn to `0.0.0.0:80`: all network interfaces, on the port Square Cloud routes to your app. Django itself has no port setting to change. ## Configure Square Cloud Create a `squarecloud.app` file next to `manage.py`: ```systemd squarecloud.app theme={"system"} MAIN=manage.py MEMORY=512 VERSION=recommended DISPLAY_NAME=My Django app SUBDOMAIN=mysite START=python manage.py collectstatic --noinput && python manage.py migrate --noinput && python -m gunicorn mysite.wsgi --bind 0.0.0.0:80 ``` On every start, this command: * `collectstatic` copies your static files to `STATIC_ROOT`, where WhiteNoise serves them. * `migrate` applies pending database migrations. It does nothing when the database is already up to date. * `python -m gunicorn mysite.wsgi --bind 0.0.0.0:80` serves the WSGI application of the `mysite` project on port 80 and all network interfaces. `MAIN=manage.py` selects the Python runtime. In the dashboard upload, set the same main file and start command. ## What goes in the ZIP * `manage.py` and the `mysite/` package, with your apps and templates. * `requirements.txt`. * `squarecloud.app`. `manage.py`, `requirements.txt` and `squarecloud.app` must be at the root of the ZIP. Leave out `.venv`, `__pycache__`, `staticfiles/` (rebuilt by `collectstatic` on every start) and your local `db.sqlite3`. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### KeyError: 'DJANGO\_SECRET\_KEY' The environment variable is missing. Set `DJANGO_SECRET_KEY` as shown in [Configuring settings for production](#configuring-settings-for-production), then restart the application. ### Bad Request (400) The address you opened is not in `DJANGO_ALLOWED_HOSTS`. Add your subdomain or custom domain to it, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Django, see the [official Django documentation](https://docs.djangoproject.com/en/stable/) and its [deployment checklist](https://docs.djangoproject.com/en/stable/howto/deployment/checklist/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy an Express API Source: https://docs.squarecloud.app/en/tutorials/api/express Deploy an Express API on Square Cloud: read the port from PORT, listen on 0.0.0.0, zip the project with package.json and squarecloud.app, and go live on HTTPS. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Express 5 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project folder with a `package.json`, enable ES modules and install Express: ```bash theme={"system"} mkdir my-express-api cd my-express-api npm init -y npm pkg set type=module npm install express ``` `npm pkg set type=module` lets you use `import` in `.js` files. Then create an `app.js` file: ```javascript app.js theme={"system"} import express from 'express'; const app = express(); app.get('/', (req, res) => { res.send('Hello World!'); }); // Square Cloud sets PORT=80. Listening on 0.0.0.0 accepts connections from outside the container. const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => { console.log(`App listening on port ${port}`); }); ``` To run it on your machine, pick a free port: `PORT=3000 node app.js`, then open `http://localhost:3000`. ## Port and host The code above already does it: it reads the `PORT` environment variable, which Square Cloud sets to `80`, and listens on `0.0.0.0`. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=app.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My Express API SUBDOMAIN=my-express-api ``` Square Cloud starts your API with `node app.js`. In the dashboard upload, set `app.js` as the main file. ## What goes in the ZIP * `app.js` and your other source files. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your `dependencies` on the first start. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Express, see the [official Express documentation](https://expressjs.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a FastAPI App with Uvicorn Source: https://docs.squarecloud.app/en/tutorials/api/fastapi Deploy a FastAPI app on Square Cloud: list fastapi and uvicorn in requirements.txt, start Uvicorn on host 0.0.0.0 and port 80 with a START command, and go live. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Python runtime](/en/articles/getting-started-with-python). Tested with FastAPI and Uvicorn on Python 3.13 in September 2026. ## Create the project You need Python and pip on your machine. If you don't have them, download Python from the [official Python website](https://www.python.org/downloads/). Install FastAPI and Uvicorn, the ASGI server that runs it: ```bash Terminal theme={"system"} pip install fastapi uvicorn ``` Create a `main.py` file: ```python main.py theme={"system"} import os import uvicorn from fastapi import FastAPI app = FastAPI() @app.get("/") def hello_world(): return {"message": "Hello, World!"} if __name__ == "__main__": # Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container. uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 80))) ``` To try it on your machine, pick a free port: `PORT=8000 python main.py`, then open `http://localhost:8000/docs` to see the interactive API documentation. Then list your dependencies in a `requirements.txt` file. Square Cloud installs them with pip before starting the app: ```txt requirements.txt theme={"system"} fastapi uvicorn ``` ## Port and host Uvicorn is a production-ready ASGI server, so you don't need Gunicorn. The `START` command below binds it to host `0.0.0.0` and port `80`: all network interfaces, on the port Square Cloud routes to your app. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=main.py MEMORY=512 VERSION=recommended DISPLAY_NAME=My FastAPI app SUBDOMAIN=my-fastapi-app START=python -m uvicorn main:app --host 0.0.0.0 --port 80 ``` `main:app` means "the `app` object in `main.py`". `MAIN=main.py` selects the Python runtime, and `START` launches Uvicorn directly instead of `python main.py`. In the dashboard upload, set the same main file and start command. For higher traffic, add Uvicorn workers: `START=python -m uvicorn main:app --host 0.0.0.0 --port 80 --workers 4`. Each worker is a separate process, so it uses more memory. ## What goes in the ZIP * `main.py` and your other source files. * `requirements.txt`. * `squarecloud.app`. Leave out `.venv` and `__pycache__`: Square Cloud installs your dependencies itself. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about FastAPI, see the [official FastAPI documentation](https://fastapi.tiangolo.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Fastify API Source: https://docs.squarecloud.app/en/tutorials/api/fastify Deploy a Fastify API on Square Cloud: listen on host 0.0.0.0 and the PORT variable, zip the project with package.json and squarecloud.app, and go live on HTTPS. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Fastify 5 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project folder with a `package.json`, enable ES modules and install Fastify: ```bash theme={"system"} mkdir my-fastify-api cd my-fastify-api npm init -y npm pkg set type=module npm install fastify ``` Then create an `app.js` file: ```javascript app.js theme={"system"} import Fastify from 'fastify'; const fastify = Fastify({ logger: true }); fastify.get('/', async () => { return 'Hello World!'; }); // Fastify listens only on localhost unless you pass a host. // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container. try { await fastify.listen({ port: Number(process.env.PORT) || 80, host: '0.0.0.0' }); } catch (err) { fastify.log.error(err); process.exit(1); } ``` To run it on your machine, pick a free port: `PORT=3000 node app.js`, then open `http://localhost:3000`. ## Port and host Fastify needs both settings in `listen()`. By default it listens only on `localhost`, so requests from outside the container never reach it and your site times out. `host: '0.0.0.0'` makes it listen on all network interfaces, and `process.env.PORT` is `80` on Square Cloud. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=app.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My Fastify API SUBDOMAIN=my-fastify-api ``` Square Cloud starts your API with `node app.js`. In the dashboard upload, set `app.js` as the main file. ## What goes in the ZIP * `app.js` and your other source files. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your `dependencies` on the first start. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Fastify, see the [official Fastify documentation](https://fastify.dev/docs/latest/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Flask Hosting: Deploy a Flask App Source: https://docs.squarecloud.app/en/tutorials/api/flask Deploy a Flask app on Square Cloud: list flask and gunicorn in requirements.txt, start Gunicorn on 0.0.0.0:80 with a START command, and go live on HTTPS. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Python runtime](/en/articles/getting-started-with-python). Tested with Flask 3 on Python 3.13 in September 2026. ## Create the project You need Python and pip on your machine. If you don't have them, download Python from the [official Python website](https://www.python.org/downloads/). Install Flask and Gunicorn, the production server: ```bash theme={"system"} pip install flask gunicorn ``` Create an `app.py` file: ```python app.py theme={"system"} import os from flask import Flask app = Flask(__name__) @app.route("/") def hello_world(): return "Hello, World!" if __name__ == "__main__": # Development server only. Square Cloud sets PORT=80. app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 80))) ``` To try it on your machine, pick a free port: `PORT=5000 python app.py`, then open `http://localhost:5000`. Then list your dependencies in a `requirements.txt` file. Square Cloud installs them with pip before starting the app: ```txt requirements.txt theme={"system"} flask gunicorn ``` ## Choose a production server Flask's built-in server, used by `app.run()`, is meant for development only. In production, run your app with Gunicorn, a WSGI server, through the `START` command below: `app:app` means "the `app` object in `app.py`". Gunicorn is a Python WSGI HTTP server for UNIX. It's a pre-fork worker model, which means that it forks multiple worker processes to handle requests. This makes it a great choice for running python web applications in production. ## Port and host The `START` command binds Gunicorn to `0.0.0.0:80`: all network interfaces, on the port Square Cloud routes to your app. The `app.run()` line reads `PORT` too, for local runs. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=app.py MEMORY=512 VERSION=recommended DISPLAY_NAME=My Flask app SUBDOMAIN=my-flask-app START=python -m gunicorn app:app --bind 0.0.0.0:80 ``` `MAIN=app.py` selects the Python runtime, and `START` replaces the default `python app.py`. `python -m gunicorn` runs the Gunicorn that pip installed, whatever its folder. In the dashboard upload, set the same main file and start command. ## What goes in the ZIP * `app.py` and your other source files. * `requirements.txt`. * `squarecloud.app`. Leave out `.venv` and `__pycache__`: Square Cloud installs your dependencies itself. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### No module named gunicorn `gunicorn` is missing from `requirements.txt`. Add it and upload the file again. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Flask, see the [official Flask documentation](https://flask.palletsprojects.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Laravel Hosting: Deploy a Laravel App Source: https://docs.squarecloud.app/en/tutorials/api/laravel Deploy a Laravel app on Square Cloud: Composer runs on its own, and a START command runs migrations and php artisan serve on port 80, plus APP_KEY and env vars. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [PHP runtime](/en/articles/getting-started-with-php). ## Create the project You need PHP and Composer on your machine. Install the Laravel installer with Composer: ```bash theme={"system"} composer global require laravel/installer ``` Then create a project and start the development server: ```bash theme={"system"} laravel new myapp cd myapp php artisan serve ``` The development server usually listens on `http://localhost:8000`. Here is a basic route in `routes/web.php`: ```php routes/web.php theme={"system"} `php artisan serve` needs both values on the command line: `--host=0.0.0.0 --port=80`. Without `--host=0.0.0.0`, it only listens on `127.0.0.1` and your site times out. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=public/index.php MEMORY=512 VERSION=recommended DISPLAY_NAME=My Laravel app SUBDOMAIN=mylaravelapp START=php artisan migrate --force && php artisan serve --host=0.0.0.0 --port=80 ``` On every start, after Square Cloud installs your dependencies in `vendor/`, this command: * `php artisan migrate --force` applies pending database migrations. `--force` is required to run migrations in production. * `php artisan serve --host=0.0.0.0 --port=80` serves your application from the `public/` folder through Laravel's router, on port 80 and all network interfaces. `MAIN=public/index.php` selects the PHP runtime. In the dashboard upload, set the same main file and start command. ### Environment variables Set these [environment variables](/en/platform/environment-variables) in your application, from the dashboard or with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set), instead of uploading your local `.env` file: | Variable | Value | | - | - | | `APP_KEY` | The output of `php artisan key:generate --show` | | `APP_ENV` | `production` | | `APP_DEBUG` | `false` (never `true` in production) | | `APP_URL` | Your site's address, for example `https://mylaravelapp.squareweb.app` | | `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` | Your database connection. New Laravel projects use SQLite by default | ### Trusting the Square Cloud proxy Square Cloud serves your site over HTTPS through a proxy. To make Laravel generate `https://` links and asset URLs, trust the proxy in `bootstrap/app.php`: ```php bootstrap/app.php theme={"system"} ->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); }) ``` ### Better performance with Swoole `php artisan serve` handles one request at a time. For higher traffic, the PHP runtime already includes Swoole: run your application on it with Laravel Octane (`composer require laravel/octane`). Run PHP applications on Swoole on Square Cloud. ## What goes in the ZIP * Your whole project: `app/`, `bootstrap/`, `config/`, `database/`, `public/` (with `public/build` if you use Vite), `resources/`, `routes/`, `storage/`, `artisan`, `composer.json` and `composer.lock`. * `squarecloud.app`. Leave out `vendor/` and `node_modules/` (Square Cloud installs `vendor/` on the server) and your local `.env` file. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### No application encryption key has been specified `APP_KEY` is missing. Generate one with `php artisan key:generate --show`, set it as an environment variable, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Laravel, see the [official Laravel documentation](https://laravel.com/docs). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a NestJS API Source: https://docs.squarecloud.app/en/tutorials/api/nestjs Deploy a NestJS API on Square Cloud: build dist/ locally with npm run build, set MAIN=dist/main.js, and let the generated code read the PORT variable. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with NestJS 12 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Install the Nest CLI globally and create a project: ```bash theme={"system"} npm install -g @nestjs/cli nest new my-app ``` `nest new` asks for a package manager and installs the dependencies in the new `my-app` folder. Start the development server with `npm run start:dev`; it listens on `http://localhost:3000`. ## Build for production NestJS is written in TypeScript, so compile it to JavaScript before you deploy: ```bash theme={"system"} npm run build ``` The `build` script runs `nest build`, which writes the compiled files to the `dist/` folder. The entry file is `dist/main.js`, the same file the `start:prod` script runs. Don't use `nest start` or `npm run start` in production. The Nest CLI and TypeScript are `devDependencies`, which Square Cloud does not install (it runs with `NODE_ENV=production`). Build on your machine and upload the compiled `dist/` folder. ## Port and host Nothing to change: the generated `src/main.ts` already reads the `PORT` environment variable, which Square Cloud sets to `80`, and Nest listens on all network interfaces by default. Locally, it falls back to port 3000: ```typescript src/main.ts theme={"system"} import { NestFactory } from '@nestjs/core'; import { AppModule } from './app.module.js'; async function bootstrap() { const app = await NestFactory.create(AppModule); await app.listen(process.env.PORT ?? 3000); } await bootstrap(); ``` Projects created with older versions of the Nest CLI may import `./app.module` and end with `bootstrap();`. The `app.listen` line is the one that matters. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=dist/main.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My NestJS API SUBDOMAIN=my-nest-api ``` Square Cloud then runs `node dist/main.js`, the same command as the `start:prod` script. In the dashboard upload, set `dist/main.js` as the main file. ## What goes in the ZIP * `dist/`, the compiled application. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your `dependencies` on the first start. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### The main file is invalid or corrupted `dist/main.js` is missing from the ZIP. Run `npm run build` and check that the `dist/` folder is at the root of the ZIP. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about NestJS, see the [official NestJS documentation](https://docs.nestjs.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Spring Boot App (JAR) Source: https://docs.squarecloud.app/en/tutorials/api/spring-boot Deploy a Spring Boot app on Square Cloud: read the port from PORT in application.properties, build the JAR with Maven or Gradle, then zip and upload it. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Java runtime](/en/articles/getting-started-with-java), which uses JDK 25. ## Create the project You need a Java Development Kit (JDK) on your machine. Generate a project on [Spring Initializr](https://start.spring.io/) with the **Spring Web** dependency, download it and unzip it. The examples below use the default artifact name, `demo`. ## Port and host Spring Boot does not read the `PORT` environment variable by itself. Set it in `src/main/resources/application.properties`: ```properties src/main/resources/application.properties theme={"system"} server.port=${PORT:80} server.address=0.0.0.0 ``` `${PORT:80}` uses the `PORT` variable, which Square Cloud sets to `80`, and falls back to 80. To run the app on another port locally, set `PORT`, for example `PORT=8080 ./mvnw spring-boot:run`. `server.address=0.0.0.0` makes the server listen on all network interfaces. ## Build for production Square Cloud does not compile Java projects: build an executable JAR on your machine. ```bash Maven theme={"system"} ./mvnw clean package ``` ```bash Gradle theme={"system"} ./gradlew bootJar ``` On Windows, run `mvnw.cmd clean package` or `gradlew.bat bootJar`. Maven writes the JAR to `target/demo-0.0.1-SNAPSHOT.jar` and Gradle to `build/libs/demo-0.0.1-SNAPSHOT.jar`. Build with JDK 25 or an earlier version: the runtime cannot run classes compiled for a newer Java. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project and point `MAIN` to the JAR: ```systemd squarecloud.app theme={"system"} MAIN=target/demo-0.0.1-SNAPSHOT.jar MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Spring Boot app SUBDOMAIN=my-spring-app ``` Square Cloud starts it with `java -jar target/demo-0.0.1-SNAPSHOT.jar`. In the dashboard upload, set the same main file. `MAIN` accepts up to 32 characters. The Gradle path, `build/libs/demo-0.0.1-SNAPSHOT.jar`, is longer: replace the `MAIN` line with `RUNTIME=java` and `START=java -jar build/libs/demo-0.0.1-SNAPSHOT.jar`. ## What goes in the ZIP * The JAR, in the path set in `MAIN`. * `squarecloud.app`. The executable JAR already contains your compiled code and its dependencies, so the source code is optional. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### UnsupportedClassVersionError The JAR was compiled for a newer Java than the runtime's JDK 25. Build it with JDK 25 or earlier, or set `java.version` in your `pom.xml` (or the toolchain in `build.gradle`) to 25 or lower. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Spring Boot, see the [official Spring Boot documentation](https://docs.spring.io/spring-boot/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Host a Discord Bot 24/7 Source: https://docs.squarecloud.app/en/tutorials/bots/discord Host your Discord bot 24/7 on Square Cloud: create the token, write a discord.js or discord.py bot, deploy it and keep it online. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs) or the [Python runtime](/en/articles/getting-started-with-python). ## Create the project You need a Discord account to create and manage bots. If you don't have one, create it on the [official Discord website](https://discord.com/). ### Bot application on Discord Access the [Developer Portal](https://discord.com/developers/applications) and click "New Application". Define a name for your bot and click "Create" to create the application. After creating the application, navigate to the "Bot" tab and click "Reset Token" to generate the authentication token. Copy it: you will set it as an environment variable on Square Cloud, never in your code. The example bot reads the text of messages, so it needs the **Message Content Intent**. Stay in the "Bot" tab, scroll down to "Privileged Gateway Intents" and turn on **Message Content Intent**. This example doesn't need the other two privileged intents (Presence and Server Members). **Keep your token secret**: this token grants total control over the bot. Never write it in your code or put it in your ZIP: the examples below read it from the `DISCORD_TOKEN` environment variable. ## Develop the bot Write the bot with discord.js (Node.js) or discord.py (Python): 1. Verify that Node.js is installed on your system. If not, download it from the [official Node.js website](https://nodejs.org/). 2. Initialize a new Node.js project: ```bash Terminal theme={"system"} npm init -y ``` 3. Install the discord.js library: ```bash Terminal theme={"system"} npm install discord.js ``` 4. Create a JavaScript file (e.g., `index.js`) and add the following code to create a basic Discord bot: ```javascript index.js theme={"system"} const { Client, Events, GatewayIntentBits } = require("discord.js"); const client = new Client({ intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, // Privileged: turn on "Message Content Intent" in the Developer Portal GatewayIntentBits.MessageContent, ], }); client.once(Events.ClientReady, (readyClient) => { console.log(`Logged in as ${readyClient.user.tag}`); }); client.on(Events.MessageCreate, (message) => { if (message.author.bot) return; if (message.content === "!hello") { message.reply("Hello!"); } }); // The token comes from the DISCORD_TOKEN environment variable client.login(process.env.DISCORD_TOKEN); ``` The code uses discord.js v14, where the ready event is `Events.ClientReady` (`"clientReady"`). The old `"ready"` name is deprecated. 1. Verify that Python is installed on your system. If not, download it from the [official Python website](https://www.python.org/). 2. Install the discord.py library using pip: ```bash Terminal theme={"system"} pip install discord.py ``` 3. Create a Python file (e.g., `main.py`) and add the following code to create a basic Discord bot: ```python main.py theme={"system"} import os import discord from discord.ext import commands intents = discord.Intents.default() # Privileged: turn on "Message Content Intent" in the Developer Portal intents.message_content = True bot = commands.Bot(command_prefix="!", intents=intents) @bot.event async def on_ready(): print(f"Logged in as {bot.user}") @bot.command() async def hello(ctx): await ctx.reply("Hello!") # The token comes from the DISCORD_TOKEN environment variable bot.run(os.environ["DISCORD_TOKEN"]) ``` 4. Create a `requirements.txt` file to list all external libraries needed for your project: ```txt requirements.txt theme={"system"} discord.py ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project, next to your main file. It tells Square Cloud how to run your bot: ```systemd Discord.js theme={"system"} DISPLAY_NAME=My Discord Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true ``` ```systemd Discord.py theme={"system"} DISPLAY_NAME=My Discord Bot MAIN=main.py MEMORY=512 VERSION=recommended AUTORESTART=true ``` * `MAIN` is the file Square Cloud runs, and `MEMORY` is the bot's RAM in MB. Bots need at least 256 MB; 512 MB leaves room to grow. * `AUTORESTART=true` starts the bot again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: a bot doesn't serve web pages. When you upload from the dashboard, the upload form can fill in these settings for you. See the [configuration file reference](/en/getting-started/config-file) for every field. ## Set the bot token Your code reads the token from the `DISCORD_TOKEN` environment variable, so the token never goes into your files. Set it in one of these ways: * **Dashboard**: on the upload page, open **Advanced configuration** and add a variable named `DISCORD_TOKEN` with your token as the value. For a bot that is already deployed, add it on the application's **Environment Variables** page and restart the bot. * **CLI**: right after you upload the bot (see [Deploy and verify](#deploy-and-verify)), set it with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) and restart the bot: ```bash theme={"system"} squarecloud app env set DISCORD_TOKEN=your_token_here squarecloud app restart ``` The bot reads its environment variables when it starts, so restart it after every change. See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. To run the bot on your computer first, set the variable in your terminal: `export DISCORD_TOKEN=your_token_here` on macOS and Linux, or `$env:DISCORD_TOKEN="your_token_here"` in PowerShell. ## What goes in the ZIP * Your main file (`index.js` or `main.py`) and your other source files. * `package.json` or `requirements.txt`. * `squarecloud.app`. Leave out `node_modules`, `.venv` and `__pycache__`: Square Cloud installs your dependencies when the bot starts. ## Deploy and verify Create the ZIP described above, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Invite the bot to your server To send the bot a command, add it to a Discord server: 1. Access the [Developer Portal](https://discord.com/developers/applications) and select your bot. 2. Navigate to the "OAuth2" tab and go to "OAuth2 URL Generator". 3. Under "Scopes", check the "bot" option. 4. Under "Bot Permissions", check only what the example needs: **View Channels**, **Send Messages** and **Read Message History**. Avoid **Administrator**: bots rarely need it, and a leaked token would then control your whole server. 5. Copy the generated URL, open it in your browser and add the bot to your server. The URL looks like this: ```txt theme={"system"} https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=68608&scope=bot ``` `68608` is the sum of those three permissions. Replace `YOUR_CLIENT_ID` with your application's ID, shown on the "General Information" tab. If you add commands that need more permissions, generate a new URL with them checked. Then send `!hello` in a channel the bot can see. It replies with `Hello!`. ## Common errors ### An invalid token was provided The logs show `Error [TokenInvalid]: An invalid token was provided.` (discord.js) or `discord.errors.LoginFailure: Improper token has been passed.` (discord.py). The `DISCORD_TOKEN` variable is missing or holds an old token. Copy the current token from the "Bot" tab, set it again and restart the bot. With discord.py, a `KeyError: 'DISCORD_TOKEN'` means the variable is not set at all. ### Used disallowed intents The logs show `Error [DisallowedIntents]: Privileged intent provided is not enabled or whitelisted.` (discord.js) or `discord.errors.PrivilegedIntentsRequired` (discord.py). The code asks for the Message Content Intent, but it is off in the Developer Portal. Turn it on in the "Bot" tab, as in [Bot application on Discord](#bot-application-on-discord), then restart the bot. ### The bot is online but doesn't answer `!hello` Check that the bot can view and send messages in that channel, and that the Message Content Intent is on: without it, the bot receives messages with empty text. For more messages and fixes, see [Discord bot errors](/en/platform/troubleshooting/discord-bot-errors). ## Next steps Fix an invalid token, missing intents and other common errors. Manage your bot's token and other secrets. Host a Lavalink server to play music in your bot. For more about these libraries, see the [official discord.py documentation](https://discordpy.readthedocs.io/en/latest/) and the [official discord.js guide](https://discordjs.guide/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Host a Slack Bot Source: https://docs.squarecloud.app/en/tutorials/bots/slack Host a Slack bot on Square Cloud with Bolt for JavaScript or Python: create the tokens, run it in Socket Mode with no public URL, deploy and test it. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs) or the [Python runtime](/en/articles/getting-started-with-python). ## Create the project To create a Slack bot, you will need an account and permissions to create apps on Slack. Create or access your account on [Slack](https://slack.com/) before following the next steps. ### Bot application on Slack 1. Go to the [Slack API - Your Apps](https://api.slack.com/apps) and click "Create New App". 2. Choose "From scratch", give the app a name and select the workspace where you will install it. 3. In the "Socket Mode" section, enable Socket Mode and generate an *app-level token* with the `connections:write` scope. Copy it (it starts with `xapp-`): this is your `SLACK_APP_TOKEN`. 4. In the "OAuth & Permissions" section, add the scopes your bot needs (e.g. `chat:write`, `app_mentions:read`, `commands`), install the app to your workspace and copy the *Bot User OAuth Token* (it starts with `xoxb-`): this is your `SLACK_BOT_TOKEN`. 5. In "Event Subscriptions", enable events and subscribe to the `app_mention` bot event. In "Slash Commands", create the `/hello` command. With Socket Mode enabled, neither asks for a Request URL. **Security:** Never expose the app-level token or the Bot Token publicly. Treat them as sensitive credentials: the examples below read them from environment variables, never from your code. With Socket Mode, the bot opens the connection to Slack itself, so it runs like any other bot: no public URL or port is needed. If you prefer Slack to send events over HTTP, see [Use HTTP mode instead of Socket Mode](#use-http-mode-instead-of-socket-mode). ## Develop the bot Use the tab for the language you choose. Both examples reply to mentions and to the `/hello` slash command. 1. Make sure Node.js is installed. 2. Initialize a project and install dependencies: ```bash Terminal theme={"system"} npm init -y npm install @slack/bolt ``` 3. Create an `index.js` file with the following content: ```javascript index.js theme={"system"} const { App } = require('@slack/bolt'); const app = new App({ token: process.env.SLACK_BOT_TOKEN, appToken: process.env.SLACK_APP_TOKEN, // Socket Mode: the bot connects to Slack, so no public URL is needed socketMode: true, }); // Responds when mentioned app.event('app_mention', async ({ event, say }) => { await say(`<@${event.user}> Thanks for mentioning me!`); }); // Example slash command app.command('/hello', async ({ ack, respond }) => { await ack(); await respond('Hello from Square Cloud!'); }); (async () => { await app.start(); console.log('⚡️ Slack Bolt app is running!'); })(); ``` 1. Make sure Python and pip are installed. 2. Install the Bolt for Python library: ```bash Terminal theme={"system"} pip install slack_bolt ``` 3. Create an `app.py` file with the following content: ```python app.py theme={"system"} import os from slack_bolt import App from slack_bolt.adapter.socket_mode import SocketModeHandler app = App(token=os.environ.get('SLACK_BOT_TOKEN')) @app.event('app_mention') def handle_mention(event, say): user = event.get('user') say(f'<@{user}> Thanks for mentioning me!') @app.command('/hello') def hello_command(ack, respond): ack() respond('Hello from Square Cloud!') if __name__ == '__main__': # Socket Mode: the bot connects to Slack, so no public URL is needed SocketModeHandler(app, os.environ.get('SLACK_APP_TOKEN')).start() ``` 4. For Python projects, include a `requirements.txt` with: ```txt requirements.txt theme={"system"} slack_bolt ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project, next to your main file. It tells Square Cloud how to run your bot: ```systemd Node.js theme={"system"} DISPLAY_NAME=My Slack Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true ``` ```systemd Python theme={"system"} DISPLAY_NAME=My Slack Bot MAIN=app.py MEMORY=512 VERSION=recommended AUTORESTART=true ``` * `MAIN` is the file Square Cloud runs, and `MEMORY` is the bot's RAM in MB. Bots need at least 256 MB; 512 MB leaves room to grow. * `AUTORESTART=true` starts the bot again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: in Socket Mode, the bot needs no public URL. See the [configuration file reference](/en/getting-started/config-file) for every field. ## Set the tokens Your code reads both tokens from the `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` environment variables, so they never go into your files. Set them in one of these ways: * **Dashboard**: on the upload page, open **Advanced configuration** and add both variables. For a bot that is already deployed, add them on the application's **Environment Variables** page and restart the bot. * **CLI**: right after you upload the bot (see [Deploy and verify](#deploy-and-verify)), set them with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) and restart the bot: ```bash theme={"system"} squarecloud app env set SLACK_BOT_TOKEN=xoxb-your-token SLACK_APP_TOKEN=xapp-your-token squarecloud app restart ``` The bot reads its environment variables when it starts, so restart it after every change. See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. ## What goes in the ZIP * Your main file (`index.js` or `app.py`) and your other source files. * `package.json` or `requirements.txt`. * `squarecloud.app`. Leave out `node_modules`, `.venv` and `__pycache__`: Square Cloud installs your dependencies when the bot starts. ## Deploy and verify Create the ZIP described above, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Test the bot 1. In the Slack app settings, under "OAuth & Permissions", install the app to the workspace (if you haven't already). 2. Check the application logs in the Square Cloud dashboard for startup errors. With Socket Mode there is no Request URL to configure: the bot connects to Slack as soon as it starts. 3. Invite the bot to a channel, then mention it or run the `/hello` command to validate responses. Example install link (replace the client\_id): ```txt theme={"system"} https://slack.com/oauth/v2/authorize?client_id=000000000000.000000000000&scope=commands,chat:write,app_mentions:read ``` ## Common errors ### You must provide an appToken when socketMode is set to true Bolt for JavaScript stops at startup with this message when `SLACK_APP_TOKEN` is not set. Set the app-level token (the one that starts with `xapp-`) and restart the bot. ### Either an env variable `SLACK_BOT_TOKEN` or `token` argument in the constructor is required Bolt for Python stops at startup with this message when `SLACK_BOT_TOKEN` is not set. Set the Bot User OAuth Token (the one that starts with `xoxb-`) and restart the bot. ### The bot doesn't answer mentions Check that the bot is a member of the channel, that "Event Subscriptions" subscribes to the `app_mention` bot event, and that you reinstalled the app after adding scopes. ## Use HTTP mode instead of Socket Mode Apps that use Socket Mode can't be listed in the public Slack Marketplace. If you need Slack to send events over HTTP instead, run the bot as a web application: 1. In the Slack app settings, disable Socket Mode and copy the *Signing Secret* (under "Basic Information") into a `SLACK_SIGNING_SECRET` environment variable, set the same way as the tokens. 2. Create the app with the signing secret instead of the app-level token, and listen on the port in the `PORT` environment variable: ```javascript index.js theme={"system"} const app = new App({ token: process.env.SLACK_BOT_TOKEN, signingSecret: process.env.SLACK_SIGNING_SECRET, }); (async () => { // Square Cloud sets PORT=80 await app.start(Number(process.env.PORT) || 80); console.log('⚡️ Slack Bolt app is running!'); })(); ``` ```python app.py theme={"system"} app = App( token=os.environ.get('SLACK_BOT_TOKEN'), signing_secret=os.environ.get('SLACK_SIGNING_SECRET') ) if __name__ == '__main__': # Square Cloud sets PORT=80 app.start(port=int(os.environ.get('PORT', 80))) ``` Both servers listen on all network interfaces (`0.0.0.0`), which Square Cloud requires. 3. Add a `SUBDOMAIN` to your configuration file (or select "Web Publication" and set a subdomain when uploading from the dashboard) so the bot gets a public URL. Web applications need at least `MEMORY=512`: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My Slack Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true SUBDOMAIN=my-slack-bot ``` An application uploaded without a subdomain can't get one later. If your bot already runs in Socket Mode, upload the HTTP version as a new application. 4. In "Event Subscriptions" and in the `/hello` slash command, set the Request URL to `https://.squareweb.app/slack/events`. ## Next steps Fix missing modules, memory errors and other startup failures. Manage your bot's tokens and other secrets. Host a Discord bot next to your Slack bot. For more about Bolt, see the official Slack documentation for [Bolt for JavaScript](https://docs.slack.dev/tools/bolt-js/) and [Bolt for Python](https://docs.slack.dev/tools/bolt-python/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Host a Telegram Bot 24/7 Source: https://docs.squarecloud.app/en/tutorials/bots/telegram Host your Telegram bot 24/7 on Square Cloud: get a token from BotFather, write a grammY or pyTelegramBotAPI bot, deploy it and test it. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs) or the [Python runtime](/en/articles/getting-started-with-python). ## Create the project A Telegram account is essential for testing and interacting with your bot. If you don't have one, visit the [official Telegram website](https://telegram.org/) to create your account. ### Bot application on Telegram Access [Telegram Web](https://web.telegram.org/a/) and search for the official **BotFather** bot, responsible for creating and managing bots on the platform. Start a conversation with BotFather and type `/start`. Then, select the `/newbot` option to create a new bot. The system will ask for a name for your bot and, after confirmation, will automatically generate the necessary authentication token. **Keep your token secret**: this token grants full control over the bot. Never write it in your code or put it in your ZIP: the examples below read it from the `TELEGRAM_BOT_TOKEN` environment variable. ## Develop the bot Write the bot with grammY (Node.js) or pyTelegramBotAPI (Python). Both examples echo every text message: 1. Verify that Node.js is installed on your system. Otherwise, download it from the [official Node.js website](https://nodejs.org/). 2. Initialize a new Node.js project: ```bash Terminal theme={"system"} npm init -y ``` 3. Install the grammY library: ```bash Terminal theme={"system"} npm install grammy ``` 4. Create the main file (`index.js`) with the following structure: ```javascript index.js theme={"system"} const { Bot } = require("grammy"); // The token comes from the TELEGRAM_BOT_TOKEN environment variable const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN); // Reply to every text message with an echo bot.on("message:text", async (ctx) => { await ctx.reply(`${ctx.me.username} responds: ${ctx.message.text}`); }); // Long polling: the bot asks Telegram for new messages, so no public URL is needed bot.start({ onStart: (botInfo) => console.log(`Bot ${botInfo.username} started successfully!`), }); ``` 1. Verify that Python and pip are installed. Otherwise, download them from the [official Python website](https://www.python.org/). 2. Install the pyTelegramBotAPI library: ```bash Terminal theme={"system"} pip install pyTelegramBotAPI ``` 3. Create the main file (`main.py`): ```python main.py theme={"system"} import os import telebot # The token comes from the TELEGRAM_BOT_TOKEN environment variable bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"]) bot_name = bot.get_me().username # Echo every message that isn't a command @bot.message_handler(func=lambda message: not message.text.startswith("/")) def echo_handler(message): bot.reply_to(message, f"{bot_name} responds: {message.text}") if __name__ == "__main__": print(f"Bot {bot_name} started successfully!") # Long polling: no public URL is needed bot.infinity_polling() ``` 4. Create the `requirements.txt` file to manage dependencies: ```txt requirements.txt theme={"system"} pyTelegramBotAPI ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project, next to your main file. It tells Square Cloud how to run your bot: ```systemd grammY theme={"system"} DISPLAY_NAME=My Telegram Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true ``` ```systemd telebot theme={"system"} DISPLAY_NAME=My Telegram Bot MAIN=main.py MEMORY=512 VERSION=recommended AUTORESTART=true ``` * `MAIN` is the file Square Cloud runs, and `MEMORY` is the bot's RAM in MB. Bots need at least 256 MB; 512 MB leaves room to grow. * `AUTORESTART=true` starts the bot again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: with long polling, the bot needs no public URL. See the [configuration file reference](/en/getting-started/config-file) for every field. ## Set the bot token Your code reads the token from the `TELEGRAM_BOT_TOKEN` environment variable, so the token never goes into your files. Set it in one of these ways: * **Dashboard**: on the upload page, open **Advanced configuration** and add a variable named `TELEGRAM_BOT_TOKEN` with your token as the value. For a bot that is already deployed, add it on the application's **Environment Variables** page and restart the bot. * **CLI**: right after you upload the bot (see [Deploy and verify](#deploy-and-verify)), set it with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) and restart the bot: ```bash theme={"system"} squarecloud app env set TELEGRAM_BOT_TOKEN=your_token_here squarecloud app restart ``` The bot reads its environment variables when it starts, so restart it after every change. See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. To run the bot on your computer first, set the variable in your terminal: `export TELEGRAM_BOT_TOKEN=your_token_here` on macOS and Linux, or `$env:TELEGRAM_BOT_TOKEN="your_token_here"` in PowerShell. ## What goes in the ZIP * Your main file (`index.js` or `main.py`) and your other source files. * `package.json` or `requirements.txt`. * `squarecloud.app`. Leave out `node_modules`, `.venv` and `__pycache__`: Square Cloud installs your dependencies when the bot starts. ## Deploy and verify Create the ZIP described above, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Test the bot After the deploy, find your bot on Telegram and send it a message. The bot replies with the same text, which confirms it is running. ## Common errors ### Error 409: Conflict: terminated by other getUpdates request Another copy of the bot is reading updates with the same token, for example the one you started on your computer. Telegram delivers updates to only one long polling connection per bot. Stop the other copy, or revoke the token in BotFather if you don't know where it runs, then set the new token and restart the bot. ### Error 401: Unauthorized The token is wrong or was revoked. Copy the current token from BotFather, set it again and restart the bot. ### Empty token or `KeyError: 'TELEGRAM_BOT_TOKEN'` The `TELEGRAM_BOT_TOKEN` variable is not set: grammY stops with `Empty token!`, and the Python example stops with a `KeyError`. Set the variable, as in [Set the bot token](#set-the-bot-token), and restart the bot. ## Next steps Fix missing modules, memory errors and other startup failures. Manage your bot's token and other secrets. Using python-telegram-bot? Fix frequent NetworkError exceptions. For more about these libraries, see the [official grammY documentation](https://grammy.dev/) and the [pyTelegramBotAPI page on PyPI](https://pypi.org/project/pyTelegramBotAPI/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Host a WhatsApp Bot 24/7 Source: https://docs.squarecloud.app/en/tutorials/bots/whatsapp Host a WhatsApp bot 24/7 on Square Cloud with whatsapp-web.js or Baileys: scan the QR Code from the logs, keep the session saved and deploy. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). ## Create the project You need WhatsApp installed on your phone to link the bot to your account. If you don't have the app, visit the [official WhatsApp website](https://www.whatsapp.com/download) for download and setup. 1. **Node.js verification**: Confirm that Node.js is installed on your system. Otherwise, download it from the [official Node.js website](https://nodejs.org/). 2. **Project initialization**: Set up a new Node.js project by running the initialization command: ```bash Terminal theme={"system"} npm init -y ``` 3. **Dependencies installation**: Install the essential libraries for bot functionality: ```bash Terminal theme={"system"} npm install whatsapp-web.js qrcode-terminal ``` ## Develop the bot Create the `index.js` file with the bot's base structure: ```javascript index.js theme={"system"} // Import necessary modules const { Client, LocalAuth } = require("whatsapp-web.js"); const qrcode = require("qrcode-terminal"); // Create a new WhatsApp client instance const client = new Client({ // Save the session in the .wwebjs_auth folder, so restarts don't ask for a new QR Code authStrategy: new LocalAuth(), puppeteer: { // Run Chrome in headless mode (without graphical interface) headless: true, args: [ // Disable Chrome sandboxing features // Required for execution in containerized environments "--no-sandbox", // Additional sandboxing flag to disable setuid sandbox "--disable-setuid-sandbox", ], }, }); // Event listener for QR Code generation client.on("qr", (qr) => { // Print the QR Code in the logs, so you can scan it from the Square Cloud dashboard qrcode.generate(qr, { small: true }); console.log("Scan the QR Code above in WhatsApp: Linked devices > Link a device"); }); // Event listener for client ready client.on("ready", () => { // Confirmation log when WhatsApp Web session is established console.log("WhatsApp client successfully initialized!"); }); // Event listener for created messages client.on("message_create", (msg) => { // Log message content to console console.log("Message received:", msg.body); // Test command implementation if (msg.body === "!ping") { // Automatic response for ping command msg.reply("pong - Bot working correctly!"); } }); // Initialize WhatsApp client client.initialize(); ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project, next to `index.js`. It tells Square Cloud how to run your bot: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My WhatsApp Bot MAIN=index.js MEMORY=1024 VERSION=recommended AUTORESTART=true ``` * `MEMORY` is the bot's RAM in MB. whatsapp-web.js runs a headless Chromium browser, so give it at least 1024 MB. * `AUTORESTART=true` starts the bot again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: the bot doesn't serve web pages. See the [configuration file reference](/en/getting-started/config-file) for every field. ## What goes in the ZIP * `index.js` and your other source files. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your dependencies when the bot starts. Also leave out the `.wwebjs_auth` and `.wwebjs_cache` folders that a run on your computer creates, so the bot links its own session on Square Cloud. If you upload with the CLI, list both folders in your [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) file. ## Deploy and verify Create the ZIP described above, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Link your WhatsApp account Open the application logs in the Square Cloud dashboard. On first boot, the bot prints a QR Code there: on your phone, open WhatsApp, go to **Linked devices** > **Link a device** and scan it. The `WhatsApp client successfully initialized!` message confirms the session is active. Then send `!ping` from another number to the linked WhatsApp account and confirm it replies with `pong - Bot working correctly!`. `LocalAuth` saves the session in the `.wwebjs_auth` folder, so restarts reconnect without a new QR Code. To link a different number, delete that folder and restart the application. ## Common errors ### The QR Code can't be scanned The QR Code is drawn with text characters, and WhatsApp replaces it periodically, so scan the most recent one. If your phone can't read it, zoom out until the whole code fits on screen, or switch the dashboard to the dark theme. ### Login stopped working after a WhatsApp Web update Update the library with `npm install whatsapp-web.js@latest` and deploy again. Avoid pinning an old WhatsApp Web version with the `webVersionCache` option: outdated versions tend to break login. ### The bot runs out of memory whatsapp-web.js runs a headless Chromium browser, which needs memory. Keep `MEMORY` at 1024 MB or more, or switch to [Baileys](#use-baileys-instead-of-whatsapp-webjs), which runs without a browser. ## Use Baileys instead of whatsapp-web.js [Baileys](https://github.com/WhiskeySockets/Baileys) is an alternative library that connects to WhatsApp's multi-device API directly over a WebSocket, without launching a headless browser. Since there's no Chromium/Puppeteer instance to run, it uses significantly less RAM than whatsapp-web.js. Baileys saves its session (the `creds.json` file and keys) in the `auth` folder through `useMultiFileAuthState`. Square Cloud keeps your application's files between restarts, so you only need to scan the QR Code again if you log out or delete that folder. As with `.wwebjs_auth`, leave a local `auth` folder out of your ZIP. 1. Install the library: ```bash Terminal theme={"system"} npm install @whiskeysockets/baileys qrcode-terminal ``` 2. Create an `index.js` file using `makeWASocket` and `useMultiFileAuthState` to load and persist the session: ```javascript index.js theme={"system"} const { makeWASocket, useMultiFileAuthState } = require("@whiskeysockets/baileys"); const qrcode = require("qrcode-terminal"); async function startBot() { // Load (or create) the authentication state from the "auth" folder. // Square Cloud keeps this folder between restarts, so the session survives. const { state, saveCreds } = await useMultiFileAuthState("auth"); const sock = makeWASocket({ auth: state, }); // Persist updated credentials whenever Baileys rotates them sock.ev.on("creds.update", saveCreds); // Print the QR Code on first login and reconnect when the socket closes sock.ev.on("connection.update", ({ connection, qr, lastDisconnect }) => { if (qr) { // Print the QR Code in the logs, so you can scan it from the Square Cloud dashboard qrcode.generate(qr, { small: true }); console.log("Scan the QR Code above in WhatsApp: Linked devices > Link a device"); } if (connection === "close") { const loggedOut = lastDisconnect?.error?.output?.statusCode === 401; if (!loggedOut) startBot(); } }); // Reply to a basic command sock.ev.on("messages.upsert", async ({ messages }) => { const msg = messages[0]; if (!msg.message || msg.key.fromMe) return; if (msg.message.conversation === "!ping") { await sock.sendMessage(msg.key.remoteJid, { text: "pong - Bot working correctly!" }); } }); } startBot(); ``` Since Baileys doesn't need a browser, its configuration file on Square Cloud can use a lower `MEMORY` value than the whatsapp-web.js example above: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My WhatsApp Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true ``` ## Next steps Fix missing modules, memory errors and other startup failures. Run a WhatsApp API that manages many instances at once. What Square Cloud offers for bots that run 24/7. For more about whatsapp-web.js, see the [official whatsapp-web.js documentation](https://wwebjs.dev/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Build and Host an X (Twitter) Bot Source: https://docs.squarecloud.app/en/tutorials/bots/x Build and host an X (Twitter) bot on Square Cloud with Node.js and twitter-api-v2: set up the API keys, reply to new mentions and deploy it. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). ## Create the project An active X (Twitter) account is required for authentication and bot operation. If you don't have an account, sign up at the [official X website](https://x.com/).\ An X Developer account is also required to access the APIs. Request access through the [X Developer Portal](https://developer.x.com/en). The X API is paid per use: reading mentions and posting replies are billed to your X developer account, including the bot's periodic mention checks. Check the current rates on the [X API pricing page](https://docs.x.com/x-api/getting-started/pricing) before deploying. ### Bot application on X 1. Go to the [X Developer Portal](https://developer.x.com/en/portal/dashboard). 2. Log in with your X (Twitter) account. 3. If this is your first time, complete the developer access request process. 1. In the dashboard, click "Create Project". 2. Choose a name for your project (e.g. "Square Cloud Bot"). 3. Select the most appropriate use case (e.g. "Making a bot"). 4. Provide a detailed description of your bot. 5. Confirm project creation. 1. Within the created project, click "Create App". 2. Define a unique name for your application. 3. Confirm application creation. 4. Note down the generated **App ID** for future reference. 1. Navigate to the "Keys and tokens" section of your application. 2. In the "Consumer Keys" section, click "Regenerate" to generate: * **API Key** (Consumer Key) * **API Secret Key** (Consumer Secret) 3. **Important**: Copy and save these keys immediately, as you won't be able to view them again. 1. Go to the "App permissions" section. 2. Click "Edit" to modify permissions. 3. Select "Read and write" to allow your bot to post tweets. 4. If necessary, select "Read and write and Direct message" for DM functionality. 5. Save the changes. 1. Return to the "Keys and tokens" section. 2. In the "Access Token and Secret" section, click "Generate". 3. Confirm token generation. 4. Copy and save: * **Access Token** * **Access Token Secret** 5. **Warning**: These tokens cannot be viewed again after closing the page. 1. Confirm that you have all 4 required credentials: * API Key (Consumer Key) * API Secret Key (Consumer Secret) * Access Token * Access Token Secret 2. Store these credentials in a secure location 3. **Important**: Never share or expose these credentials publicly ## Develop the bot 1. **Node.js check**: Verify that Node.js is installed on your system. If not, download it from the [official Node.js website](https://nodejs.org/). 2. **Project initialization**: Create a new Node.js project by running: ```bash Terminal theme={"system"} npm init -y ``` 3. **Install dependencies**: Install the libraries required for the bot: ```bash Terminal theme={"system"} npm install twitter-api-v2 ``` 4. **Credentials**: the code reads the four credentials from environment variables, so they never go into your code. To test the bot on your computer, put them in a `.env` file and start the bot with `node --env-file=.env index.js`: ```env .env theme={"system"} API_KEY=your_api_key_here API_SECRET_KEY=your_api_secret_key_here ACCESS_TOKEN=your_access_token_here ACCESS_TOKEN_SECRET=your_access_token_secret_here ``` Square Cloud doesn't read this file when the bot runs: you set the same variables on the platform in [Set the credentials](#set-the-credentials). 5. **Create the main file**: Develop the `index.js` file with the bot's base structure: ```javascript index.js theme={"system"} // Import necessary modules const { TwitterApi } = require('twitter-api-v2'); // Configure Twitter client with authentication const client = new TwitterApi({ appKey: process.env.API_KEY, appSecret: process.env.API_SECRET_KEY, accessToken: process.env.ACCESS_TOKEN, accessSecret: process.env.ACCESS_TOKEN_SECRET, }); // Client with read and write permissions const rwClient = client.readWrite; // Stores the authenticated bot user id (set in verifyBot) let botUserId = null; // ID of the newest mention already seen: only newer mentions are fetched let sinceId; let firstCheck = true; // Function to check if the bot is working async function verifyBot() { try { // Get authenticated user information (X API v2) const me = await rwClient.v2.me(); botUserId = me.data.id; console.log(`Bot successfully initialized! User: @${me.data.username}`); return true; } catch (error) { console.error('Error verifying bot:', error); return false; } } // Function to post a tweet async function postTweet(text) { try { const tweet = await rwClient.v2.tweet(text); console.log(`Tweet posted successfully! ID: ${tweet.data.id}`); return tweet; } catch (error) { console.error('Error posting tweet:', error); throw error; } } // Function to respond to mentions async function respondToMentions() { if (!botUserId) return; try { // Fetch mentions newer than sinceId (X API v2) const mentions = await rwClient.v2.userMentionTimeline(botUserId, { max_results: 10, since_id: sinceId, }); // Remember the newest mention, so the next check skips the ones handled now sinceId = mentions.data?.meta?.newest_id ?? sinceId; // First check after start: only record the newest mention, so a restart doesn't reply to old ones again if (firstCheck) { firstCheck = false; return; } for (const tweet of mentions.data?.data ?? []) { if (tweet.text.includes('!ping')) { // Reply to the mention await rwClient.v2.reply( 'Pong! 🤖 X Bot working correctly!', tweet.id ); console.log(`Replied to mention (tweet ID: ${tweet.id})`); } } } catch (error) { console.error('Error processing mentions:', error); } } // Function to search and interact with specific tweets async function searchAndInteract(query) { if (!botUserId) return; try { // Search recent tweets (X API v2) const tweets = await rwClient.v2.search(query, { max_results: 10, }); for (const tweet of tweets.data?.data ?? []) { // Like the tweet await rwClient.v2.like(botUserId, tweet.id); console.log(`Liked tweet ID: ${tweet.id}`); // Wait a bit between actions to avoid rate limiting await new Promise(resolve => setTimeout(resolve, 2000)); } } catch (error) { console.error('Error searching and interacting:', error); } } // Main bot function async function runBot() { console.log('Starting X bot...'); // Check if the bot is configured correctly const botOk = await verifyBot(); if (!botOk) { console.error('Bot initialization failed'); return; } // Record the newest existing mention, so only new mentions get replies await respondToMentions(); // Main bot loop setInterval(async () => { try { // Check and respond to mentions every 5 minutes await respondToMentions(); // Example: Search and interact with tweets about a specific topic // await searchAndInteract('#SquareCloud'); } catch (error) { console.error('Error in main loop:', error); } }, 5 * 60 * 1000); // 5 minutes console.log('Bot running. Press Ctrl+C to stop.'); } // Signal handling for graceful shutdown process.on('SIGINT', () => { console.log('\nShutting down X bot...'); process.exit(0); }); process.on('SIGTERM', () => { console.log('\nShutting down X bot...'); process.exit(0); }); // Initialize the bot runBot(); ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project, next to `index.js`. It tells Square Cloud how to run your bot: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My X Bot MAIN=index.js MEMORY=512 VERSION=recommended AUTORESTART=true ``` * `MEMORY` is the bot's RAM in MB. Bots need at least 256 MB; 512 MB leaves room to grow. * `AUTORESTART=true` starts the bot again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: the bot calls the X API and doesn't serve web pages. See the [configuration file reference](/en/getting-started/config-file) for every field. ## Set the credentials **Security**: Never include your API credentials directly in code. Always use environment variables on Square Cloud. The bot needs four environment variables: * `API_KEY`: Your X API key * `API_SECRET_KEY`: Your X API secret key * `ACCESS_TOKEN`: Your access token * `ACCESS_TOKEN_SECRET`: Your access token secret Set them in one of these ways: * **Dashboard**: on the upload page, open **Advanced configuration** and add the four variables. For a bot that is already deployed, add them on the application's **Environment Variables** page and restart the bot. * **CLI**: right after you upload the bot (see [Deploy and verify](#deploy-and-verify)), load them from your local `.env` file with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) and restart the bot: ```bash theme={"system"} squarecloud app env set --from-file .env squarecloud app restart ``` The bot reads its environment variables when it starts, so restart it after every change. See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. ## What goes in the ZIP * `index.js` and your other source files. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your dependencies when the bot starts. Also leave out your `.env` file: if you upload with the CLI, add a line with `.env` to your [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) file so the CLI skips it. ## Deploy and verify Create the ZIP described above, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Test the bot After deployment, check the application logs in the Square Cloud dashboard for the `Bot successfully initialized!` message to confirm the bot authenticated correctly. Then, from another account, post a tweet that mentions the bot with `!ping` (for example, `@your_bot !ping`) and confirm it replies with `Pong! 🤖 X Bot working correctly!` on X within a few minutes. Mentions posted before the bot started are skipped. ## Common errors ### Request failed with code 401 The logs show `Error verifying bot:` followed by this error. One of the four credentials is wrong or missing. Copy them again from the "Keys and tokens" section, set the four variables and restart the bot. ### Request failed with code 403 when replying The bot authenticates but can't post. The access tokens were generated while the app had read-only permission. Set "Read and write" in the app permissions, regenerate the Access Token and Secret, update `ACCESS_TOKEN` and `ACCESS_TOKEN_SECRET` and restart the bot. ### Request failed with code 429 The bot reached an X API rate limit. Wait before the next request, and space out your calls as in [Rate limiting](#rate-limiting). ## Going further The snippets below extend `index.js`: add them to the file and call them where your bot needs them. ### Hashtag monitoring ```javascript theme={"system"} // Function to monitor specific hashtags async function monitorHashtags(hashtags) { for (const hashtag of hashtags) { try { const tweets = await rwClient.v2.search(`#${hashtag}`, { max_results: 10, }); // Process found tweets for (const tweet of tweets.data?.data ?? []) { console.log(`Tweet found with #${hashtag}: ${tweet.text}`); // Implement interaction logic } } catch (error) { console.error(`Error monitoring #${hashtag}:`, error); } } } ``` ### Scheduled posts ```javascript theme={"system"} // Function to schedule posts function schedulePost(text, delay) { setTimeout(async () => { try { await postTweet(text); console.log('Scheduled post published successfully!'); } catch (error) { console.error('Error publishing scheduled post:', error); } }, delay); } // Example: Schedule a post for 1 hour schedulePost('🤖 Scheduled post by the bot!', 60 * 60 * 1000); ``` ### Rate limiting X (Twitter) has strict rate limits. Implement controls to avoid exceeding these limits: ```javascript theme={"system"} // Rate limiting control const rateLimiter = { lastRequest: 0, minInterval: 1000, // 1 second between requests async wait() { const now = Date.now(); const timeSinceLastRequest = now - this.lastRequest; if (timeSinceLastRequest < this.minInterval) { const waitTime = this.minInterval - timeSinceLastRequest; await new Promise(resolve => setTimeout(resolve, waitTime)); } this.lastRequest = Date.now(); } }; ``` ### Error handling ```javascript theme={"system"} // Helper function to retry an operation on failure async function retryOperation(operation, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await operation(); } catch (error) { console.error(`Attempt ${i + 1} failed:`, error.message); if (i === maxRetries - 1) { throw error; } // Wait before retrying await new Promise(resolve => setTimeout(resolve, 2000 * (i + 1))); } } } ``` ## Next steps Fix missing modules, memory errors and other startup failures. Manage your bot's credentials and other secrets. How Square Cloud runs Node.js applications. For more about twitter-api-v2 and the X API, see the [official twitter-api-v2 documentation](https://github.com/PLhery/node-twitter-api-v2), the [official X API documentation](https://docs.x.com/overview), the [X API usage policies](https://developer.x.com/en/developer-terms/policy) and the [X API introduction](https://docs.x.com/x-api/getting-started/about-x-api). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Host a Lavalink Server for Your Music Bot Source: https://docs.squarecloud.app/en/tutorials/how-to-create-your-lavalink-server Lavalink server hosting for Discord music bots: a v4 application.yml with the YouTube plugin, port 80, a strong password and how your bot connects. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Java runtime](/en/articles/getting-started-with-java). ## Get the project Download `Lavalink.jar` from the [official releases page](https://github.com/lavalink-devs/Lavalink/releases). This guide uses Lavalink v4: pick the latest 4.x release (4.2.0 or newer), and make sure your bot uses a Lavalink client built for v4 that supports DAVE (see [Connect your bot](#connect-your-bot)). We already have everything ready for deploy in our [lavalink-web releases](https://github.com/squarecloud-education/lavalink-web/releases), with the YouTube plugin set up. Download the `project.zip` and upload it: during the Lavalink deploy, replace the placeholder value of `LAVALINK_SERVER_PASSWORD` in the environment variables with a long random password. ## Configure Lavalink Create an `application.yml` file next to `Lavalink.jar`. The minimal configuration below listens on the port in the `PORT` environment variable (Square Cloud sets it to `80`) and plays YouTube through the official [youtube-source plugin](https://github.com/lavalink-devs/youtube-source), since the YouTube source built into Lavalink is deprecated: ```yaml application.yml theme={"system"} server: port: ${PORT:80} # the PORT variable, or 80 when it isn't set address: 0.0.0.0 plugins: youtube: enabled: true lavalink: plugins: # Latest version: https://github.com/lavalink-devs/youtube-source/releases - dependency: "dev.lavalink.youtube:youtube-plugin:1.18.2" snapshot: false server: password: "change-me-to-a-long-random-password" sources: youtube: false # replaced by the youtube-source plugin ``` Lavalink downloads the plugin on its first start. For every other option (other sources, filters, buffers), see the [official example file](https://github.com/lavalink-devs/Lavalink/blob/master/LavalinkServer/application.yml.example). Keep `address: 0.0.0.0` and don't replace the port with a fixed value other than `80`: Square Cloud delivers your subdomain's traffic to port `80` of your application. ### Set a strong password Replace the `password` value with a strong, random password of at least 32 characters. To keep it out of your files, set it in the `LAVALINK_SERVER_PASSWORD` environment variable instead: Lavalink gives [environment variables](https://lavalink.dev/configuration/) precedence over `application.yml`. Add the variable in the upload form's **Advanced configuration** or on your application's **Environment Variables** page in the dashboard, or from the CLI: ```bash theme={"system"} squarecloud app env set LAVALINK_SERVER_PASSWORD=your_long_random_password squarecloud app restart ``` See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. ## Configure Square Cloud Create a `squarecloud.app` file next to `Lavalink.jar`. The `SUBDOMAIN` field publishes your server at `https://.squareweb.app`: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=Lavalink MAIN=Lavalink.jar MEMORY=1024 VERSION=recommended SUBDOMAIN=my-lavalink AUTORESTART=true ``` `MAIN=Lavalink.jar` makes Square Cloud start the server with `java -jar Lavalink.jar`, `MEMORY` is its RAM in MB, and `AUTORESTART=true` starts it again if it crashes (see [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/)). ## What goes in the ZIP * `Lavalink.jar` * `application.yml` * `squarecloud.app` Put the three files in the same folder and compress them into a `.zip` file to upload from the dashboard. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Connect your bot Lavalink listens on port `80` inside Square Cloud, but your bot connects through the public edge, which serves HTTPS on port `443`. Configure the node in your Lavalink client like this (field names vary between libraries): ```javascript theme={"system"} const node = { host: "my-lavalink.squareweb.app", // .squareweb.app port: 443, password: process.env.LAVALINK_PASSWORD, // the same password as the server secure: true, }; ``` Since March 2026, Discord only lets bots into voice channels with DAVE, its end-to-end encryption for voice. Lavalink supports it from version 4.2.0, and your bot's Lavalink client must support it too: otherwise the bot connects to Lavalink but can't join a voice channel. ## Common errors ### The bot can't connect to Lavalink Connecting with port `80` or `secure: false` fails: use port `443` and `secure: true`, as shown in [Connect your bot](#connect-your-bot). If the connection closes with code 1006, see [Lavalink connection closed with code 1006](/en/platform/troubleshooting/discord-bot-errors#lavalink-connection-closed-with-code-1006). ## Next steps Host the music bot that connects to your Lavalink server. Fix invalid tokens, missing intents and Lavalink connection errors. How Square Cloud runs Java applications. For more about Lavalink, see the [official Lavalink documentation](https://lavalink.dev/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy Evolution API (WhatsApp API) Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-evolution-api Evolution API on Square Cloud: host this WhatsApp API with a managed PostgreSQL database, run its migrations, set port 80, a global API key and Redis cache. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. Evolution API is an open-source API for WhatsApp. It manages several WhatsApp instances in one place, through its web manager or its REST API, and connects them to tools like n8n, Chatwoot and Typebot. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). ## Get the project Download the project from [our evolutionapi-web releases](https://github.com/squarecloud-education/evolutionapi-web/releases), which already has the files needed to deploy on Square Cloud, or from the [official repository](https://github.com/EvolutionAPI/evolution-api). The official repository lists `typescript` in `devDependencies`. Square Cloud installs dependencies in production mode, without `devDependencies`, so the `npm run build` step fails. Our release already moves it to `dependencies`; with the official repository, move it yourself. ## Configure Evolution API Evolution API reads a `.env` file at the root of the project when it starts, so this file goes in your ZIP. Start from the `.env` in our release (or from `.env.example` in the official repository) and edit the variables below. Variables set in the dashboard's **Environment Variables** take precedence over the `.env` file, which makes the dashboard the better place for secrets such as `AUTHENTICATION_API_KEY` and `DATABASE_CONNECTION_URI`. See [Environment variables](/en/platform/environment-variables). ### Database Evolution API needs a PostgreSQL database. You can host one on Square Cloud with the Standard plan or higher: see [how to create and connect a managed database](/en/tutorials/how-to-deploy-your-database). After creating it, set its URL in the `.env` as `DATABASE_CONNECTION_URI`, together with the client certificate for the PostgreSQL connection. Here's an example of the configuration needed: ```systemd .env theme={"system"} DATABASE_PROVIDER=postgresql DATABASE_CONNECTION_URI='postgresql://squarecloud:password@host:port/database?sslmode=require&sslidentity=path/to/client-identity.p12&sslpassword=p12password' DATABASE_CONNECTION_CLIENT_NAME='evolution_exchange' DATABASE_SAVE_DATA_INSTANCE=true DATABASE_SAVE_DATA_NEW_MESSAGE=true DATABASE_SAVE_MESSAGE_UPDATE=true DATABASE_SAVE_DATA_CONTACTS=true DATABASE_SAVE_DATA_CHATS=true DATABASE_SAVE_DATA_LABELS=true DATABASE_SAVE_DATA_HISTORIC=true DATABASE_SAVE_IS_ON_WHATSAPP=true DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7 DATABASE_DELETE_MESSAGE=true ``` Evolution API connects through Prisma, which expects the client certificate as a `.p12` file. Download the certificate files (`.crt` and `.key`) from the database's page in the dashboard, convert them, and put the `.p12` in your project: ```bash theme={"system"} openssl pkcs12 -export -out client-identity.p12 -inkey .key -in .crt ``` The export password you choose is the `sslpassword` of the URL, and `sslidentity` is the path to the `.p12` file. Keep the `.p12` in your ZIP, since the application reads it from disk. ### Apply the migrations With the environment variable and certificate set, apply the migrations to your database. From the project folder on your computer, install the dependencies with `npm install` (it needs the `runWithProvider.js` file) and run the following command: ```bash theme={"system"} npm run db:deploy:win ``` ```bash theme={"system"} npm run db:deploy ``` Updating from an earlier version? Run the same command again before uploading the new files, since new versions can bring new migrations. ### Server As shown in the `.env.example` file of the repository, set the server variables: `SERVER_TYPE`, `SERVER_PORT`, `SERVER_URL` and the language. ```systemd .env theme={"system"} SERVER_NAME=evolution SERVER_TYPE=http SERVER_PORT=80 # Your application's URL: https://.squareweb.app, or your custom domain SERVER_URL="https://my-evolution-api.squareweb.app" LANGUAGE=en # Other variables below... ``` Evolution API reads its port from `SERVER_PORT` (not from `PORT`) and falls back to `8080` without it, so keep `SERVER_PORT=80`. ### Global API key It is important to configure a secure global API key to avoid unauthorized access. Replace it with a long random value of your own: the key in example files is public. ```systemd .env theme={"system"} # Other variables... AUTHENTICATION_API_KEY=MySuperSecureAPIKEY ``` ### Redis cache (optional) You can configure a cache system in Evolution API. To do so, you will need a Redis database, which you can also host on Square Cloud.\ To configure it, you will also need to download the certificate and set the URL to connect. Note the `rediss://` scheme: Square Cloud databases only accept TLS connections. ```systemd .env theme={"system"} CACHE_REDIS_ENABLED=true CACHE_REDIS_URI="rediss://default:MySecurePassword@square-cloud-db-ID.squareweb.app:7170" CACHE_REDIS_TTL=604800 # Prefix serves to differentiate data from one installation to another that are using the same redis CACHE_REDIS_PREFIX_KEY=evolution # Enabling this variable will save the connection information in Redis and not in the database. CACHE_REDIS_SAVE_INSTANCES=false ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of the project. The `START` command generates the Prisma client, builds the project and starts it; installing and building needs about 3072 MB of RAM: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=Evolution API RUNTIME=nodejs START=npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod MEMORY=3072 VERSION=recommended SUBDOMAIN=my-evolution-api AUTORESTART=true ``` `SUBDOMAIN` must match the address in `SERVER_URL`. When uploading from the dashboard, select "Web Publication", set the same subdomain and paste the `START` command as the startup command. ## What goes in the ZIP * The whole project folder: `package.json`, `runWithProvider.js`, `src/`, `prisma/` and the other files of the release or the repository. * `.env`, with the variables above. * The `.p12` client certificate. * `squarecloud.app`. Leave out `node_modules/`, which `npm install` created for the migrations: Square Cloud installs the dependencies on the server. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Lower the RAM after the first run After the first run, you can reduce the RAM to 1536MB or 2048MB and set the startup command to only: ```bash theme={"system"} npm run start:prod ``` ## First access Open `https://my-evolution-api.squareweb.app/manager` to reach the web manager. Log in with your `SERVER_URL` as the server URL and your `AUTHENTICATION_API_KEY` as the global API key, then create your first WhatsApp instance. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### Evolution API can't connect to the database Check that `sslidentity` points to the `.p12` file inside your ZIP and that `sslpassword` is the export password you chose. For other SSL/TLS errors, see [database connection errors](/en/platform/troubleshooting/database-connection-errors). ## Next steps Create the PostgreSQL database Evolution API needs. Fix SSL/TLS and connection errors. Build a single WhatsApp bot with whatsapp-web.js or Baileys. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Self-Host n8n on Square Cloud Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-n8n n8n self-hosting on Square Cloud: a pinned package.json, port 80 and webhook URL variables, the config file and creating your owner account after deploy. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. n8n runs with 3 GB of RAM (`MEMORY=3072` below), so it needs a plan with at least 4 GB, such as Standard: smaller plans don't have that much RAM. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). ## Get the project n8n runs on Node.js, so the project only needs a `package.json` that lists n8n in its dependencies and has a script to start it: ```json package.json theme={"system"} { "name": "squarecloud-n8n", "version": "1.0.0", "type": "module", "scripts": { "start": "n8n" }, "author": "Square Cloud Education ", "license": "ISC", "dependencies": { "n8n": "2.41.6" } } ``` The n8n version is pinned on purpose: `latest` can jump to a new major version with breaking changes on any reinstall. n8n 2.x needs Node.js 24 or newer, which `VERSION=recommended` provides. To update later, check the newest version with `npm view n8n version`, read the [n8n release notes](https://docs.n8n.io/changelog/release-notes), change the version in `package.json` and upload your project again. We already have everything ready for deploy in our [n8n-web releases](https://github.com/squarecloud-education/n8n-web/releases). You just need to download the `project.zip` and upload it. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=App name RUNTIME=nodejs START=npm run start MEMORY=3072 VERSION=recommended SUBDOMAIN=my-n8n-subdomain ``` `START=npm run start` runs the `start` script of your `package.json`. When uploading from the dashboard, set the runtime manually to Node.js and use `npm run start` as the startup command. The `MEMORY` value follows the platform's sizing rules: see [why RAM minimums exist](/en/platform/limitations-and-restrictions#why-do-ram-minimums-exist) if you want to tune it. ### Environment variables Set the variables below. You can put them in a `.env` file at the root of the project (n8n loads it when it starts) or set them as [environment variables](/en/platform/environment-variables) of the application, in the upload form's **Advanced configuration** or in the dashboard. Replace `my-n8n-subdomain` with your `SUBDOMAIN`. ```systemd .env theme={"system"} N8N_PORT=80 N8N_LISTEN_ADDRESS=0.0.0.0 N8N_HOST=my-n8n-subdomain.squareweb.app N8N_PROTOCOL=https N8N_WEBHOOK_URL=https://my-n8n-subdomain.squareweb.app/ ``` * `N8N_PORT` and `N8N_LISTEN_ADDRESS` make n8n listen on port `80` on all interfaces, where Square Cloud delivers your subdomain's traffic. n8n doesn't read the `PORT` variable Square Cloud sets, so `N8N_PORT` is required. * `N8N_HOST`, `N8N_PROTOCOL` and `N8N_WEBHOOK_URL` tell n8n its public address. Older guides call the last one `WEBHOOK_URL`, which n8n 2.x deprecates. See the [n8n endpoint variables](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/endpoints) for more options. Variables set in the dashboard take precedence over the `.env` file. ## What goes in the ZIP * `package.json` * `squarecloud.app` * `.env`, if you keep the variables above in it Leave out `node_modules/`: Square Cloud installs n8n on the server. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## First access Right after the deploy, open `https://my-n8n-subdomain.squareweb.app` and create the owner account. Whoever opens the page first becomes the owner of the instance, so do it before sharing the URL with anyone. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### n8n doesn't respond on your subdomain n8n ignores the `PORT` and `HOST` variables. Check that `N8N_PORT=80` and `N8N_LISTEN_ADDRESS=0.0.0.0` are set, then restart the application. ### Webhook URLs point to the internal port Without `N8N_WEBHOOK_URL`, the webhook URLs n8n shows in your workflows point to the internal port and external services can't reach them. Set `N8N_WEBHOOK_URL` to your public address, for example `https://my-n8n-subdomain.squareweb.app/`, then restart the application. ## Next steps Manage n8n's settings and secrets from the dashboard or the CLI. Serve n8n from your own domain, then update `N8N_HOST` and `N8N_WEBHOOK_URL`. Monitor n8n and your other services. For more about n8n, see the [official n8n documentation](https://docs.n8n.io/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Host pgAdmin 4 for Your PostgreSQL Database Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-pgadmin pgAdmin 4 hosting on Square Cloud: run it with Gunicorn, set config_local.py and the setup email and password, then manage PostgreSQL from any browser. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Python runtime](/en/articles/getting-started-with-python). ## Get the project pgAdmin runs on Python, so the project needs a `requirements.txt` or a `pyproject.toml` (see [how to create a requirements.txt](/en/articles/how-to-create-your-requirements)). It lists `pgadmin4` and a web server to serve it. This guide uses `gunicorn`: ```txt requirements.txt theme={"system"} pgadmin4==9.18 gunicorn==26.2.0 ``` The versions are pinned, as in our ready-made release, so a reinstall never jumps to a new version with breaking changes. To update later, change them here and upload your project again. Next, create a `config_local.py` file. pgAdmin reads it on startup: these settings run it as a web server and keep its data, log and SQLite database in a `.pgadmin` folder inside your application. ```py config_local.py theme={"system"} SERVER_MODE = True MAX_LOGIN_ATTEMPTS = 3 """ CRITICAL 50 ERROR 40 WARNING 30 SQL 25 INFO 20 DEBUG 10 NOTSET 0 """ CONSOLE_LOG_LEVEL = 10 DATA_DIR = "/application/.pgadmin/" LOG_FILE = "/application/.pgadmin/logfile" SQLITE_PATH = '/application/.pgadmin/pgadmin4.db' ``` We already have everything ready for deploy in our [pgadmin4-web releases](https://github.com/squarecloud-education/pgadmin4-web/releases). You just need to download the `project.zip`, fill in the two variables below and upload it. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=App name RUNTIME=python MEMORY=1024 START=python -m gunicorn --bind 0.0.0.0:80 --workers=1 --threads=4 pgadmin4.pgAdmin4:app VERSION=recommended SUBDOMAIN=my-pgadmin-subdomain ``` Gunicorn listens on port `80` on all interfaces (`0.0.0.0`), where Square Cloud delivers your subdomain's traffic. Keep a single worker (`--workers=1`) and add threads instead: with more workers, pgAdmin fails with CSRF errors. When uploading from the dashboard, set the runtime manually to Python and use the same `START` command as the startup command. ### Environment variables Set 2 environment variables, `PGADMIN_SETUP_EMAIL` and `PGADMIN_SETUP_PASSWORD`. pgAdmin uses them to create the first user when it starts for the first time. ```systemd .env theme={"system"} PGADMIN_SETUP_EMAIL=accessemail@example.com PGADMIN_SETUP_PASSWORD=yourSecurePassword ``` Set them in the upload form's **Advanced configuration**, on the application's **Environment Variables** page (then restart it), or with `squarecloud app env set`. pgAdmin doesn't read a `.env` file at the root of your project, so these values only work as environment variables. See [Environment variables](/en/platform/environment-variables). ## What goes in the ZIP * `requirements.txt` or `pyproject.toml` * `config_local.py` * `squarecloud.app` ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## First access Open `https://my-pgadmin-subdomain.squareweb.app` and log in with the email and password you set. Then add your PostgreSQL server to manage it from anywhere. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### CSRF errors after logging in pgAdmin runs with more than one Gunicorn worker. Set `--workers=1` in the `START` command, add threads with `--threads` if you need more capacity, then restart the application. ## Next steps Create a PostgreSQL database to manage with pgAdmin. Fix SSL/TLS and connection errors. Tune the web server that runs pgAdmin. For more about pgAdmin, see the [official pgAdmin documentation](https://www.pgadmin.org/docs/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Self-Host Uptime Kuma for Uptime Monitoring Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-uptime-kuma Uptime Kuma self-hosted on Square Cloud: download the ready project.zip, set your subdomain in the config file and deploy your uptime monitor in minutes. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). ## Get the project Choose a version in our [uptimekuma-web releases](https://github.com/squarecloud-education/uptimekuma-web/releases) and download its `project.zip`. ## Configure Square Cloud The project already includes its configuration file, `squarecloud.config`. If you want a custom subdomain instead of a random hash, set the desired subdomain in it: ```systemd squarecloud.config theme={"system"} DISPLAY_NAME=Uptime Kuma MEMORY=1024 VERSION=recommended AUTORESTART=true MAIN=server/server.js SUBDOMAIN=my-uptime-kuma ``` You can also set this through the upload menu. There is no port to configure: Uptime Kuma reads the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`. ## What goes in the ZIP Upload the `project.zip` with all its files. If you extract it to edit `squarecloud.config`, compress the contents again so that `squarecloud.config` stays at the root of the ZIP, next to `package.json`. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## First access Right after the deploy, open `https://my-uptime-kuma.squareweb.app` and create the admin account. Whoever opens the page first creates it, so do it before sharing the URL with anyone. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Serve your status pages from your own domain. Automate what happens when a monitor goes down. Fix missing modules, memory errors and other startup failures. For more about Uptime Kuma, see the [official Uptime Kuma wiki](https://github.com/louislam/uptime-kuma/wiki). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Create and Connect a Managed Database Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-your-database Managed database on Square Cloud: create a PostgreSQL, MongoDB, MySQL or Redis instance, get its connection string and TLS certificate, and connect from code. ## Introduction This tutorial takes you from zero to a live, connected database in a few minutes: create the instance from the dashboard, grab its connection string, and connect to it from your own code. ### Prerequisites * **Square Cloud Account**: Create your account through the [signup page](https://squarecloud.app/en/signup). * **Active Standard plan or higher**: Managed databases require an **active Standard plan or higher**. Check the [available plans](/en/platform/plans) and choose the one that fits your workload. ## Step 1: Choose an engine Square Cloud offers four managed database engines, already configured to connect and start using: | Engine | Version | | :-: | :-: | | PostgreSQL | 17 | | MongoDB | 8 | | MySQL | 9 | | Redis | 8 | This tutorial uses **PostgreSQL**, but the same dashboard flow applies to every engine above. ## Step 2: Create the database Go to the [Databases](https://squarecloud.app/en/dashboard/databases) page and click on the "Create Database" button. Select **PostgreSQL** (or the engine you chose in Step 1) and fill in the required information, such as the database name and RAM. Click on the "Create" button and wait for the database to be created. ## Step 3: Get the connection string Once your database is ready, open it from the [Databases](https://squarecloud.app/en/dashboard/databases) page. The connection details (host, port, username, password and connection URL) are shown in the database dashboard, alongside the TLS certificate you'll need to connect. Square Cloud databases only accept SSL/TLS connections. See [how do I connect to my database](/en/services/databases#how-do-i-connect-to-my-database) for how the certificate is used by different clients. ## Step 4: Connect from your code With the connection string in hand, connect using your language's PostgreSQL client. Install the [`pg`](https://www.npmjs.com/package/pg) package and enable ES modules, which the example below uses (`import` and top-level `await`): ```bash theme={"system"} npm install pg npm pkg set type=module ``` Connect and verify with a simple query: ```javascript index.js theme={"system"} import fs from "node:fs"; import { Client } from "pg"; const cert = fs.readFileSync("certificate.pem").toString(); const client = new Client({ connectionString: process.env.DATABASE_URL, // postgresql://user:password@host:port/dbname ssl: { ca: cert, cert: cert, key: cert }, }); await client.connect(); const result = await client.query("SELECT 1"); console.log("Connected! Result:", result.rows[0]); await client.end(); ``` Install [`psycopg2`](https://pypi.org/project/psycopg2-binary/): ```bash theme={"system"} pip install psycopg2-binary ``` Connect and verify with a simple query: ```python main.py theme={"system"} import os import psycopg2 conn = psycopg2.connect( os.environ["DATABASE_URL"], # postgresql://user:password@host:port/dbname sslmode="verify-ca", sslrootcert="certificate.pem", sslcert="certificate.pem", sslkey="certificate.pem", ) cur = conn.cursor() cur.execute("SELECT 1") print("Connected! Result:", cur.fetchone()) cur.close() conn.close() ``` If the query returns a result instead of raising a connection error, your application is talking to the database successfully. Never hardcode the connection string in your source code. Set it as an environment variable (`DATABASE_URL`) in your application's Environment Variables on the dashboard, or with the CLI command `squarecloud app env set "DATABASE_URL=" --app ` (see [environment variables in the CLI](/en/cli-reference/environment-variables#squarecloud-app-env-set)), so credentials never end up in your repository. Restart the application afterwards: it reads environment variables when it starts. See [Environment variables](/en/platform/environment-variables). Keep `certificate.pem` in your application's ZIP, since the code reads it from disk, but out of any public repository. ## Next steps You now have a managed database running and reachable from your code. From here: Host the application that connects to this database on Square Cloud. Fix SSL/TLS, timeout and access errors. Create and restore database snapshots from the CLI. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Run Selenium with Headless Chromium Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-your-selenium-application Selenium automation on Square Cloud: run a Python script with headless Chromium and ChromeDriver, the flags containers need, requirements.txt and deploy. ## Professional Selenium script development To implement efficient web automation on Square Cloud, it's essential to establish a proper development environment and follow configuration best practices. ### Essential technical prerequisites * **Python and pip**: Make sure you have **Python** and **pip** installed on your system. If you don't have them, download from the [official Python website](https://www.python.org/) and the [official Pip website](https://pypi.org/). * **Square Cloud Account**: Create your account through the [signup page](https://squarecloud.app/en/signup), using your email address for registration. * **Active plan**: An active plan is necessary to ensure adequate resources for running Selenium applications. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. ### Selenium environment configuration With Python and pip installed, proceed with creating the Selenium script. First, install the Selenium library: ```bash Terminal theme={"system"} pip install selenium ``` Next, create a Python file (for example, `main.py`) and add the following code to implement a basic Selenium script: ```python main.py theme={"system"} import time from selenium import webdriver from selenium.webdriver.chrome.options import Options from selenium.webdriver.chrome.service import Service # Configuration options for Chromium options = Options() options.add_argument("--headless") # Runs in background without graphical interface options.add_argument("--no-sandbox") # Required in containers, where the Chromium sandbox can't start options.add_argument("--disable-dev-shm-usage") # Overcomes shared memory limitations on large pages # Driver initialization service = Service('/usr/bin/chromedriver') # Default ChromeDriver path on Square Cloud driver = webdriver.Chrome(service=service, options=options) # Browser window dimensions configuration driver.set_window_size(1920, 1080) # Adjust as needed for your application # Navigate to web page driver.get('https://www.google.com') # Loop for screenshot capture every minute while True: driver.save_screenshot('page.png') print("Page screenshot saved successfully.") time.sleep(60) # 60-second pause between captures ``` ## Dependency management with requirements.txt The `requirements.txt` file is an essential component that lists all external libraries needed for your project. It's crucial to include all dependencies used, excluding native Python libraries like `random` and `datetime`. This file should be included when submitting your application to Square Cloud. ```txt requirements.txt theme={"system"} selenium ``` ## Chromium path configuration In the implementation presented above, it's not necessary to explicitly define the Chromium path, as the Selenium WebDriver can automatically locate the browser when installed in a standard system location. The ChromeDriver, specified with `Service('/usr/bin/chromedriver')`, has knowledge about where to locate the Chromium/Chrome executable. ### Square Cloud architecture On Square Cloud, Chromium is installed at `/usr/bin/chromium`, which is the standard system location. Therefore, the Selenium WebDriver can locate it automatically through the specified ChromeDriver. Thus, there's no need to explicitly specify the Chromium path in the code, unless there are specific reasons to do so, such as custom installations or different environment configurations. ## Square Cloud configuration file Create a `squarecloud.app` file at the root of your project, next to `main.py`. It tells Square Cloud how to run your script: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=Selenium Automation MAIN=main.py MEMORY=1024 VERSION=recommended AUTORESTART=true ``` * `MEMORY` is the RAM in MB. Chromium is memory hungry, so give it at least 1024 MB and raise it if the application stops with `LACK_OF_RAM`. * `AUTORESTART=true` starts the script again if it crashes. See [how auto restart works](https://help.squarecloud.app/en-us/article/how-to-use-auto-restart-on-square-cloud-nmhvh0/). * There is no `SUBDOMAIN`: the script doesn't serve web pages. Your ZIP holds `main.py`, `requirements.txt` and `squarecloud.app`. The squarecloud.app file is an essential configuration file that will be used to configure your application on Square Cloud. It defines name, description, version, main file, among other fundamental configurations. ## Project upload to Square Cloud After preparing all project files, proceed with uploading to Square Cloud and host your application professionally. ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Additional resources and documentation For more detailed information about Selenium and its advanced tools, visit the [official Selenium documentation](https://www.selenium.dev/documentation/webdriver/getting_started/). There you'll find detailed technical guides, specialized tutorials, and complete API documentation to maximize the use of Selenium functionalities. ## Next steps Fix LACK\_OF\_RAM, missing modules and other startup failures. How Square Cloud runs Python applications. Keep logins and API keys used by your automation out of your code. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # How to Host a Website or API Source: https://docs.squarecloud.app/en/tutorials/how-to-deploy-your-website Host a website or API on Square Cloud: set up the squarecloud.app file with SUBDOMAIN and port 80, see static and Next.js examples and framework guides. ## Introduction To host websites and APIs on Square Cloud, it's essential to follow proper configuration procedures and meet the necessary technical prerequisites. This comprehensive guide will present the entire professional implementation process. ### Technical prerequisites * **Square Cloud Account**: Create your account through the [signup page](https://squarecloud.app/en/signup), using your email address for registration. * **Active plan**: It's necessary to have an active plan to ensure adequate resources and optimized performance. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. ## Square Cloud configuration file The squarecloud.app file is an essential configuration file that will be used to configure your application on Square Cloud. It defines name, description, version, main file, among other fundamental configurations. ### Essential parameters for websites Your server must listen on **port 80** and on **host `0.0.0.0`** (all network interfaces): Square Cloud delivers your subdomain's traffic there. It sets the `PORT` (`80`) and `HOST` (`0.0.0.0`) environment variables for you, so read the port from `PORT` and keep a fallback of `80`: ```javascript Node.js theme={"system"} const port = Number(process.env.PORT) || 80; app.listen(port, "0.0.0.0"); ``` ```python Python theme={"system"} import os port = int(os.environ.get("PORT", 80)) app.run(host="0.0.0.0", port=port) ``` Many frameworks, such as Next.js and Nuxt, already read `PORT` on their own. Static websites don't need a server or a `START` parameter at all. **Main parameters of the squarecloud.app configuration file:** * `SUBDOMAIN`: For website hosting, define this parameter with your desired subdomain. Set it on the first upload: an application uploaded without a subdomain can't get one later. * `START`: Custom startup command (when necessary). * `MEMORY`: RAM allocated to your application, in megabytes. Websites and APIs need at least 512. Curious why there is a minimum value? See [why RAM minimums exist](/en/platform/limitations-and-restrictions#why-do-ram-minimums-exist). The website URL will be: `my-subdomain-parameter`.squareweb.app ### Configuration examples **Example 1: Static website without custom startup command** ```systemd theme={"system"} MAIN=index.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My simple static website! SUBDOMAIN=mysite-simple-website ``` **Example 2: Next.js website with a custom startup command** ```systemd theme={"system"} RUNTIME=nodejs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My simple Next.js website! SUBDOMAIN=mysite-nextjs-website START=npm run start ``` Run `npm run build` on your machine first and include the `.next` folder in the zip: Square Cloud doesn't install `devDependencies`, so the build can't run on the server. With a `START` command, `RUNTIME=nodejs` picks the Node.js runtime and no `MAIN` file is needed. For framework-specific details, see the [Next.js guide](/en/tutorials/website/nextjs). ### Custom domain To serve your website from your own domain (e.g., `mysite.com`) instead of `mysite.squareweb.app`, you need the Standard plan or higher. Follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/) in the help center. ## Support for multiple technologies Square Cloud offers comprehensive support for various web development technologies, providing flexibility in choosing the most suitable tech stack for your project. Learn how to host your React website on Square Cloud. Learn how to host your Next.js website on Square Cloud. Learn how to host your NestJs application on Square Cloud. Learn how to host your Vite website on Square Cloud. Learn how to host your Vue website on Square Cloud. Learn how to host your Express API on Square Cloud. Learn how to host your Flask application on Square Cloud. Learn how to host your Django application on Square Cloud. Learn how to host your FastAPI application on Square Cloud. Learn how to host your Lavalink server and stream high-quality music to your Discord bot. ## Next steps Fix port conflicts, missing modules and other startup failures. Keep API keys and connection strings out of your code. Create a database for your website or API. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Fix python-telegram-bot NetworkError with aiohttp Source: https://docs.squarecloud.app/en/tutorials/python/how-to-change-ptb-connection python-telegram-bot NetworkError fix: swap the default httpx backend for aiohttp with ptbcontrib's AiohttpRequest, with examples for Bot and ApplicationBuilder. This guide changes the HTTP backend of `python-telegram-bot` (PTB) from `httpx`, the default, to `aiohttp`. Both are libraries that make HTTP requests. The default `httpx` backend can raise frequent `NetworkError` exceptions, such as `ReadError`, in bots that poll Telegram for long periods, and switching to `aiohttp` is a common way to make them stop. If your bot runs without these errors, you don't need this change. ## Install ptbcontrib You need Python and the `python-telegram-bot` library: ```bash theme={"system"} pip install python-telegram-bot ``` Then install `ptbcontrib`, which offers a class to handle the requests made to Telegram. Its `aiohttp_request` extra also installs `aiohttp`: ```bash theme={"system"} pip install "ptbcontrib[aiohttp_request] @ git+https://github.com/python-telegram-bot/ptbcontrib.git@main" ``` Add the same dependencies to your `requirements.txt`, so Square Cloud installs them during the deploy: ```txt requirements.txt theme={"system"} python-telegram-bot ptbcontrib[aiohttp_request] @ git+https://github.com/python-telegram-bot/ptbcontrib.git@main ``` ## Switch from httpx to aiohttp Import `AiohttpRequest` in the file where you create your bot client: ```python theme={"system"} from ptbcontrib.aiohttp_request import AiohttpRequest ``` This class handles all requests to Telegram instead of the default `httpx`. Pass it to the PTB client like in the examples below. Both read the bot token from the `TELEGRAM_BOT_TOKEN` environment variable, so it never goes into your code: ```python Bot theme={"system"} import asyncio import os import telegram from ptbcontrib.aiohttp_request import AiohttpRequest async def main(): bot = telegram.Bot( os.environ["TELEGRAM_BOT_TOKEN"], request=AiohttpRequest(), get_updates_request=AiohttpRequest(), ) async with bot: print(await bot.get_me()) if __name__ == '__main__': asyncio.run(main()) ``` ```python ApplicationBuilder theme={"system"} import logging import os from telegram import Update from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler from ptbcontrib.aiohttp_request import AiohttpRequest logging.basicConfig( format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO ) async def start(update: Update, context: ContextTypes.DEFAULT_TYPE): await context.bot.send_message(chat_id=update.effective_chat.id, text="I'm a bot, please talk to me!") if __name__ == '__main__': application = ( ApplicationBuilder() .token(os.environ["TELEGRAM_BOT_TOKEN"]) .request(AiohttpRequest(connection_pool_size=256)) .get_updates_request(AiohttpRequest()) .build() ) start_handler = CommandHandler('start', start) application.add_handler(start_handler) application.run_polling() ``` ## Run it on Square Cloud Create a `squarecloud.app` file at the root of your project. For a bot whose main file is `main.py`: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My Telegram Bot MAIN=main.py MEMORY=512 VERSION=recommended AUTORESTART=true ``` Your ZIP holds `main.py`, `requirements.txt` and `squarecloud.app`, without the token. Then set the token as the `TELEGRAM_BOT_TOKEN` environment variable: in the upload form's **Advanced configuration**, on the application's **Environment Variables** page (then restart the bot), or from the CLI: ```bash theme={"system"} squarecloud app env set TELEGRAM_BOT_TOKEN=your_token_here squarecloud app restart ``` See [Environment variables](/en/platform/environment-variables) for the details, and the [Telegram bot tutorial](/en/tutorials/bots/telegram) for the full deploy walkthrough. ## Next steps Create, deploy and test a Telegram bot from scratch. Manage your bot's token and other secrets. Fix ModuleNotFoundError and other startup failures. ## Did you like this article? * We created this content with great care to offer the best help possible. If this article helped you in any way, support our work! Developers have already rated Square Cloud **4.9/5 across 402 reviews** on Google and Trustpilot: leave yours too! It helps us understand what matters most to you. Leave your review in Google Reviews. Leave your review in Trustpilot. # Run Flask or Django in Production with Gunicorn Source: https://docs.squarecloud.app/en/tutorials/python/how-to-use-gunicorn Gunicorn for Flask and Django on Square Cloud: bind to 0.0.0.0:80, size workers to your RAM with gunicorn.conf.py and set the START command in your config. Gunicorn is a Python WSGI HTTP server that runs Flask, Django and other WSGI applications in production. This guide shows how to start your application with Gunicorn, tune it for the RAM of your plan and run it on Square Cloud. ## Install Gunicorn Install Gunicorn on your machine: ```bash theme={"system"} pip install gunicorn ``` Add `gunicorn` to your `requirements.txt` too, so Square Cloud installs it with your other dependencies: ```txt requirements.txt theme={"system"} flask gunicorn ``` ## Basic usage To run an application with Gunicorn, you need a WSGI application, such as one built with Flask or Django, and you need to know the module name and the variable name that holds the WSGI application object. For example, if you have a Flask application in a file named `app.py` and the Flask instance is named `app`, you can run it with Gunicorn using the following command: ```bash theme={"system"} python -m gunicorn --bind 0.0.0.0:80 app:app ``` In this command: * `python -m gunicorn` runs Gunicorn as a Python module. * `--bind 0.0.0.0:80` tells Gunicorn to listen on all network interfaces on port 80. * `app:app` specifies the module name (`app`) and the variable name (`app`) that contains the WSGI application object. For Django, point Gunicorn to the `wsgi.py` module Django creates inside your project package (replace `myproject` with your project's name): ```bash theme={"system"} python -m gunicorn --bind 0.0.0.0:80 myproject.wsgi:application ``` ## Additional options Gunicorn provides several options to customize its behavior. These are the most common ones; the [official Gunicorn settings reference](https://gunicorn.org/reference/settings/) lists them all. ### Workers * `--workers ` This option sets the number of worker processes for handling requests. Each worker is a separate process with its own copy of your application in memory, so on Square Cloud the limit is usually RAM, not CPU. Start with 2 workers and add more only after raising `MEMORY`. If your application stops with `LACK_OF_RAM`, lower the number of workers. Don't size workers with `multiprocessing.cpu_count()` or the `(2 x $num_cores) + 1` formula: inside a container, the core count can be the host machine's, which starts dozens of workers and exhausts your RAM. ### Name * `--name ` * `-n ` This option sets the process name for Gunicorn. ### Worker class * `--worker-class ` * `-k ` This option sets the type of worker to use. The default is `sync`, but you can also use `gevent`, `eventlet`, `tornado` or other worker type. ## Config file You can also set Gunicorn options in a Python configuration file. Gunicorn automatically loads a file named `gunicorn.conf.py` from the directory where it runs, which is your project root on Square Cloud. For any other file name, pass it with `-c `. ```python gunicorn.conf.py theme={"system"} import os # Square Cloud sets PORT=80; the fallback keeps the file working anywhere bind = f"0.0.0.0:{os.getenv('PORT', '80')}" # Each worker uses its own share of RAM: raise WEB_CONCURRENCY only together with MEMORY workers = int(os.getenv("WEB_CONCURRENCY", 2)) ``` With this file in your project, the start command no longer needs the `--bind` option. ## Run it on Square Cloud Create a `squarecloud.app` file at the root of your project and put the Gunicorn command in its `START` field, so Square Cloud starts your application with Gunicorn instead of the default `python app.py`: ```systemd Command line theme={"system"} DISPLAY_NAME=My Flask App MAIN=app.py MEMORY=512 VERSION=recommended SUBDOMAIN=my-flask-app START=python -m gunicorn --bind 0.0.0.0:80 app:app ``` ```systemd With gunicorn.conf.py theme={"system"} DISPLAY_NAME=My Flask App MAIN=app.py MEMORY=512 VERSION=recommended SUBDOMAIN=my-flask-app START=python -m gunicorn app:app ``` Gunicorn must bind to `0.0.0.0:80`: Square Cloud delivers your subdomain's traffic to port `80` of your application. Square Cloud also sets the `PORT` environment variable to `80`, and Gunicorn reads it: without a `--bind` option, it listens on `0.0.0.0:$PORT` when `PORT` is set. For Django, use `myproject.wsgi:application` in `START` and your project's `manage.py` as `MAIN`. The [Flask](/en/tutorials/api/flask) and [Django](/en/tutorials/api/django) tutorials cover the full deploy. ## Next steps Deploy a Flask application behind Gunicorn. Deploy a Django project behind Gunicorn. Fix EADDRINUSE, LACK\_OF\_RAM and other startup failures. ## Did you like this article? * We created this content with great care to offer the best help possible. If this article helped you in any way, support our work! Developers have already rated Square Cloud **4.9/5 across 402 reviews** on Google and Trustpilot: leave yours too! It helps us understand what matters most to you. Leave your review in Google Reviews. Leave your review in Trustpilot. # Validate Python Data with Pydantic Source: https://docs.squarecloud.app/en/tutorials/python/how-to-validate-data-with-pydantic Pydantic data validation in Python: BaseModel, dataclasses, strict mode, nested models, EmailStr and pydantic-settings to check environment variables at boot. This guide covers data validation with pydantic, a Python library whose validation core (`pydantic-core`) is written in Rust. The examples use pydantic v2. You need Python and the pydantic library: ```bash theme={"system"} pip install pydantic ``` ## Creating a model * First, we will need to import and make our class inherit from `pydantic.BaseModel` to start validating. In our example we will create a class named `Person` and it will have a name, an age and an e-mail. ```python theme={"system"} from pydantic import BaseModel class Person(BaseModel): name: str age: int email: str ``` * With this class, when we instantiate it, pydantic will validate that `name` and `email` are strings and `age` is an integer. ### Using the model * Now that we have it created, we will instantiate the class. We will create a dict containing the data and unpack it into our class. ```python theme={"system"} data = { "name": "John", "age": 19, "email": "john@example.com" } person = Person(**data) ``` * The above example will not raise any error since all **fields** have the correct type. By default, pydantic also converts compatible values: if `age` is the string `"19"`, it becomes the integer `19`. Now we will send wrong data to confirm that our validation works. ```python theme={"system"} data = { "name": "John", "age": "nineteen", "email": "john@example.com" } person = Person(**data) ``` * The above example raises a `ValidationError` because `age` needs to be an **integer** and `"nineteen"` cannot be converted to one: ```text theme={"system"} 1 validation error for Person age Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='nineteen', input_type=str] ``` * To handle the error instead of letting it stop your program, catch it with `try`/`except`. Its `errors()` method lists each invalid field: ```python theme={"system"} from pydantic import ValidationError try: Person(name="John", age="nineteen", email="john@example.com") except ValidationError as error: for item in error.errors(): print(item["loc"], item["msg"]) # ('age',) Input should be a valid integer, unable to parse string as an integer ``` ### Strict mode * If you want to reject strings like `"19"` too, enable strict mode in the model. Then `age` only accepts a real `int`, and `Person(name="John", age="19", email="john@example.com")` raises `ValidationError`. ```python theme={"system"} from pydantic import BaseModel, ConfigDict class Person(BaseModel): model_config = ConfigDict(strict=True) name: str age: int email: str ``` ## Creating a dataclass * You can also create **dataclasses** with pydantic. They are similar to standard Python **dataclasses**, but validate their fields like `BaseModel`. ```python theme={"system"} from pydantic.dataclasses import dataclass @dataclass class Person: name: str age: int email: str ``` * If we send the string `"19"` to `age`, it will convert to the `int` `19`. Pydantic supports recursive validation, meaning that when validating nested models, it also validates the internal models. If a class has a list of `Person`, `people: list[Person]`, pydantic checks each item of the list and converts it into a `Person`. ## Extras * Pydantic has some extras, like **e-mail** validation and a fallback **timezone** package. To install them, run the following commands: ```bash theme={"system"} pip install "pydantic[email]" ``` ```bash theme={"system"} pip install "pydantic[timezone]" ``` * You can install both together by running the following command. ```bash theme={"system"} pip install "pydantic[email,timezone]" ``` * `pydantic[email]` adds the `EmailStr` type, which validates the `user@domain.tld` format and normalizes the address. ```python theme={"system"} from pydantic import EmailStr from pydantic.dataclasses import dataclass @dataclass class Person: name: str age: int email: EmailStr ``` ## Validating environment variables at boot * Bots and APIs read tokens and settings from environment variables. With `pydantic-settings`, a missing or invalid variable stops the application at startup with a clear error, instead of failing later in the middle of a request. ```bash theme={"system"} pip install pydantic-settings ``` * Declare the variables your application needs in a class that inherits from `BaseSettings`. Each field reads the environment variable with the same name, ignoring case: `discord_token` reads `DISCORD_TOKEN`. ```python settings.py theme={"system"} from pydantic import SecretStr from pydantic_settings import BaseSettings class Settings(BaseSettings): discord_token: SecretStr # required: the application doesn't start without it port: int = 80 # optional: 80 when PORT isn't set debug: bool = False settings = Settings() ``` * If `DISCORD_TOKEN` isn't set, `Settings()` raises a `ValidationError` for `discord_token` with the message `Field required`. A value like `PORT=abc` fails the same way, because `port` must be an integer. * `SecretStr` hides the token when you print or log the settings. Read the real value with `settings.discord_token.get_secret_value()`. ## Run it on Square Cloud List pydantic and its extras in your `requirements.txt`, so Square Cloud installs them during the deploy: ```txt requirements.txt theme={"system"} pydantic[email] pydantic-settings ``` Create a `squarecloud.app` file at the root of your project. For a bot whose main file is `main.py` and imports `settings` from `settings.py`: ```systemd squarecloud.app theme={"system"} DISPLAY_NAME=My Python Bot MAIN=main.py MEMORY=512 VERSION=recommended AUTORESTART=true ``` Your ZIP holds your `.py` files, `requirements.txt` and `squarecloud.app`, without the token. Set `DISCORD_TOKEN` and the other variables in the dashboard or with `squarecloud app env set`: see [Environment variables](/en/platform/environment-variables). If a required variable is missing, the `ValidationError` shows up in the application's logs as soon as it starts. ## Next steps Set the variables your settings class reads. Deploy an API that validates its requests with pydantic. Host a bot that reads its token from the environment. ## Did you like this article? * We created this content with great care to offer the best help possible. If this article helped you in any way, support our work! Developers have already rated Square Cloud **4.9/5 across 402 reviews** on Google and Trustpilot: leave yours too! It helps us understand what matters most to you. Leave your review in Google Reviews. Leave your review in Trustpilot. # Receive Top.gg Vote Webhooks Source: https://docs.squarecloud.app/en/tutorials/topgg-webhook-config Top.gg vote webhooks on Square Cloud: receive vote events in Node.js or Python, verify the x-topgg-signature HMAC with your secret and send a test vote. ## Introduction * This guide assumes you have an approved bot on [top.gg](https://top.gg/) and are using either Node.js or Python for your project. * Next, you will need to create an account on Square Cloud, which can be done through the [sign up page](https://squarecloud.app/en/signup). You can use your email to create an account. * Finally, you need to have an active plan on your account. Compare the [available plans](https://squarecloud.app/en/pricing) and choose one according to your needs. ## Setting up the environment 1. Before you begin, make sure you have Node.js and npm installed on your system. If you don't have them yet, you can download them from the [official Node.js website](https://nodejs.org/). 2. Start a new Node.js project and enable the `import` syntax with the following commands: ```bash Terminal theme={"system"} npm init -y npm pkg set type=module ``` These commands create a package.json file in the current directory. 3. Install Express: ```bash Terminal theme={"system"} npm install express ``` 1. Ensure you have Python and Pip (a package manager for Python) installed on your system. If not, you can download them from the [official Python website](https://www.python.org/) and the [official Pip website](https://pypi.org/). 2. Install the `flask` and `waitress` libraries using pip: ```bash theme={"system"} pip install flask waitress ``` ## Setting up the project **1. Get your webhook secret:** * Choose the subdomain your application will use on Square Cloud (the `SUBDOMAIN` field of your configuration file), for example `mysite`. Your webhook URL will then be `https://mysite.squareweb.app/topgg`. * On Top.gg, open your project's dashboard and go to **Webhooks**. * Paste the webhook URL and save. Top.gg then generates a webhook secret that starts with `whs_`: copy it and keep it private. Your code reads it from the `TOPGG_WEBHOOK_SECRET` environment variable. Top.gg signs every request with the `x-topgg-signature` header, in the format `t=,v1=`, where the signature is an HMAC SHA-256 of `.` made with your secret. The code below recomputes it and rejects any request that doesn't match, so nobody else can send fake votes to your URL. See the [Top.gg webhook documentation](https://docs.top.gg/webhooks/overview) for details. This guide uses Top.gg v1 webhooks. The legacy v0 webhook, which sends a password in the `Authorization` header with a different payload, is not covered here. **2. Implement the webhook listener:** The following sections provide code examples for both JavaScript and Python: The example verifies the signature with Node's built-in `crypto` module, so no Top.gg package is needed. The `Webhook` class of `@top-gg/sdk` 4.0.0 is not used: in our tests, its listener answered valid deliveries with a timeout error, which makes Top.gg retry them. ```javascript index.js theme={"system"} import crypto from "node:crypto"; import express from "express"; const app = express(); // The whs_ secret from your project's Webhooks page on Top.gg const SECRET = process.env.TOPGG_WEBHOOK_SECRET; function isValidSignature(rawBody, header = "") { // Header format: t=,v1=."> const parts = Object.fromEntries(header.split(",").map((item) => item.split("="))); const timestamp = Number(parts.t); if (!SECRET || !Buffer.isBuffer(rawBody) || !parts.v1 || !timestamp) return false; // Reject requests older than 5 minutes (replay protection) if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false; const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.`).update(rawBody).digest(); const received = Buffer.from(parts.v1, "hex"); return received.length === expected.length && crypto.timingSafeEqual(received, expected); } // express.raw keeps the exact bytes Top.gg signed app.post("/topgg", express.raw({ type: "*/*" }), (req, res) => { if (!isValidSignature(req.body, req.get("x-topgg-signature"))) return res.sendStatus(401); const { type, data } = JSON.parse(req.body); // "vote.create" is a real vote, "webhook.test" comes from the Send Test button if (type === "vote.create" || type === "webhook.test") { console.log(`Vote received successfully! User ID: ${data.user.platform_id}`); } res.sendStatus(204); }); // Square Cloud sets PORT=80 and routes your subdomain's traffic to it const port = Number(process.env.PORT) || 80; app.listen(port, "0.0.0.0", () => console.log(`Listening on port ${port}`)); ``` For Python, you can use the following code: ```python app.py theme={"system"} import hashlib import hmac import json import os import time from flask import Flask, abort, request from waitress import serve app = Flask(__name__) # The whs_ secret from your project's Webhooks page on Top.gg SECRET = os.environ.get("TOPGG_WEBHOOK_SECRET", "") def is_valid_signature(raw_body: bytes, header: str) -> bool: # Header format: t=,v1=."> try: parts = dict(item.split("=", 1) for item in header.split(",")) timestamp = parts["t"] signature = parts["v1"] age = abs(time.time() - int(timestamp)) except (KeyError, ValueError): return False if age > 300: # reject requests older than 5 minutes (replay protection) return False message = timestamp.encode() + b"." + raw_body expected = hmac.new(SECRET.encode(), message, hashlib.sha256).hexdigest() return hmac.compare_digest(expected.encode(), signature.encode()) # Top.gg sends signed POST requests to this route @app.route("/topgg", methods=["POST"]) def topgg_webhook(): raw_body = request.get_data() if not SECRET or not is_valid_signature(raw_body, request.headers.get("x-topgg-signature", "")): abort(401) payload = json.loads(raw_body) # "vote.create" is a real vote, "webhook.test" comes from the Send Test button if payload["type"] in ("vote.create", "webhook.test"): print(f'Vote received successfully! User ID: {payload["data"]["user"]["platform_id"]}') return "", 204 if __name__ == "__main__": # Square Cloud sets PORT=80 and routes your subdomain's traffic to it serve(app, host="0.0.0.0", port=int(os.environ.get("PORT", 80))) ``` ## Creating the squarecloud config file Create a `squarecloud.app` file in your project folder. Set `SUBDOMAIN` to the subdomain you chose in step 1: ```systemd Node.js theme={"system"} DISPLAY_NAME=Top.gg Webhook MAIN=index.js MEMORY=512 VERSION=recommended SUBDOMAIN=mysite ``` ```systemd Python theme={"system"} DISPLAY_NAME=Top.gg Webhook MAIN=app.py MEMORY=512 VERSION=recommended SUBDOMAIN=mysite ``` `SUBDOMAIN` publishes the listener at `https://mysite.squareweb.app`, and web applications need at least `MEMORY=512`. The code listens on the port in the `PORT` environment variable, which Square Cloud sets to `80`, and on host `0.0.0.0`. The squarecloud.app file is a configuration file that will be used to configure your application; it will be used to define the name, description, version, main file, among other things. ## Uploading your application to Square Cloud After following all the steps, your project folder should contain your code, its dependency file (`package.json` or `requirements.txt`) and the configuration file. To upload from the dashboard, put them into a `.zip` file. If your application is a Node.js project, take a look at our article on [Node.js](/en/articles/getting-started-with-nodejs). If your application is a Python project, take a look at our article on [Python](/en/articles/getting-started-with-python). ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Setting the webhook secret Add your `whs_` secret as the `TOPGG_WEBHOOK_SECRET` environment variable of your application, in one of these ways: * **Dashboard**: on the upload page, open **Advanced configuration** and add the variable before you deploy. For an application that is already deployed, add it on its **Environment Variables** page. * **CLI**: from your project folder, set it with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) and restart the application: ```bash theme={"system"} squarecloud app env set TOPGG_WEBHOOK_SECRET=whs_your_secret squarecloud app restart ``` The application reads environment variables when it starts, so restart it after every change. Until the secret is set, the code rejects every request with `401 Unauthorized`. See [Environment variables](/en/platform/environment-variables) for the other ways to manage them. ## Starting tests If you have done everything correctly, open `https://mysite.squareweb.app/topgg` in your browser (replace `mysite` with your subdomain). If "Cannot GET /topgg" (Node.js) or "Method Not Allowed" (Python) appears, everything is okay: the route only accepts the `POST` requests Top.gg sends. * For the JavaScript code we created with `app.post("/topgg", ...)`, the route that will receive the votes is "/topgg". So, if your website is `mysite.squareweb.app`, the Webhook URL is `https://mysite.squareweb.app/topgg`. * For the Python code we created with `@app.route("/topgg", methods=["POST"])`, the route that will receive the votes is also "/topgg". So, the Webhook URL is the same `https://mysite.squareweb.app/topgg`. Finally, go back to your project's **Webhooks** page on Top.gg and click on the "Send Test" button. After that, check your application's logs. If everything went well, the message you defined in `console.log` or `print` should appear in the logs. And with that, if everything has been configured correctly, your webhook will be ready to send notifications when your bot receives a vote on top.gg. ## Troubleshooting ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Host the bot that receives the votes. Manage your webhook secret and other secrets. Fix port conflicts, missing modules and other startup failures. ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy an Angular App Source: https://docs.squarecloud.app/en/tutorials/website/angular Deploy an Angular app on Square Cloud: build it with ng build, serve the browser folder with the static runtime or Node.js, or run the SSR server. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Angular 22 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Install the Angular CLI and create a project: ```bash theme={"system"} npm install -g @angular/cli ng new my-angular-app ``` The CLI asks about the stylesheet format and whether to enable server-side rendering (SSR). Answer **No** to SSR for a static site, the simplest setup; if you answer **Yes**, see [Server-side rendering](#server-side-rendering-ssr) below. `ng new` installs the dependencies for you. Start the development server with `ng serve` (it listens on `http://localhost:4200`) and edit `src/app/app.html` to change the home page. ## Build for production ```bash theme={"system"} ng build ``` `ng build` uses the production configuration by default. It writes the site to `dist/my-angular-app/browser`. If your project has another name, replace `my-angular-app` in the paths below. ## Choose how to serve it Without SSR, an Angular build is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist/my-angular-app/browser'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist/my-angular-app/browser" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. ## Server-side rendering (SSR) A project created with SSR (or with `ng add @angular/ssr`) also builds a Node.js server into `dist/my-angular-app/server`. That server reads the `PORT` environment variable, which Square Cloud sets to `80`, and listens on all network interfaces, so you don't need to change it. Start it with `START` in your `squarecloud.app`: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=node dist/my-angular-app/server/server.mjs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Angular app SUBDOMAIN=my-angular-app ``` Angular's SSR server only answers requests for host names you allow; any other host gets a `400 Bad Request`. Add your address to the `NG_ALLOWED_HOSTS` [environment variable](/en/platform/environment-variables), for example `my-angular-app.squareweb.app` (separate several hosts with commas), or list it under `security.allowedHosts` in `angular.json` before you build. Run `ng build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the `dist/` folder, without `node_modules`: Square Cloud installs the `dependencies` of your `package.json`, which already include `express` and `@angular/ssr`. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### A refresh on a route returns 404 Your app uses the Angular router and the server does not know the route. On the static runtime, rename `index.html` to `vite.html`. The Express and `serve` options above already return `index.html` for unknown paths. ### The SSR server answers 400 Bad Request The host name of the request is not in the allowed list. Set `NG_ALLOWED_HOSTS` to your subdomain or custom domain, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Angular, see the [official Angular documentation](https://angular.dev). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy an Astro Site Source: https://docs.squarecloud.app/en/tutorials/website/astrojs Deploy an Astro site on Square Cloud: build it into dist/ and serve it with the static runtime or Node.js, or run on-demand rendering with @astrojs/node. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Astro 7 on Node.js 24 in September 2026. ## Create the project You need Node.js 22.12 or later and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npm create astro@latest my-astro-site ``` The initializer asks for a template and offers to install the dependencies. Then enter the project folder: ```bash theme={"system"} cd my-astro-site ``` Start the development server with `npm run dev` (it listens on `http://localhost:4321`). Pages live in `src/pages/`: edit `src/pages/index.astro` to change the home page. ## Build for production ```bash theme={"system"} npm run build ``` By default, Astro prerenders every page and writes the site to the `dist/` folder, one HTML file per page. ## Choose how to serve it A default Astro build is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. Astro writes one HTML file per page, so on the static runtime keep `index.html` (no `vite.html` rename): your `src/pages/404.astro` page becomes the `404.html` that answers unknown paths. ## On-demand rendering (SSR) Pages rendered on each request need a server. Add the Node.js adapter in standalone mode: ```bash theme={"system"} npx astro add node ``` `npm run build` then writes the server to `dist/server/entry.mjs` and the browser files to `dist/client/`. The server reads the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`, so you don't need to change them. Set it as the main file in your `squarecloud.app`: ```systemd squarecloud.app theme={"system"} MAIN=dist/server/entry.mjs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Astro site SUBDOMAIN=my-astro-site ``` Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the `dist/` folder, without `node_modules`: Square Cloud installs the `dependencies` of your `package.json`, which include `astro` and `@astrojs/node`. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Astro, see the [official Astro documentation](https://docs.astro.build/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Gatsby Site Source: https://docs.squarecloud.app/en/tutorials/website/gatsby Deploy a Gatsby site on Square Cloud: build it with npm run build, then serve the public/ folder with the static runtime or a small Node.js server. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Gatsby 5 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npm create gatsby@latest ``` The initializer asks for the site name, the folder and options such as TypeScript and a CMS, then installs the dependencies. Enter the folder it created: ```bash theme={"system"} cd ``` Start the development server with `npm run develop` (it listens on `http://localhost:8000`). Pages live in `src/pages/`: edit `src/pages/index.js` (or `index.tsx`) to change the home page. ## Build for production ```bash theme={"system"} npm run build ``` Gatsby writes the site to the `public/` folder, one HTML file per page. ## Choose how to serve it A Gatsby build is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'public'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s public" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. Gatsby writes one HTML file per page, so on the static runtime keep `index.html` (no `vite.html` rename): your `src/pages/404.js` page becomes the `404.html` that answers unknown paths. To keep `squarecloud.app` across builds, put it in the `static/` folder: Gatsby copies that folder unchanged into `public/`. This guide covers static Gatsby sites. Pages that use server-side rendering (`getServerData`), Deferred Static Generation or Gatsby Functions need a Gatsby server and are not covered here. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Gatsby, see the [official Gatsby documentation](https://www.gatsbyjs.com/docs/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Next.js Hosting: Deploy a Next.js App Source: https://docs.squarecloud.app/en/tutorials/website/nextjs Deploy a Next.js app on Square Cloud: build it with next build, run next start with a START command, zip the project with .next, and go live on HTTPS. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Next.js 16 on Node.js 24 in September 2026. ## Create the project You need Node.js 20.9 or later and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npx create-next-app@latest my-app ``` The initializer asks about TypeScript, the linter, Tailwind CSS and the App Router, then installs the dependencies. Start the development server with `npm run dev` and edit `app/page.tsx` (or `app/page.js`) to change the home page. ## Build for production ```bash theme={"system"} npm run build ``` `next build` writes the production build to the `.next` folder. Run it on your machine: TypeScript, ESLint and Tailwind CSS are `devDependencies`, which Square Cloud does not install. ## Port and host Nothing to change in Next.js: `next start` reads the `PORT` environment variable, which Square Cloud sets to `80`, and listens on all network interfaces. Keep the default `start` script in your `package.json`: ```json package.json theme={"system"} "scripts": { "start": "next start" } ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Next.js app SUBDOMAIN=my-next-app ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` runs `next start`. In the dashboard upload, set the same start command. ## What goes in the ZIP * `.next/`, the production build (Square Cloud removes `.next/cache` on upload, so you can leave it out). * `public/`, `package.json` and your `next.config.*` file. * `squarecloud.app`. * Your source folders (`app/` or `pages/`) are not read by `next start`, but uploading them does no harm. Leave out `node_modules`: Square Cloud installs your `dependencies` on the first start. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### Could not find a production build `next start` did not find the `.next` folder. Run `npm run build` before zipping and check that `.next` is in the ZIP. ## Deploy on every push with GitHub Actions The [Square Cloud GitHub Action](https://github.com/squarecloudofc/github-action) installs the CLI on the runner, so a workflow can build your app and send it to Square Cloud. Save an [API key](https://squarecloud.app/en/account/security) as the repository secret `SQUARECLOUD_API_KEY` and your application ID as the repository variable `SQUARECLOUD_APP_ID`, then add `.github/workflows/deploy.yml`: ```yaml .github/workflows/deploy.yml theme={"system"} name: Deploy Next.js app on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 - uses: squarecloudofc/github-action@v2 with: token: ${{ secrets.SQUARECLOUD_API_KEY }} install-only: true - run: npm ci && npm run build - run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart ``` `squarecloud commit` sends the folder, including the fresh `.next` build, to your application, and `--restart` restarts it so the new build goes live. Add `.next/cache` to a [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) file to keep the upload small. For more options, see [deploying with GitHub Actions](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/). ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Next.js, see the [official Next.js documentation](https://nextjs.org/docs). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Nuxt App (Nitro Server) Source: https://docs.squarecloud.app/en/tutorials/website/nuxt Deploy a Nuxt app on Square Cloud: build it with npm run build, run the .output/server/index.mjs server as MAIN, or generate a static site instead. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs), or on the [static runtime](/en/articles/getting-started-with-html) for a generated site. Tested with Nuxt 4 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer, which replaces `nuxi init`: ```bash theme={"system"} npm create nuxt@latest my-nuxt-app ``` The initializer asks for a template and the package manager, then installs the dependencies. Enter the project folder and start the development server: ```bash theme={"system"} cd my-nuxt-app npm run dev ``` The development server listens on `http://localhost:3000`. Edit `app/app.vue` to change the home page, or create `app/pages/index.vue` to use file-based routing. ## Build for production ```bash theme={"system"} npm run build ``` Nuxt builds a standalone Node.js server with Nitro into the `.output` folder. Its entry file is `.output/server/index.mjs`, and `.output/server` carries its own dependencies. ## Port and host Nothing to change in Nuxt: the Nitro server reads the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`. ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project and point `MAIN` to the Nitro server: ```systemd squarecloud.app theme={"system"} MAIN=.output/server/index.mjs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Nuxt app SUBDOMAIN=my-nuxt-app ``` Square Cloud starts it with `node .output/server/index.mjs`. In the dashboard upload, set the same main file. ## What goes in the ZIP * `.output/`, the production build. * `package.json`, `nuxt.config.ts` and your source folders (`app/`, `public/` and the others your project has): on the first start, Square Cloud runs `npm install`, and the `postinstall` script of Nuxt projects (`nuxt prepare`) needs them. * `squarecloud.app`. Leave out `node_modules` and `.nuxt`: they are regenerated on the server. ## Static generation instead of a server If every page can be generated at build time, run `npm run generate` instead of `npm run build`. Nuxt writes a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps) to `.output/public`, which the static runtime serves without a Node.js process: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. `nuxt generate` prerenders one HTML file per page and a `404.html`, so keep `index.html` (no `vite.html` rename). ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### Cannot find module .output/server/index.mjs The build is missing from the ZIP. Run `npm run build` and check that the `.output` folder is at the root of the ZIP, next to `squarecloud.app`. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Nuxt, see the [official Nuxt documentation](https://nuxt.com/docs). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Phoenix (Elixir) App Source: https://docs.squarecloud.app/en/tutorials/website/phoenix Deploy a Phoenix app on Square Cloud: set SECRET_KEY_BASE and PHX_HOST, build assets and start the server in production mode with a START command. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Elixir runtime](/en/articles/getting-started-with-elixir). ## Create the project You need Erlang/OTP and Elixir on your machine. If you don't have them, follow the [official Elixir installation guide](https://elixir-lang.org/install.html). Install the Phoenix project generator and create a project: ```bash theme={"system"} mix archive.install hex phx_new mix phx.new my_app --no-ecto ``` `--no-ecto` creates a project without a database, the simplest setup to deploy. Drop it if you need Ecto, then see [Environment variables](#environment-variables) for the database address. Start the development server: ```bash theme={"system"} cd my_app mix phx.server ``` Phoenix listens on `http://localhost:4000` in development. ## Build for production Square Cloud builds your app when it starts: before running your `START` command, it fetches your dependencies with `mix deps.get`. The `START` command below then compiles the app in production mode (`MIX_ENV=prod`), builds and digests the assets with `mix assets.deploy`, and starts the server. You don't need to build anything on your machine, and your ZIP holds the project source. The first start compiles your dependencies and downloads the asset tools (esbuild and Tailwind), so it takes a few minutes. Later starts reuse the compiled files. ## Port and host Nothing to change: in production, the generated `config/runtime.exs` reads the `PORT` environment variable, which Square Cloud sets to `80`, and listens on all network interfaces. ## Environment variables Set these [environment variables](/en/platform/environment-variables) in the dashboard or with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set): | Variable | Value | | - | - | | `SECRET_KEY_BASE` | The output of `mix phx.gen.secret`. Production refuses to start without it | | `PHX_HOST` | Your site's host name, for example `my-app.squareweb.app`. Phoenix builds URLs with it and LiveView accepts WebSocket connections only from this host | | `DATABASE_URL` | Only for projects with Ecto: your database connection, for example `ecto://user:password@host:port/database` | ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=mix.exs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Phoenix app SUBDOMAIN=my-app START=MIX_ENV=prod mix assets.deploy && MIX_ENV=prod mix phx.server ``` `MAIN=mix.exs` tells Square Cloud that the project runs on Elixir, and `START` replaces the default `mix run --no-halt`. `mix phx.server` starts the web server, so you don't need `PHX_SERVER`. Projects with Ecto can apply migrations on every start by adding `MIX_ENV=prod mix ecto.migrate && ` before `mix phx.server`. ## What goes in the ZIP * `mix.exs` and `mix.lock`. * `config/`, `lib/`, `assets/`, `priv/` and the other source folders. * `squarecloud.app`. Leave out `_build/`, which holds files compiled for your machine, and `deps/`: Square Cloud fetches the dependencies again and compiles everything on Linux. Prefer a release? A release built on Windows or macOS does not run on Square Cloud, which runs Linux: build it on Linux, for example in WSL. Its start script is `_build/prod/rel/my_app/bin/my_app`, so the command is `START=PHX_SERVER=true _build/prod/rel/my_app/bin/my_app start`; `PHX_SERVER=true` makes the release start the web server. Keep `mix.exs` and `mix.lock` in the ZIP, because Square Cloud runs `mix deps.get` before `START`. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### environment variable SECRET\_KEY\_BASE is missing Set `SECRET_KEY_BASE` as shown in [Environment variables](#environment-variables), then restart the application. ### LiveView keeps reconnecting `PHX_HOST` does not match the address in the browser. Set it to your subdomain or custom domain, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Phoenix, see the [official Phoenix documentation](https://hexdocs.pm/phoenix/) and its [release guide](https://hexdocs.pm/phoenix/releases.html). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Preact App Source: https://docs.squarecloud.app/en/tutorials/website/preact Deploy a Preact app on Square Cloud: create it with npm init preact, build it into dist/, and serve it with the static runtime or a Node.js server. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Preact 10 and Vite 8 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer, `create-preact`: ```bash theme={"system"} npm init preact ``` The initializer asks for the project folder and options such as TypeScript, the router and prerendering (SSG). You don't need to install the older `preact-cli`. Then enter the project folder and install the dependencies if the initializer did not: ```bash theme={"system"} cd npm install ``` Start the development server with `npm run dev` and edit `src/index.jsx` (or `src/index.tsx`) to change the home page. ## Build for production ```bash theme={"system"} npm run build ``` `create-preact` projects build with Vite, which writes the production files to the `dist/` folder. ## Choose how to serve it A Preact build is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### A refresh on a route returns 404 Your app uses the Preact router and the server does not know the route. On the static runtime, rename `index.html` to `vite.html`. The Express and `serve` options above already return `index.html` for unknown paths. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Preact, see the [official Preact documentation](https://preactjs.com/guide/v10/getting-started). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Qwik App Source: https://docs.squarecloud.app/en/tutorials/website/qwik Deploy a Qwik City app on Square Cloud: add the static adapter and serve dist/ with the static runtime, or add the Express adapter and run its server. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Qwik 1 and Qwik City on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npm create qwik@latest ``` The initializer asks for a starter, the project folder and whether to install the dependencies. The starters create a Qwik City app, with file-based routes in `src/routes/`. Enter the project folder and start the development server with `npm run dev`. A new project has no deploy target yet: `npm run build` ends with **Missing an integration**. Add an adapter first, as shown below. ## Choose how to serve it Add the static adapter, which prerenders every route at build time: ```bash theme={"system"} npm run qwik add static ``` `npm run build` then writes a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps) to `dist/`, one HTML file per page plus a `404.html`, so keep `index.html` (no `vite.html` rename). The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. Add the Express adapter to render pages on each request: ```bash theme={"system"} npm run qwik add express ``` The server bundle imports `undici` and `dotenv`, which the project lists as `devDependencies`. Square Cloud does not install those, so move them to `dependencies`: ```bash theme={"system"} npm install --save-prod undici dotenv ``` Run `npm run build`. It writes the browser files to `dist/` and the server to `server/entry.express.js`. Nothing to change in the server: it reads the `PORT` environment variable, which Square Cloud sets to `80`, and listens on all network interfaces. Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=server/entry.express.js MEMORY=512 VERSION=recommended DISPLAY_NAME=My Qwik app SUBDOMAIN=my-qwik-app ``` The ZIP needs `dist/`, `server/`, `package.json` and `squarecloud.app`, without `node_modules`: Square Cloud installs your `dependencies` on the first start. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### Cannot find package 'undici' The server needs a package that is still in `devDependencies`. Run `npm install --save-prod undici dotenv` and upload the new `package.json`. Square Cloud installs dependencies only when `node_modules` is missing, so delete the `node_modules` folder of your application in the dashboard file manager, then restart it. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Qwik, see the [official Qwik documentation](https://qwik.dev/docs/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a React App (Vite Build) Source: https://docs.squarecloud.app/en/tutorials/website/react Deploy a React app on Square Cloud: build it with Vite into dist/, then serve it with the static runtime or a small Node.js server on your subdomain. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with React 19 and Vite 8 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a React project with [Vite](https://vite.dev/): ```bash theme={"system"} npm create vite@latest my-react-app -- --template react ``` `my-react-app` is the project folder. Use `--template react-ts` for TypeScript. The `--` passes the option to the initializer instead of to npm. Then install the dependencies: ```bash theme={"system"} cd my-react-app npm install ``` Using React Router in framework mode, with server rendering? Follow the [React Router guide](/en/tutorials/website/remix) instead. Using Next.js? Follow the [Next.js guide](/en/tutorials/website/nextjs). ## Build for production ```bash theme={"system"} npm run build ``` Vite writes the production files to the `dist/` folder. ## Choose how to serve it A React app built with Vite is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### A refresh on a route returns 404 Your app uses client-side routing, for example with React Router in declarative mode, and the server does not know the route. On the static runtime, rename `index.html` to `vite.html`. The Express and `serve` options above already return `index.html` for unknown paths. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about React, see the [official React documentation](https://react.dev/learn). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy React Router (formerly Remix) Source: https://docs.squarecloud.app/en/tutorials/website/remix Deploy a React Router app (formerly Remix) on Square Cloud: build with npm run build, set START=npm run start to run react-router-serve, and go live. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with React Router 8 on Node.js 24 in September 2026. Remix merged into React Router: React Router framework mode, since v7, is the successor of Remix v2. New projects use `create-react-router` instead of `create-remix`. If you still have a Remix v2 project, see [Existing Remix v2 projects](#existing-remix-v2-projects). ## Create the project You need Node.js 22.22 or later and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npx create-react-router@latest my-app ``` The initializer creates the project and offers to install its dependencies. Enter the project folder and start the development server: ```bash theme={"system"} cd my-app npm run dev ``` The development server usually listens on `http://localhost:5173/`. Routes are declared in `app/routes.ts`, and the starter maps the home page to `app/routes/home.tsx`. Replace the content of that file with a simple example: ```tsx app/routes/home.tsx theme={"system"} export default function Home() { return
Hello World from React Router!
; } ``` ## Build for production ```bash theme={"system"} npm run build ``` This creates the `build/` folder: `build/client` holds the static assets and `build/server` holds the server code. The build tools (`@react-router/dev` and Vite) are `devDependencies`, which Square Cloud does not install, so run the build on your machine. ## Port and host Nothing to change: the starter includes `@react-router/serve`, a production Node.js server, and a `start` script that runs it. `react-router-serve` reads the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`. ```json package.json theme={"system"} "scripts": { "start": "react-router-serve ./build/server/index.js" } ``` ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start MEMORY=1024 VERSION=recommended DISPLAY_NAME=My React Router app SUBDOMAIN=myapp ``` `RUNTIME=nodejs` selects the Node.js runtime without requiring a `MAIN` file, and `START` replaces the default start command. In the dashboard upload, set the same start command. ## What goes in the ZIP * `build/`, the production build. * `package.json`. * `squarecloud.app`. Leave out `node_modules`: Square Cloud installs your `dependencies`, including `@react-router/serve`, on the first start. ### Existing Remix v2 projects Remix v2 projects deploy the same way: run `npm run build` locally and keep `START=npm run start`, where the `start` script runs `@remix-run/serve`, which also reads `PORT` and `HOST`: ```bash theme={"system"} remix-serve ./build/server/index.js ``` Projects still on the classic Remix compiler (without Vite) use `remix-serve ./build/index.js` instead. To move to React Router, follow the [official upgrade guide](https://reactrouter.com/upgrading/remix). ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about React Router, see the [official React Router documentation](https://reactrouter.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Ruby on Rails App Source: https://docs.squarecloud.app/en/tutorials/website/ruby-on-rails Deploy a Ruby on Rails app on Square Cloud: set RAILS_MASTER_KEY, then precompile assets, prepare the database and start the server with a START command. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Ruby runtime](/en/articles/getting-started-with-ruby). ## Create the project You need Ruby and Bundler on your machine. If you don't have Ruby yet, download it from the [official Ruby website](https://www.ruby-lang.org/). Install Rails and create a project: ```bash theme={"system"} gem install rails rails new myapp ``` New Rails projects use SQLite, stored in the `storage/` folder, so they run without an external database. Start the development server: ```bash theme={"system"} cd myapp bin/rails server ``` Rails listens on `http://localhost:3000` in development. Keep the default port on your machine: you don't need port 80 locally. ## Build for production Square Cloud prepares the app when it starts: it runs `bundle install` to install the gems in your `Gemfile`, then your `START` command precompiles the assets and prepares the database. The Ruby runtime sets `RACK_ENV=production`, so Rails runs in production mode. ## Port and host Nothing to change: `rails server` reads the `PORT` environment variable, which Square Cloud sets to `80`, and in production it listens on all network interfaces. ## Environment variables Set these [environment variables](/en/platform/environment-variables) in the dashboard or with [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set): | Variable | Value | | - | - | | `RAILS_MASTER_KEY` | The content of your `config/master.key` file. Rails decrypts `config/credentials.yml.enc`, including `secret_key_base`, with it | | `BUNDLE_WITHOUT` | `development:test`, so `bundle install` skips the gems you only use on your machine | ## Configure Square Cloud Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=ruby MEMORY=1024 VERSION=recommended DISPLAY_NAME=My Rails app SUBDOMAIN=myapp START=rm -f tmp/pids/server.pid && bundle exec rails assets:precompile && bundle exec rails db:prepare && bundle exec rails server ``` On every start, this command: * removes a server PID file left by a previous run, which would stop Rails from starting; * `rails assets:precompile` builds your CSS and JavaScript into `public/assets`; * `rails db:prepare` creates the databases or applies pending migrations; * `rails server` starts Puma. `RUNTIME=ruby` selects the Ruby runtime without a `MAIN` file. The commands use `bundle exec rails` instead of `bin/rails` because a ZIP made on Windows can lose the permission to execute `bin/rails`. ## What goes in the ZIP * Your whole project: `app/`, `bin/`, `config/`, `db/`, `lib/`, `public/`, `Gemfile`, `Gemfile.lock` and `config.ru`. * `squarecloud.app`. Leave out `config/master.key` (the key goes in `RAILS_MASTER_KEY`), `log/`, `tmp/` and the local databases in `storage/`. ## Deploy and verify ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### Missing secret\_key\_base or ActiveSupport::MessageEncryptor::InvalidMessage `RAILS_MASTER_KEY` is missing or does not match `config/credentials.yml.enc`. Copy the content of the `config/master.key` that created those credentials, then restart the application. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Rails, see the [official Rails guides](https://guides.rubyonrails.org/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a SolidJS App Source: https://docs.squarecloud.app/en/tutorials/website/solidjs Deploy a SolidJS app on Square Cloud: run the SolidStart server from .output/server/index.mjs, or serve a Solid and Vite build with the static runtime. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [Node.js runtime](/en/articles/getting-started-with-nodejs) or the [static runtime](/en/articles/getting-started-with-html). Tested with SolidStart 2 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npm create solid@latest ``` The initializer asks for the project folder and the kind of project: * **SolidStart**: a full-stack app with server-side rendering, which runs as a Node.js server. SolidStart 2 needs Node.js 24 or later. * **Solid + Vite** (vanilla): a single-page app that builds to [static files](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps). Then enter the project folder, install the dependencies and start the development server: ```bash theme={"system"} cd npm install npm run dev ``` ## Build and serve it Build the app: ```bash theme={"system"} npm run build ``` SolidStart writes a standalone Node.js server to the `.output` folder. Its entry file is `.output/server/index.mjs`, the same file the `start` script runs. Nothing to change in SolidStart: the server reads the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`. Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} MAIN=.output/server/index.mjs MEMORY=1024 VERSION=recommended DISPLAY_NAME=My SolidStart app SUBDOMAIN=my-solid-app ``` Both `VERSION` values run Node.js 24 or later, as SolidStart 2 requires. The ZIP needs `.output/`, `package.json` and `squarecloud.app`, without `node_modules`: Square Cloud installs your `dependencies` on the first start. Build the app: ```bash theme={"system"} npm run build ``` Vite writes the production files to the `dist/` folder. Serve them with the static runtime, the lightest option: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. To serve `dist/` with a Node.js server instead, use the Express or `serve` option of the [Vite guide](/en/tutorials/website/vite#choose-how-to-serve-it). ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Solid, see the [official Solid documentation](https://docs.solidjs.com/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Vite App Source: https://docs.squarecloud.app/en/tutorials/website/vite Deploy a Vite app on Square Cloud: build it with npm run build, then serve dist/ with the static runtime or a small Node.js server on your subdomain. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Vite 8 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer: ```bash theme={"system"} npm create vite@latest my-vite-app -- --template react ``` `my-vite-app` is the project folder. `--template` picks the framework: `vanilla`, `vue`, `react`, `preact`, `lit`, `svelte`, `solid` or `qwik`, each with a TypeScript variant ending in `-ts`, such as `react-ts`. The `--` passes the option to the initializer instead of to npm. Without `--template`, the initializer asks which framework and variant you want. Then install the dependencies: ```bash theme={"system"} cd my-vite-app npm install ``` ## Build for production ```bash theme={"system"} npm run build ``` Vite writes the production files to the `dist/` folder. Don't use `vite preview` to serve them on Square Cloud: it is a local preview of the build, not a production server. ## Choose how to serve it A Vite build is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### A refresh on a route returns 404 Your app uses client-side routing and the server does not know the route. On the static runtime, rename `index.html` to `vite.html`. The Express and `serve` options above already return `index.html` for unknown paths. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Vite, see the [official Vite documentation](https://vite.dev/guide/). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # Deploy a Vue App Source: https://docs.squarecloud.app/en/tutorials/website/vue Deploy a Vue app on Square Cloud: scaffold it with npm create vue@latest, build it into dist/, and serve it with the static runtime or a Node.js server. ## Introduction To develop and host on Square Cloud, it's essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment. ### Prerequisites * **Square Cloud Account**: Register through the [signup page](https://squarecloud.app/en/signup) using your email. * **Active plan**: Ensures dedicated resources and optimized performance for your application. Check our [available plans](https://squarecloud.app/en/pricing) and choose the most suitable for your needs. This guide runs on the [static runtime](/en/articles/getting-started-with-html) or the [Node.js runtime](/en/articles/getting-started-with-nodejs). Tested with Vue 3 and Vite 8 on Node.js 24 in September 2026. ## Create the project You need Node.js and npm on your machine. If you don't have them, download them from the [official Node.js website](https://nodejs.org/). Create a project with the official initializer, `create-vue`: ```bash theme={"system"} npm create vue@latest ``` The initializer asks for the project name and the features you want, such as TypeScript and Vue Router. Then enter the project folder and install the dependencies: ```bash theme={"system"} cd npm install ``` ## Build for production ```bash theme={"system"} npm run build ``` Vite, the build tool of `create-vue` projects, writes the production files to the `dist/` folder. ## Choose how to serve it A Vue app built this way is a [static site](/en/articles/getting-started-with-html#static-sites-and-server-rendered-apps): HTML, CSS and JavaScript files that any web server can deliver. Pick one of these options: The static runtime serves the files of your build with a web server managed by Square Cloud. No Node.js process runs, so it is the lightest way to host a site without server-side code. Run `npm run build`. The output goes to the folder. If your app changes pages in the browser without a reload (client-side routing), rename /index.html to `vite.html`. The static runtime answers every path that is not a file with `vite.html`, so refreshing a route such as `/about` still loads your app. A site with one HTML file per page keeps `index.html`: unknown paths then return your `404.html`. See [how the static runtime serves files](/en/articles/getting-started-with-html#how-the-static-runtime-serves-files). Create a `squarecloud.app` file inside . A `MAIN` that points to an HTML file selects the static runtime: ```systemd squarecloud.app theme={"system"} MAIN=vite.html MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Use `MAIN=index.html` if you kept `index.html`. 512 MB is the minimum memory for a website. When you upload through the dashboard, it asks for these values and writes the file for you. Zip the contents of , not the folder itself, so that `squarecloud.app` sits at the root of the ZIP. With the CLI, run `squarecloud upload` from inside . Everything in the ZIP is public on your site. Upload only the build output, never your source code or `.env` files. Most build tools empty on every build. Keep a copy of `squarecloud.app` in the folder that your framework copies unchanged into the build (`public/` in Vite-based projects), or repeat the last three steps after each build. This option runs a small [Express](https://expressjs.com/) server on the Node.js runtime. Install Express as a regular dependency, not a `devDependency`, which Square Cloud does not install: ```bash theme={"system"} npm install express ``` Create a `server.mjs` file at the root of your project. It serves the build output folder, , and returns `index.html` for any other path so client-side routing keeps working: ```javascript server.mjs theme={"system"} import express from 'express'; import path from 'node:path'; const app = express(); const distPath = path.join(import.meta.dirname, 'dist'); app.use(express.static(distPath)); // SPA fallback: serve index.html for any route not matched above app.use((req, res) => { res.sendFile(path.join(distPath, 'index.html')); }); // Square Cloud sets PORT=80; 0.0.0.0 accepts connections from outside the container const port = Number(process.env.PORT) || 80; app.listen(port, '0.0.0.0', () => console.log(`Server running on port ${port}`)); ``` To try it on your machine, pick a free port: `PORT=3000 node server.mjs`. Create a `squarecloud.app` file at the root of your project. Square Cloud starts your site with `node server.mjs`: ```systemd squarecloud.app theme={"system"} MAIN=server.mjs MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` Run `npm run build` before creating your ZIP. The ZIP needs `server.mjs`, `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. This option runs the [`serve`](https://www.npmjs.com/package/serve) package on the Node.js runtime, with no server code to write. Install it as a regular dependency: ```bash theme={"system"} npm install serve ``` Add a `start:prod` script to the `scripts` of your `package.json`, next to the ones you already have: ```json package.json theme={"system"} "scripts": { "start:prod": "serve -s dist" } ``` serve -s serves the build output folder, , in single-page mode: any path that is not a file returns `index.html`, so client-side routing keeps working. `serve` listens on all network interfaces, on the port in the `PORT` environment variable, which Square Cloud sets to `80` (locally, it falls back to `3000`). Create a `squarecloud.app` file at the root of your project: ```systemd squarecloud.app theme={"system"} RUNTIME=nodejs START=npm run start:prod MEMORY=512 VERSION=recommended DISPLAY_NAME=My website SUBDOMAIN=mywebsite ``` `RUNTIME=nodejs` selects the Node.js runtime without a `MAIN` file, and `START` replaces the default start command. Run `npm run build` before creating your ZIP. The ZIP needs `package.json`, `squarecloud.app` and the folder, without `node_modules`: Square Cloud installs your dependencies on the first start. Build tools are usually `devDependencies`, which Square Cloud does not install, so the build has to run on your machine. Need server-side rendering with Vue? Follow the [Nuxt guide](/en/tutorials/website/nuxt). ## Deploy and verify Create the ZIP described in the option you picked, then upload it: ### Via dashboard Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file. After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.\ If you are uploading a web project, make sure to select "Web Publication" and set a subdomain to your project. Finally, click on the "Deploy" button to host your project on Square Cloud.\ After deployment, you can monitor your project's status and logs from the dashboard. Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/dashboard), wait for your application status to show as running and check the logs for any startup errors.\ If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ### Via CLI To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application. Learn how to create the `squarecloud.app` configuration file that defines your application's environment. Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it: ```bash macOS, Linux, and WSL theme={"system"} curl -fsSL https://cli.squarecloud.app/install | bash ``` ```bash Windows with npm theme={"system"} npm install -g @squarecloud/cli@latest ``` Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see [CLI authentication](/en/cli-reference/authentication). ```bash theme={"system"} squarecloud auth login ``` From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it: ```bash theme={"system"} squarecloud upload ``` To upload a zip you created yourself, pass it with `--file`: ```bash theme={"system"} squarecloud upload --file ``` Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal: ```bash theme={"system"} squarecloud app status squarecloud app logs ``` If you deployed a website or API, open `https://.squareweb.app` in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online. App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes. ## Common errors ### Custom domain To use a custom domain (e.g., `mysite.com`) instead of the default URL `mysite.squareweb.app`, you need the **Standard plan or higher**. The default URL comes from the **SUBDOMAIN** field in the configuration file. To connect your domain, follow [how to set up your own domain](https://help.squarecloud.app/en-us/article/how-to-set-up-your-own-domain-cnamedns-1fzbrgh/). ### Minimum RAM requirements **Minimum: 512MB RAM** for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend **at least 1GB RAM**. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing. ### Could not find this site. Check if the **subdomain/domain** matches what's configured in the **SUBDOMAIN** field or in the **custom domain settings**. If you just uploaded the site, wait up to **60 seconds** for Square to enable **first access**. ### Site took too long to respond... Your server must listen on **port 80** and **host 0.0.0.0**. Square Cloud sets the **PORT** (`80`) and **HOST** (`0.0.0.0`) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on `localhost` or `127.0.0.1` never receives requests. ### A refresh on a route returns 404 Your app uses Vue Router in history mode and the server does not know the route. On the static runtime, rename `index.html` to `vite.html`. The Express and `serve` options above already return `index.html` for unknown paths. ## Next steps Keep secrets and settings out of your code and read them at runtime. Serve your app on your own domain, on the Standard plan and above. Fix an app that does not start or a site that does not respond. For more about Vue, see the [official Vue documentation](https://vuejs.org/guide/introduction.html). ## Contact us If you continue facing **technical difficulties**, our **specialized support team** is available to assist you. [**Contact us**](https://squarecloud.app/en/support) and we'll be happy to help you resolve any issue: support quality is a big part of why developers rate Square Cloud [**4.9/5 across 402 reviews**](https://www.trustpilot.com/review/squarecloud.app) on Google and Trustpilot. # VS Code extension commands and settings Source: https://docs.squarecloud.app/en/vscode-extension/commands Run every Square Cloud extension command from the VS Code command palette or side bar, and find its settings, refresh behavior and fixes for common problems. ## Commands Open the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type **Square Cloud**. | Command | Where else it appears | | - | - | | `Square Cloud: Connect Account` | Sign-in view, status bar when disconnected | | `Square Cloud: Get Started` | Sign-in view, side bar `...` menu | | `Square Cloud: Refresh` | Side bar title bar, status bar | | `Square Cloud: Upload New Application` | Side bar title bar, empty Applications section | | `Square Cloud: Show Service Status` | Side bar footer, with an account connected | | `Square Cloud: Create Database` | Side bar `...` menu, empty Databases section | | `Square Cloud: Create Workspace` | Side bar `...` menu, empty Workspaces section | | `Square Cloud: Copy My Invite Code` | Side bar `...` menu | | `Square Cloud: Disconnect Account` | Side bar `...` menu | With an account connected, the palette also runs the application and database actions. Each one asks which application or database to use and lists only the ones it applies to: Start offers applications that aren't running, Stop and Restart the ones that aren't stopped, the edge tools only websites, and metrics only applications with 512 MB or more. | Group | Commands | In the CLI | | - | - | - | | Lifecycle | Start Application..., Stop Application..., Restart Application... | [`app start`, `stop`, `restart`](/en/cli-reference/apps) | | Logs and metrics | Show Application Logs..., Toggle Application Realtime Stream..., Show 24h Application Metrics... | [`app logs`, `realtime`](/en/cli-reference/logs), [`app metrics`](/en/cli-reference/status-and-metrics) | | Deploy | Commit Files to Application..., Download Application Snapshot..., Restore Application Snapshot... | [`commit`](/en/cli-reference/deploy), [`app snapshot`](/en/cli-reference/snapshots) | | Configuration | Edit Application Environment Variables..., Link Application to GitHub Repository..., Unlink Application from GitHub Repository... | [`app env`](/en/cli-reference/environment-variables), [`app deploy github`](/en/cli-reference/github-deploys) | | Edge (websites) | Show Edge Logs..., Show Edge Errors..., Show Edge Performance..., Purge Edge Cache... | [`app network`](/en/cli-reference/edge-analytics) | | Other | Open Application in Web Dashboard..., Copy Application ID..., Delete Application... | [`app info`, `app delete`](/en/cli-reference/apps) | | Databases | Start Database..., Stop Database..., Download Database TLS Certificate..., Delete Database... | [`db`](/en/cli-reference/databases) | The same actions are in the menu of each card in the side bar: right-click an application, database or workspace, or use its ⋯ button. ## Settings | Setting | Default | Description | | - | - | - | | `squarecloud.favApps` | `[]` | IDs of your favorite applications, shown at the top of the list. The star on each card manages it, so you rarely need to edit it by hand. | ## Activation and refresh The extension activates only when needed: when the workspace has a `squarecloud.app` or `squarecloud.config` file, or when you open the Square Cloud side bar, run one of its commands or open a config file. Until then, it has no background activity. Once active, it refreshes your account every **60 seconds**. Polling pauses while the VS Code window is out of focus and refreshes as soon as you come back, so an idle editor doesn't spend your API quota. When a rate limit is hit, background polling pauses for a few minutes and the side bar keeps what is already on screen. ## Troubleshooting Check that an account is connected: without one, the side bar shows the sign-in screen. If Square Cloud can't be reached, is pausing requests or is under maintenance, the side bar says which, with **Try again** and **Service status** buttons. Authorizations last 90 days and can't be renewed silently. Run `Square Cloud: Connect Account` again. You can revoke an authorization at any time under **My Account → Authentication** in the [dashboard](https://squarecloud.app/en/account/security). Don't enter it. Approving someone else's code connects their editor to your account. If the page rejects the code you pasted, start over from VS Code. The chosen folder needs a `squarecloud.app` or `squarecloud.config` file at its root. See the [config file guide](/en/getting-started/config-file). Zips are limited to 100 MB. Add build output, caches and dependency folders to [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore). `node_modules` and `.git` are already left out, and dependencies are installed on the platform from your manifest. Wait before trying again. Background polling already backs off on its own, and retrying over and over only keeps the limit in place. Open **View → Output** and pick the **Square Cloud** channel for a log of every API call, and include it when you report a bug on [GitHub](https://github.com/squarecloudofc/vscode-extension). Click the status bar item or the refresh icon in the side bar's title bar. Remember that polling pauses while the window is out of focus. # Square Cloud VS Code extension features Source: https://docs.squarecloud.app/en/vscode-extension/features Deploy, manage and monitor Square Cloud apps, databases and workspaces from the VS Code side bar, with snapshots, edge analytics and config file IntelliSense. ## Deploying ### Upload a new application Run `Square Cloud: Upload New Application` from the command palette, the upload icon in the side bar's title bar, or **Upload your first application** on an empty account. Your open workspace folders come first; **Browse...** picks any other folder. The folder must contain a [`squarecloud.app` or `squarecloud.config`](/en/getting-started/config-file) file. Without one, nothing is uploaded and the error links to the config file guide. A dialog asks before anything leaves your machine. The folder is zipped with your ignore rules applied, with a live file count, and you can cancel until the upload starts. Zips are limited to 100 MB. The notification shows the detected runtime and offers **Open dashboard** and **Copy ID**. If the config file declares a `SUBDOMAIN`, the application answers at `https://.squareweb.app` once it starts. ### Commit changes to an existing application Open an application's action menu (right-click its card, or use its ⋯ button) and pick **Commit**. Choose whether to restart the application afterwards, then pick one or more files, or a folder. A folder is zipped with the same ignore rules and lands inside a folder of the same name in the application. *Upload* creates a new application, with a new ID. *Commit* sends files to an application that already exists and keeps its ID, domain and configuration. ### Ignore rules The extension and the [Square Cloud CLI](/en/cli-reference/installation) read the same [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) file, with the same `.gitignore` syntax and the same defaults: `node_modules`, `.git`, `.github`, `.vscode` and the lockfiles are always left out unless a `!` rule brings them back. Your `.gitignore` is not read, since it often lists files the application needs to run, like `.env`. ## Applications The side bar opens with your account: name, plan and a RAM meter for the plan's memory. Below it, every application is a card with a live status badge (**Online**, **Offline**, **Checking** while the status loads, or amber while an action you clicked is on its way), its RAM and, while it runs, its CPU. Click a card to see its ID, memory, runtime, cluster, domain and when it started. * Pointing at a card shows start or stop, restart and logs. The star next to the name marks a favorite and keeps it at the top. * **Right-click a card, or use its ⋯ button, for the full action menu**, grouped by purpose, with destructive actions last. * Past 10 applications, the list shows 10 at a time with previous and next arrows, and a filter by name, domain or ID finds any of them. * Actions that can't work are not offered: edge tools only appear for applications with a domain, and metrics only for applications with 512 MB or more. | Action | What it does | | - | - | | **Start**, **Stop**, **Restart** | Sends the action and follows the status until it changes. Starting a running application, or stopping a stopped one, is shown as information, not as an error. | | **Show logs** | Fetches the latest logs into an output channel of their own, with colors preserved. | | **Toggle realtime stream** | Opens a live feed of the application in an output channel; run it again to stop. When the server closes the connection, the extension reconnects on its own. | | **Show 24h metrics** | Prints the last 24 hours of CPU, RAM and network in 5-minute samples, plus the latest sample and the averages. Needs 512 MB or more. | | **Download snapshot** | Generates a fresh snapshot and saves the zip to the folder you choose. A large application can take a couple of minutes to generate one: the extension says so, and running the command again then saves it. | | **Restore snapshot** | Lists stored snapshots, newest first with their size, and restores the one you pick after a confirmation. | | **Environment variables** | Lists, adds, edits and deletes variables, or clears them all after a confirmation. The application reads them at startup, so restart it to apply a change. | | **Link / Unlink GitHub repository** | Links a repository and branch through the [Square Cloud GitHub App](/en/api-reference/endpoint/apps/deploy/github-app-link), so every push deploys the application. | | **Edge logs / errors / performance** | For applications with a domain: pick a range (1 hour, 6 hours, 24 hours or 7 days) and the report opens in an output channel. | | **Purge edge cache** | Clears the whole edge cache of the application after a confirmation. | | **Delete** | Asks you to type the application's name, takes a recovery snapshot and then deletes. If that snapshot is still being generated, nothing is deleted and you are asked to try again in a couple of minutes. | ## Databases The **Databases** section lists your managed databases with engine and memory. Right-click one, or use its ⋯ button, for **Start**, **Stop**, **Download TLS certificate** and **Delete** (type the name to confirm). The certificate is saved as a `.pem` file readable only by you. **Create database** is in the side bar's `...` menu, the command palette and the empty Databases section. Give it a name, an engine (`mongo`, `mysql`, `redis` or `postgres`), its memory in MB and a version. As soon as the database exists, its connection URL, password included, is copied to your clipboard, with a **Copy password** button. Square Cloud shows a new database's credentials only once. Keep them somewhere safe. ## Workspaces The **Workspaces** section shows every workspace you own or joined, with its member and application counts. Right-click one, or use its ⋯ button, to **Leave** or **Delete** it (only the owner can delete). **Create workspace** is in the side bar's `...` menu, the command palette and the empty Workspaces section. To join someone else's workspace, use **Copy My Invite Code** in the side bar's `...` menu. It copies your personal invite code: send it to the workspace owner, who uses it to add you. ## Status and problems * Platform health sits in the footer of the side bar. When Square Cloud reports trouble, a banner at the top shows its message and a link to the [status page](https://status.squarecloud.app/). * **Every problem has its own illustrated state:** no connection, a rate-limit pause with a countdown to the automatic retry, maintenance, an authorization that needs connecting again, an unexpected error, and an account without a plan. Each one offers the button that helps: **Try again**, **Connect account**, **Service status** or **See plans**. * If a refresh fails while your data is on screen, a small banner says so and keeps the last data it loaded. * The **status bar item** shows whether an account is connected, how many applications are online, and whether Square Cloud is offline, pausing requests or degraded. Hover it for the account, plan and service status; click it to refresh. ## Config file IntelliSense `squarecloud.app` and `squarecloud.config` get full editor support, with nothing else to install. * **Validation as you type:** missing required keys and duplicates, value lengths, a `MAIN` file that doesn't exist, a `MEMORY` below the minimum or above what your plan has free, invalid `SUBDOMAIN` characters, and unknown `RUNTIME` or `VERSION` values are underlined as errors. * **Autocomplete:** every key on an empty line, and after `=` the source files for `MAIN`, the runtimes for `RUNTIME`, `recommended` and `latest` for `VERSION`, `true` and `false` for `AUTORESTART`, and memory sizes for `MEMORY`. * **Quick fixes:** the light bulb on an `AUTORESTART`, `VERSION` or `RUNTIME` line sets a valid value in one click. * **Highlighting and icons** for `squarecloud.app`, `squarecloud.config` and `squarecloud.ignore`. See the [config file guide](/en/getting-started/config-file) for every key. ## From the terminal Most actions in the side bar also have a [Square Cloud CLI](/en/cli-reference/quickstart) command, handy in scripts and CI: [upload and commit](/en/cli-reference/deploy), [applications](/en/cli-reference/apps), [logs](/en/cli-reference/logs), [environment variables](/en/cli-reference/environment-variables), [snapshots](/en/cli-reference/snapshots), [edge analytics](/en/cli-reference/edge-analytics), [databases](/en/cli-reference/databases) and [workspaces](/en/cli-reference/workspaces). # Square Cloud extension for VS Code Source: https://docs.squarecloud.app/en/vscode-extension/installation Install the Square Cloud extension for VS Code or Open VSX editors, connect your account with a browser code and follow the Get Started walkthrough. The Square Cloud extension lets you deploy, manage and monitor your applications, databases and workspaces without leaving VS Code. * **Connect in the browser:** approve with an eight-character code, no key to copy or paste. * **Every application at a glance:** live status, CPU and RAM, one-click start, stop, restart and logs. * **Deploy from the editor:** upload a new application or commit to an existing one, with your [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) rules applied. * **The whole toolbox:** realtime logs, 24h metrics, snapshots, environment variables, GitHub deploys, edge analytics, databases and workspaces. * **A config file that checks itself:** autocomplete, validation and quick fixes for [`squarecloud.app`](/en/getting-started/config-file). ## Install Install **Square Cloud** from the [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=squarecloud.squarecloud), or from [Open VSX](https://open-vsx.org/extension/squarecloud/squarecloud) in editors that use it, such as VSCodium and Cursor. You can also search for "Square Cloud" in the Extensions view. Click the **Square Cloud** icon in the activity bar and press **Connect account**, or run `Square Cloud: Connect Account` from the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`). The side bar shows an eight-character code and copies it to your clipboard. Paste it on the approval page that opens in your browser and approve. The side bar confirms which account you connected, then loads your applications, databases and workspaces. Never enter a code that someone sent you. A code belongs on the approval page only when your own VS Code shows it: approving someone else's code connects their editor to your account. VS Code gets an authorization of its own: scoped to what the extension uses, valid for **90 days**, and revocable at any time under **My Account → Authentication** in the [dashboard](https://squarecloud.app/en/account/security). Your password never passes through VS Code. When the authorization expires, the extension asks you to connect again. **Other ways to connect** takes an API key created in the dashboard, for example on a machine without a browser. Either way, the credential is stored in the OS keychain through VS Code's secret storage, never in plain text on disk. Connecting or disconnecting in one VS Code window applies to every open window. ## Get Started walkthrough `Square Cloud: Get Started` opens a guided walkthrough on VS Code's Welcome page. It opens by itself the first time the extension runs without a connected account, and is also linked from the sign-in view and the side bar's `...` menu. Each step explains one idea in plain words, with an animated illustration and buttons that run the real command: 1. **Connect your account** 2. **Describe your app in `squarecloud.app`** 3. **Upload your application** 4. **Start, stop and restart** 5. **Follow logs and metrics** 6. **Back up with snapshots** 7. **Create a database** 8. **Work as a team** with workspaces 9. **Deploy on every git push** with the GitHub App 10. **Understand your traffic** with edge analytics Steps tick themselves off as you use the features. ## Languages The extension speaks the eight languages of the Square Cloud website: English, Portuguese, Spanish, German, French, Italian, Japanese and Chinese. It follows VS Code's display language, and links into the website open in the same language. ## Requirements * **VS Code 1.125** or newer. * **A Square Cloud account.** Some features (databases, workspaces, edge analytics, GitHub App linking and the snapshot list) need an active plan; the extension says so when your plan doesn't include an action. ## Privacy * The extension talks only to Square Cloud, through the official [JavaScript SDK](/en/sdks/js/client). There is no telemetry and no third-party service. * When you create a database, its connection URL is copied to your clipboard once, and the password only through **Copy password**. The extension never stores either. ## Next steps Deploy, manage applications, databases and workspaces from the side bar. Every command, the settings and how to solve common problems. Deploy and manage the same applications from the terminal. # API authentication, keys and scopes Source: https://docs.squarecloud.app/en/api-reference/authentication Authenticate to the Square Cloud API with an API key in the Authorization header, pick the scopes each endpoint needs and limit a key to specific resources. Every request to the Square Cloud API carries an API key. Create keys in your [account security settings](https://squarecloud.app/en/account/security): an account holds up to 10 of them, each with a name, and the secret of a new key is shown only once. Keys you create there don't expire. The keys the [CLI](/en/cli-reference/authentication) and the VS Code extension receive when you connect them last 90 days. ## Sending the key Send the key in the `Authorization` header. The `Bearer ` prefix is optional. ```bash theme={"system"} curl https://api.squarecloud.app/v2/users/me \ --header "Authorization: $SQUARECLOUD_API_KEY" ``` Keep the key on your server, in an environment variable. Anyone who has it can act on your account within its scopes. The use of the API is subject to the [Terms of Service](https://squarecloud.app/legal) and the [Acceptable Use Policy](https://squarecloud.app/legal/policy). 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) send the key for you and wrap every endpoint of this reference. ## Scopes Each key carries scopes, which decide what it can do. A key with full access covers every scope, including the ones added later. A call to an endpoint outside the key's scopes answers `403 MISSING_SCOPE`. Scopes can't be edited on an existing key: create a new key with the scopes you need. | Scope | Endpoints | | - | - | | `account:read` | [Account Information](/en/api-reference/endpoint/users/me) | | `apps:read` | [Application Info](/en/api-reference/endpoint/apps/info), [Status](/en/api-reference/endpoint/apps/status), [Status of all applications](/en/api-reference/endpoint/apps/status-all), [Logs](/en/api-reference/endpoint/apps/logs), [Realtime](/en/api-reference/endpoint/apps/realtime), [Metrics](/en/api-reference/endpoint/apps/metrics), [deploy history](/en/api-reference/endpoint/apps/deploy/list) and [current deploy](/en/api-reference/endpoint/apps/deploy/info), [DNS records](/en/api-reference/endpoint/apps/network/dns), [network analytics](/en/api-reference/endpoint/apps/network/analytics), [errors](/en/api-reference/endpoint/apps/network/errors), [logs](/en/api-reference/endpoint/apps/network/logs) and [performance](/en/api-reference/endpoint/apps/network/performance), [List Domains](/en/api-reference/endpoint/apps/domains), [Load Balancers](/en/api-reference/endpoint/apps/network/load-balancers) | | `apps:control` | [Start](/en/api-reference/endpoint/apps/start), [Restart](/en/api-reference/endpoint/apps/restart), [Stop](/en/api-reference/endpoint/apps/stop) | | `apps:write` | [Upload Application](/en/api-reference/endpoint/apps/upload), [Delete Application](/en/api-reference/endpoint/apps/delete), [Custom Domain](/en/api-reference/endpoint/apps/network/custom), [Purge Cache](/en/api-reference/endpoint/apps/network/purge_cache) | | `apps:deploy` | [Commit](/en/api-reference/endpoint/apps/commit), [GitHub webhook](/en/api-reference/endpoint/apps/deploy/webhooks), [link](/en/api-reference/endpoint/apps/deploy/github-app-link) and [unlink](/en/api-reference/endpoint/apps/deploy/github-app-unlink) the GitHub App | | `files:read` | [List Files](/en/api-reference/endpoint/apps/filemanager/list), [Read File](/en/api-reference/endpoint/apps/filemanager/content) | | `files:write` | [Write File](/en/api-reference/endpoint/apps/filemanager/put), [Move File](/en/api-reference/endpoint/apps/filemanager/patch), [Delete File](/en/api-reference/endpoint/apps/filemanager/delete) | | `envs:read` | [Get Environment Variables](/en/api-reference/endpoint/apps/envs/get) | | `envs:write` | [Add or edit](/en/api-reference/endpoint/apps/envs/add_n_edit), [replace](/en/api-reference/endpoint/apps/envs/overwrite) and [remove](/en/api-reference/endpoint/apps/envs/remove) environment variables | | `snapshots:read` | List snapshots of an [application](/en/api-reference/endpoint/apps/snapshots/list), a [database](/en/api-reference/endpoint/databases/snapshots/list) or the [account](/en/api-reference/endpoint/users/snapshots) | | `snapshots:write` | Create and restore snapshots of an [application](/en/api-reference/endpoint/apps/snapshots/create) or a [database](/en/api-reference/endpoint/databases/snapshots/create) | | `databases:read` | [Database Info](/en/api-reference/endpoint/databases/info), [Status](/en/api-reference/endpoint/databases/status), [Status of all databases](/en/api-reference/endpoint/databases/status-all), [Metrics](/en/api-reference/endpoint/databases/metrics) | | `databases:write` | [Create](/en/api-reference/endpoint/databases/create), [Edit](/en/api-reference/endpoint/databases/edit), [Start](/en/api-reference/endpoint/databases/start), [Stop](/en/api-reference/endpoint/databases/stop) and [Delete](/en/api-reference/endpoint/databases/delete) a database | | `databases:credentials` | [Get Certificate](/en/api-reference/endpoint/databases/credentials/get_certificate), [Reset Credentials](/en/api-reference/endpoint/databases/credentials/reset) | | `workspaces:manage` | Every [workspace](/en/api-reference/endpoint/workspace/list) endpoint, including members and shared applications | | `ai:chat` | [AI Gateway](/en/api-reference/ai-gateway) | | `blob:read`, `blob:write` | [Blob Storage](/en/blob-reference/authentication#scopes) | Each endpoint page also names its scope, right below the `Authorization` field. Some scopes reach further than their name suggests. `files:write` and `apps:deploy` run code of your choice in the application, `snapshots:read` downloads the whole application with its environment variables, `envs:read` exposes every secret of the application, `databases:credentials` gives the database password, and access granted with `workspaces:manage` keeps working after the key is revoked. Give each integration only the scopes it needs. ## Restricting a key to resources A key can also be limited to up to 30 applications and databases. A call about any other resource, or to an account-wide endpoint that can't be narrowed to those resources, answers `403 RESOURCE_NOT_ALLOWED`. Listing endpoints such as [Account Information](/en/api-reference/endpoint/users/me) return only the resources the key covers. A restricted key can't carry the `blob:read` or `blob:write` scopes, because stored files belong to the account and not to an application. Create one key for your applications and another one for Blob Storage. ## Errors | Code | HTTP | Meaning | | - | - | - | | `ACCESS_DENIED` | 401 | The key is missing, mistyped, revoked or expired, or its account no longer exists. | | `MISSING_SCOPE` | 403 | The key lacks the scope of this endpoint. | | `RESOURCE_NOT_ALLOWED` | 403 | The key is restricted to resources that don't cover this request. | | `RATE_LIMITED` | 429 | The request budget of the account or key was reached. | Every other code is in [Errors](/en/api-reference/errors). ## Protection against invalid keys To protect every account, the API temporarily blocks an IP address that insists on API keys that don't belong to any account, answering `429 RATE_LIMITED` for a short period. Valid keys in normal use are not affected. If a request gets a `401`, don't retry it in a loop: fix or replace the key. ## Next steps Base URL, a first curl call and the response format. Request budgets per plan and blocked regions. # Commit files to an application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/commit POST https://api.squarecloud.app/v2/apps/{app_id}/commit Push a single file or a .zip into an existing application with POST /v2/apps/{app_id}/commit. Files go up to 100 MB, and the app does not restart by itself. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:deploy` [scope](/en/api-reference/authentication#scopes). Commit streams a single file or a `.zip` archive into an existing application without recreating it. A `.zip` is unpacked at the destination directory, while any other file is written as-is. This makes it the fastest way to push small code changes, hotfixes, or configuration updates from a CI pipeline or deploy script. Committing does not restart the application by itself: after sending your changes, call [Restart Application](/en/api-reference/endpoint/apps/restart) so the new files take effect. For a first deployment of a new application, use [Upload Application](/en/api-reference/endpoint/apps/upload) instead, and to edit a single file in place without re-uploading, see the [File Manager endpoints](/en/api-reference/endpoint/apps/filemanager/patch). Uploads are limited to **100 MB per file**. The request body is limited to **101 MB** (a file of up to 100 MB plus form overhead): a larger request is rejected with `413 FILE_TOO_LARGE` while it is still uploading. Only the first file part is read; additional form fields are ignored. File names containing path traversal (`..`), path separators, or control characters are rejected before any change is applied. On workspace-shared applications, the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. Use FormData or NodeJS Buffer (single file or compress \[zip]) Optional. The destination directory inside the application. A `.zip` is unpacked here; any other file is placed at `path/filename`. Defaults to the application root. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_CONTENT_TYPE` | 415 | The request body is not `multipart/form-data`. | | `INVALID_FILE` | 400 | No file field was found in the form data. | | `INVALID_FILENAME` | 400 | The file name contains path separators, `..`, or control characters. | | `INVALID_PATH` | 400 | The `path` query parameter contains traversal or shell metacharacters. | | `COMMIT_FAILED` | 400 | The commit could not be applied to the application; retry, and check the archive if it repeats. | | `FILE_TOO_LARGE` | 413 | The file exceeded 100 MB or the request body exceeded 101 MB. | | `UPLOAD_BUSY` | 503 | Too many uploads are being processed right now; retry in a moment. | ## Related * CLI: [`squarecloud commit`](/en/cli-reference/deploy#squarecloud-commit) * SDKs: [`api.apps.commit()`](/en/sdks/js/commit_and_upload) (JavaScript), [`client.apps.commit()`](/en/sdks/py/commit_and_upload) (Python), [`c.Apps.Commit()`](/en/sdks/go/commit_and_upload) (Go) # Delete application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/delete DELETE https://api.squarecloud.app/v2/apps/{app_id} Permanently delete an application with DELETE /v2/apps/{app_id}. It releases its custom domain, cannot be undone and is refused while a restore runs. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:write` [scope](/en/api-reference/authentication#scopes). Deleting an application permanently removes it from the cluster it runs on, releases any custom domain attached to it (unless another of your applications still serves that hostname), and invalidates your cached project and workspace listings so the change shows up immediately in the dashboard and API. This action cannot be undone through the API. If you only want to free up resources temporarily, use [Stop Application](/en/api-reference/endpoint/apps/stop) instead, or take a [snapshot](/en/api-reference/endpoint/apps/snapshots/create) first so you can restore the application later. The request is rejected while a snapshot restore is already running for the same application. It is rate limited to 1 request every 3 seconds per user. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is currently running for this application; wait for it to finish before deleting. | | `APP_NOT_FOUND` | 404 | The application does not exist or does not belong to the caller. | | `DELETE_FAILED` | 404 | The cluster rejected the delete operation. | ## Related * CLI: [`squarecloud app delete`](/en/cli-reference/apps#squarecloud-app-delete) * SDKs: [`api.apps.delete()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.delete()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Delete()`](/en/sdks/go/managing_application) (Go) # Link GitHub App repository Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/deploy/github-app-link POST https://api.squarecloud.app/v2/apps/{app_id}/deploy/github-app Link a GitHub repository and branch to an application with POST /v2/apps/{app_id}/deploy/github-app, so every push to that branch deploys it. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:deploy` [scope](/en/api-reference/authentication#scopes). This endpoint links an application to a GitHub repository and branch through the Square Cloud GitHub App, so every push to that branch deploys the application. It is the recommended alternative to [Set GitHub Webhook](/en/api-reference/endpoint/apps/deploy/webhooks): no personal access token is stored, and each deploy shows up as a Check Run on the commit. Before calling it, connect your GitHub account to Square Cloud and install the Square Cloud GitHub App on the repository. The repository must be covered by an installation your own GitHub account holds; otherwise the request fails with `REPOSITORY_NOT_AVAILABLE`. That GitHub account also needs write (push) or admin permission on the repository: read-only access fails with `REPOSITORY_PERMISSION_REQUIRED`. It works with an API key that has the `apps:deploy` scope, and only the application owner can call it. An application holds one GitHub App link at a time, so [unlink](/en/api-reference/endpoint/apps/deploy/github-app-unlink) the current repository before linking a different one. A repository and branch can be linked to only one application on the whole platform, whoever owns it. Linking invalidates the cached response from [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info). Calls are rate limited to 3 per 60 seconds per user, shared with unlinking. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The full name of the repository, in the `owner/repository` format. The branch whose pushes deploy the application. Up to 256 characters, and it must exist in the repository with this exact name. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The linked repository. The GitHub ID of the repository. The full name of the repository. The branch that deploys the application. ```json theme={"system"} { "status": "success", "response": { "repository": { "id": 1234567, "full_name": "octocat/hello-world", "branch": "main" } } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `MISSING_REQUIRED_FIELDS` | 400 | `repositoryName` or `repositoryBranch` is missing. | | `INVALID_BRANCH_LENGTH` | 400 | The branch name is longer than 256 characters. | | `BRANCH_NOT_FOUND` | 400 | The branch does not exist in the repository. | | `GIT_ALREADY_CONFIGURED` | 400 | The application already has a GitHub App repository. Unlink it first. | | `REPOSITORY_NOT_AVAILABLE` | 403 | The Square Cloud GitHub App is not installed on the repository through your GitHub account. | | `REPOSITORY_PERMISSION_REQUIRED` | 403 | Your connected GitHub account has only read access to the repository. It needs write (push) or admin permission. | | `REPOSITORY_NOT_FOUND` | 404 | The repository does not exist or your GitHub account cannot see it. | | `APP_NOT_FOUND` | 404 | The application does not exist or you are not its owner. | | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 409 | Another application, from any account, already links this repository and branch. The message names that application only when it is yours. | | `FAILED_TO_FETCH` | 502 | GitHub did not confirm the branch. Try again. | ## Related * CLI: [`squarecloud app deploy github link`](/en/cli-reference/github-deploys#squarecloud-app-deploy-github-link) * SDKs: [`api.apps.deploys.linkGithubApp()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.link_github_app()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.LinkGithubApp()`](/en/sdks/go/deploys) (Go) # Unlink GitHub App repository Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/deploy/github-app-unlink DELETE https://api.squarecloud.app/v2/apps/{app_id}/deploy/github-app Unlink the GitHub App repository of an application with DELETE /v2/apps/{app_id}/deploy/github-app. Pushes stop deploying; running code is untouched. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:deploy` [scope](/en/api-reference/authentication#scopes). This endpoint removes the repository linked through [Link GitHub App Repository](/en/api-reference/endpoint/apps/deploy/github-app-link), so pushes to that branch stop deploying the application. The code already running is not touched, and the Square Cloud GitHub App stays installed on the repository until you remove it on GitHub. It works with an API key that has the `apps:deploy` scope, and only the application owner can call it. Unlinking invalidates the cached response from [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info). Calls are rate limited to 3 per 60 seconds per user, shared with linking. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `GIT_NOT_CONFIGURED` | 400 | The application has no GitHub App repository linked. | | `APP_NOT_FOUND` | 404 | The application does not exist or you are not its owner. | ## Related * CLI: [`squarecloud app deploy github unlink`](/en/cli-reference/github-deploys#squarecloud-app-deploy-github-unlink) * SDKs: [`api.apps.deploys.unlinkGithubApp()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.unlink_github_app()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.UnlinkGithubApp()`](/en/sdks/go/deploys) (Go) # Get current deployment Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/deploy/info GET https://api.squarecloud.app/v2/apps/{app_id}/deployments/current See how an application is wired for Git deploys with GET /v2/apps/{app_id}/deployments/current: its GitHub App repository, a legacy webhook, or both. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This endpoint reports how the application is currently wired for Git-based deploys: a GitHub App repository linkage, a legacy webhook URL, or both, depending on how the integration was set up. Use it to check the tracked repository and branch before troubleshooting a deploy, or to confirm whether a webhook still needs to be generated. The response is cached for 5 minutes per owner and application, so changes made through [Set GitHub Webhook](/en/api-reference/endpoint/apps/deploy/webhooks) may take a few minutes to show up here. On workspace-shared applications, the caller needs the `manager` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles), or ownership. To see deploy history rather than the current configuration, use [List Deployments](/en/api-reference/endpoint/apps/deploy/list). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The webhook URL for the application. ```json Webhook theme={"system"} { "status": "success", "response": { "webhook": "https://api.squarecloud.app/v2/git/webhook/69ce71f11974f2cc21d47cd0a8bcbafdaacbc3c9924b23ca40e0e2032705f6391eb89b40983338e0f2415e9331d602ccc" } } ``` ```json Integration theme={"system"} { "status": "success", "response": { "app": { "id": "00000000", "name": "Your-GitHub/Repository", "branch": "main" } } } ``` ## Related * CLI: [`squarecloud app deploy current`](/en/cli-reference/github-deploys#squarecloud-app-deploy-current) * SDKs: [`api.apps.deploys.current()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.current()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.Current()`](/en/sdks/go/deploys) (Go) # List deployments Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/deploy/list GET https://api.squarecloud.app/v2/apps/{app_id}/deployments List the recent Git deploys of an application with GET /v2/apps/{app_id}/deployments, with each state from pending to success, or the error code. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Use this endpoint to inspect what happened during recent deploys: each inner array captures one deploy attempt's lifecycle, moving through the `pending`, `clone`, `commit`, `restarting` and `success` states. A deploy that fails ends in an `error` event that carries a `code` (for example `AUTHENTICATION_REQUIRED`, `INVALID_BRANCH` or `CLONE_FAILED`) and, sometimes, a `message` with details. There is no `failed` state. Only Git deploys, from a [webhook](/en/api-reference/endpoint/apps/deploy/webhooks) or a [GitHub App](/en/api-reference/endpoint/apps/deploy/github-app-link) push, are recorded, so every event's `source` is `git`. Zip uploads and [Commit Application](/en/api-reference/endpoint/apps/commit) calls don't appear here. The deploy log comes from a short-lived cluster cache, so it only reflects the application's most recent activity and returns an empty array once nothing remains recorded. To check the currently configured Git integration instead of past deploy attempts, see [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the deploy. The state of the deploy: `pending`, `clone`, `commit`, `restarting`, `success` or `error`. The date of the event. Always `git`. Only on `error` events: why the deploy failed, for example `AUTHENTICATION_REQUIRED`, `INVALID_BRANCH` or `CLONE_FAILED`. Only on some `error` events: details about the failure. ```json theme={"system"} { "status": "success", "response": [ [ { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "pending", "date": "2026-05-28T21:47:33.608Z", "source": "git" }, { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "clone", "date": "2026-05-28T21:47:34.019Z", "source": "git" }, { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "commit", "date": "2026-05-28T21:47:36.240Z", "source": "git" }, { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "restarting", "date": "2026-05-28T21:47:37.105Z", "source": "git" }, { "id": "96b1c6931c20b1555e612d3c8cd0a7b36f0fd5c7", "state": "success", "date": "2026-05-28T21:47:41.872Z", "source": "git" } ] ] } ``` ## Related * CLI: [`squarecloud app deploy list`](/en/cli-reference/github-deploys#squarecloud-app-deploy-list) * SDKs: [`api.apps.deploys.list()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.list()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.List()`](/en/sdks/go/deploys) (Go) # Set GitHub webhook Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/deploy/webhooks POST https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook Connect an application to a GitHub repository with a personal access token via POST /v2/apps/{app_id}/deploy/webhook, or send @ to remove the webhook. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:deploy` [scope](/en/api-reference/authentication#scopes). This endpoint connects an application to a GitHub repository the classic way: generate a personal access token (`ghp_*` or the fine-grained `github_pat_*` format) and Square Cloud returns a unique webhook URL to register on that repository so pushes trigger a deploy. Sending `access_token: "@"` instead removes the existing webhook and access token from the application. Configuring or removing a webhook invalidates the cached response from [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info). Calls are rate limited to 5 per 60 seconds per user, and on workspace-shared applications the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. To review deploy attempts triggered by this webhook, use [List Deployments](/en/api-reference/endpoint/apps/deploy/list). A webhook and a [GitHub App link](/en/api-reference/endpoint/apps/deploy/github-app-link) can be configured on the same application at the same time: setting up one does not remove the other. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The access token for your GitHub repository. You can find this in your [GitHub Tokens Classic](https://github.com/settings/tokens/new) ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The URL of the webhook. ```json theme={"system"} { "status": "success", "response": { "webhook": "https://api.squarecloud.app/v2/git/webhook/" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ACCESS_TOKEN` | 400 | `access_token` is not `@` and doesn't match the `ghp_*`/`github_pat_*` GitHub token format. | ## Webhook deliveries GitHub sends each push to the webhook URL (`POST https://api.squarecloud.app/v2/git/webhook/{webhook}`). The reply is plain text (`text/plain`) that says whether a deploy was queued, so the **Recent Deliveries** list of the webhook on GitHub shows what happened to each push. Only the `429` replies with JSON (`KEEP_CALM`). A `200` is sent only after the deploy was stored in the queue: ```text theme={"system"} Deploy queued: commit 1a2b3c4 of 'main' will be deployed shortly. ``` Every other reply ends with `Nothing was deployed.` | HTTP | Meaning | | - | - | | 202 | The push is for another branch than the webhook's `?branch=`, for example: `Push received but not queued: it is for 'dev', and this webhook only deploys 'main'. Nothing was deployed.` | | 202 | `GIT_REF_NOT_SUPPORTED`: the push is for a tag or another ref outside `refs/heads/`. Tags are never deployed. | | 202 | `GIT_BRANCH_DELETED`: the push deletes a branch (`deleted: true`, or an `after` made only of zeros). | | 400 | The webhook URL or the payload is invalid, for example a `ping` event instead of a `push`. | | 404 | `Unknown webhook: it is not linked to any application (it may have been regenerated). Nothing was deployed.` | | 413 | The payload is larger than GitHub's own webhook limit. | | 415 | The webhook does not send `application/json`. Set the content type to `application/json` in the webhook settings on GitHub. | | 429 | Too many pushes in a short time (`KEEP_CALM`): each webhook accepts 1 push per 15 seconds. | | 503 | A temporary failure on our side kept the deploy from being stored. | Every `202` is answered before the rate limit, so it doesn't use up the webhook's limit of 1 push per 15 seconds. A release sent with `git push --follow-tags`, or a merged pull request whose branch GitHub deletes automatically, no longer holds back the deploy of the branch push that arrives with it. For a tag or a deleted branch, the reply starts with its code, as shown on GitHub in **Settings > Webhooks > Recent Deliveries**, in the **Response** tab: ```text theme={"system"} GIT_REF_NOT_SUPPORTED: Push received but not queued: 'refs/tags/v1.2.0' is not a branch (tag pushes are not deployed). Nothing was deployed. GIT_BRANCH_DELETED: Push received but not queued: it deletes the branch 'feature/login'. Nothing was deployed. ``` If a delivery shows `503`, redeliver it on GitHub in **Settings > Webhooks > Recent Deliveries**, or push again. ## Related * CLI: [`squarecloud app deploy webhook`](/en/cli-reference/github-deploys#squarecloud-app-deploy-webhook) * SDKs: [`api.apps.deploys.setWebhook()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.set_webhook()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.SetWebhook()`](/en/sdks/go/deploys) (Go) # List all domains Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/domains GET https://api.squarecloud.app/v2/apps/domains List every hostname across your applications with GET /v2/apps/domains: custom domains first, then the default squareweb.app subdomains, each with its app. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Use this endpoint to get a single, account-wide view of every hostname you have configured, useful for populating a domains overview page without calling [Get Application Info](/en/api-reference/endpoint/apps/info) once per application. To attach or change a custom domain on a specific application, see [Set Custom Domain](/en/api-reference/endpoint/apps/network/custom); DNS records for a domain are retrieved separately via [Get DNS Records](/en/api-reference/endpoint/apps/network/dns). This endpoint accepts either your API key or a session token (JWT) in the `Authorization` header. Authentication is required: requests without it return `401`. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The `response` array is a flattened list of every hostname across the applications you own. Custom domains come first, followed by the default `*.squareweb.app` subdomains. Applications without a web domain (e.g. workers and bots) are omitted. This list is served from the cached project list, so it does **not** count against the per-application network rate limits. The list of hostnames. The 32-character hex identifier of the application that owns the domain. The fully qualified hostname. `"subdomain"` for the default `*.squareweb.app` host; `"custom"` for an attached custom domain. ```json theme={"system"} { "status": "success", "response": [ { "app_id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d", "hostname": "example.com", "type": "custom" }, { "app_id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d", "hostname": "my-app.squareweb.app", "type": "subdomain" } ] } ``` ## Related * CLI: [`squarecloud app domains`](/en/cli-reference/domains#squarecloud-app-domains) * SDKs: [`api.apps.domains()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.domains()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Domains()`](/en/sdks/go/managing_application) (Go) # Add or edit environment variables Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/envs/add_n_edit POST https://api.squarecloud.app/v2/apps/{app_id}/envs Add or update environment variables with POST /v2/apps/{app_id}/envs. Variables left out of the body stay untouched, which suits rotating a single key. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `envs:write` [scope](/en/api-reference/authentication#scopes). Use this endpoint to add new environment variables or update specific ones without touching the rest. Existing variables that aren't included in the request body are left untouched, which makes it the safest option for incremental changes like rotating a single API key. Static applications don't support environment variables and return an error. The full set is capped at 256 variables per application, with a 1024-character limit per key and 4096 characters per value. On workspace-shared applications, the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. To replace the entire variable set instead of merging, use [Overwrite Variables](/en/api-reference/endpoint/apps/envs/overwrite). To remove specific keys, see [Remove Variables](/en/api-reference/endpoint/apps/envs/remove), and to read the current values, see [List Variables](/en/api-reference/endpoint/apps/envs/get). ## Parameters The application ID. The key and value of environment variables. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The key and value of all environment variables you defined. ```json theme={"system"} { "status": "success", "response": { "TEST": "myTest" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | The application is static; static apps don't support environment variables. | | `INVALID_ENV_CONTENT` | 400 | `envs` is missing, not an object, or an array. | | `TOO_MANY_ENV_VARS` | 400 | The merged set would exceed 256 environment variables. | | `ENV_NAME_TOO_LONG` | 400 | A variable key exceeds 1024 characters. | | `ENV_CONTENT_TOO_LONG` | 400 | A variable value exceeds 4096 characters. | ## Related * CLI: [`squarecloud app env set`](/en/cli-reference/environment-variables#squarecloud-app-env-set) * SDKs: [`api.apps.envs.set()`](/en/sdks/js/environment_variables) (JavaScript), [`client.apps.envs.set()`](/en/sdks/py/environment_variables) (Python), [`c.Apps.Envs.Set()`](/en/sdks/go/environment_variables) (Go) # List environment variables Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/envs/get GET https://api.squarecloud.app/v2/apps/{app_id}/envs Read an application's environment variables as a key-value object with GET /v2/apps/{app_id}/envs. Returns an empty object when none are set. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `envs:read` [scope](/en/api-reference/authentication#scopes). Returns the application's current environment variables as a flat key-value object, read directly from its `.env` file on the cluster. If no variables have been set yet, the response is a success with an empty object rather than an error. Static applications don't support environment variables and return an error instead. On workspace-shared applications, the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. To add or update variables, use [Add/Edit Variables](/en/api-reference/endpoint/apps/envs/add_n_edit); to replace the whole set, see [Overwrite Variables](/en/api-reference/endpoint/apps/envs/overwrite). ## Parameters The application ID. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The key and value of all environment variables you defined. ```json theme={"system"} { "status": "success", "response": { "TEST": "myTest" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | The application is static; static apps don't support environment variables. | | `READ_FAILED` | 400 | The `.env` file could not be read from the cluster. | ## Related * CLI: [`squarecloud app env list`](/en/cli-reference/environment-variables#squarecloud-app-env-list) * SDKs: [`api.apps.envs.get()`](/en/sdks/js/environment_variables) (JavaScript), [`client.apps.envs.get()`](/en/sdks/py/environment_variables) (Python), [`c.Apps.Envs.Get()`](/en/sdks/go/environment_variables) (Go) # Replace all environment variables Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/envs/overwrite PUT https://api.squarecloud.app/v2/apps/{app_id}/envs Replace an application's whole environment with PUT /v2/apps/{app_id}/envs: variables not in the body are deleted, and an empty envs object wipes all. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `envs:write` [scope](/en/api-reference/authentication#scopes). Overwrite replaces the application's entire environment with exactly the variables you send: anything already set that isn't included in the request body is deleted. Sending an empty `envs` object wipes every variable, which makes this the endpoint to use for a full reset rather than an incremental change. The same limits as other environment variable endpoints apply: up to 256 variables per application, 1024 characters per key, 4096 per value. Static applications aren't supported and return an error, and on workspace-shared applications the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. If you only need to change a few variables without touching the rest, use [Add/Edit Variables](/en/api-reference/endpoint/apps/envs/add_n_edit) instead, or [Remove Variables](/en/api-reference/endpoint/apps/envs/remove) to delete specific keys. ## Parameters The application ID. The key and value variables you want on the environment. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The key and value of all environment variables you defined. ```json theme={"system"} { "status": "success", "response": { "TEST": "overwriteTest" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | The application is static; static apps don't support environment variables. | | `INVALID_ENV_CONTENT` | 400 | `envs` is missing, not an object, or an array. | | `TOO_MANY_ENV_VARS` | 400 | The new set would exceed 256 environment variables. | | `ENV_NAME_TOO_LONG` | 400 | A variable key exceeds 1024 characters. | | `ENV_CONTENT_TOO_LONG` | 400 | A variable value exceeds 4096 characters. | ## Related * CLI: [`squarecloud app env replace`](/en/cli-reference/environment-variables#squarecloud-app-env-replace) * SDKs: [`api.apps.envs.replace()`](/en/sdks/js/environment_variables) (JavaScript), [`client.apps.envs.replace()`](/en/sdks/py/environment_variables) (Python), [`c.Apps.Envs.Replace()`](/en/sdks/go/environment_variables) (Go) # Remove environment variables Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/envs/remove DELETE https://api.squarecloud.app/v2/apps/{app_id}/envs Delete one or more environment variables by key with DELETE /v2/apps/{app_id}/envs. Missing keys are ignored and the remaining variables are returned. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `envs:write` [scope](/en/api-reference/authentication#scopes). Deletes one or more environment variables by key, leaving every other variable untouched. Keys that don't currently exist are silently ignored, so it's safe to call with a list that mixes valid and already-removed names. Static applications don't support environment variables and return an error. On workspace-shared applications, the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. The response returns the full set of remaining variables, so you can confirm the removal without a separate [List Variables](/en/api-reference/endpoint/apps/envs/get) call. To add variables back or replace the whole set, see [Add/Edit Variables](/en/api-reference/endpoint/apps/envs/add_n_edit) and [Overwrite Variables](/en/api-reference/endpoint/apps/envs/overwrite). ## Parameters The application ID. The array containing the keys to remove. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The key and value of all remaining environment variables. ```json theme={"system"} { "status": "success", "response": { "REMAINING": "secret" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | The application is static; static apps don't support environment variables. | | `INVALID_ENV_CONTENT` | 400 | `envs` is missing, not an array, or empty. | | `ENV_NAME_TOO_LONG` | 400 | A key in `envs` is not a string or exceeds 1024 characters. | ## Related * CLI: [`squarecloud app env remove`](/en/cli-reference/environment-variables#squarecloud-app-env-remove) * SDKs: [`api.apps.envs.delete()`](/en/sdks/js/environment_variables) (JavaScript), [`client.apps.envs.delete()`](/en/sdks/py/environment_variables) (Python), [`c.Apps.Envs.Delete()`](/en/sdks/go/environment_variables) (Go) # Read an application file Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/filemanager/content GET https://api.squarecloud.app/v2/apps/{app_id}/files/content Read one file of up to 10 MB from an application with GET /v2/apps/{app_id}/files/content. Send encoding=base64, since the Buffer format is deprecated. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `files:read` [scope](/en/api-reference/authentication#scopes). Read File returns a single file inside a running application as JSON. Send `?encoding=base64` to get the file as a base64 string. It is meant for inspecting or downloading individual files (configs, logs, small assets) of up to 10 MB through the API, not for bulk transfers: use [Create Snapshot](/en/api-reference/endpoint/apps/snapshots/create) to pull a full copy of the application instead. Without `encoding`, the response is the legacy `{ type: "Buffer", data: number[] }` object. This format is **deprecated since September 27, 2026** and will be removed on **March 27, 2027**, when base64 becomes the default. Until then, legacy responses carry the `Deprecation` and `Sunset` headers. Send `?encoding=base64` in every request. To see what is available before reading, call [List Files](/en/api-reference/endpoint/apps/filemanager/list) first. To write a file back, use [Create/Modify File](/en/api-reference/endpoint/apps/filemanager/put), which takes the same base64 content with `encoding: "base64"`. On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles), and members without the restricted-files permission cannot read `.env` or `.env.production`, the request is rejected with `PERMISSION_DENIED` before the file is touched. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The path to the file you want to read, relative to the root of your application. Up to 256 characters. Send `base64` to receive the file as a base64 string. Any other value answers `INVALID_ENCODING`. Without it, the response uses the deprecated Buffer format. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the file. Always `base64`. The file, base64-encoded. Decode `data` to get the file's bytes: ```javascript Node.js theme={"system"} const bytes = Buffer.from(data, "base64"); ``` ```javascript Browser theme={"system"} const bytes = Uint8Array.fromBase64(data); // Older browsers: Uint8Array.from(atob(data), (c) => c.charCodeAt(0)) ``` ```python Python theme={"system"} import base64 content = base64.b64decode(data) ``` ```json theme={"system"} { "status": "success", "response": { "encoding": "base64", "data": "Y29uc29sZS5sb2coIkhlbGxvLCBTcXVhcmUgQ2xvdWQhIik7Cg==" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_PATH` | 400 | The `path` query parameter failed validation (traversal, invalid characters, or longer than 256 characters). | | `INVALID_ENCODING` | 400 | `encoding` has a value other than `base64`. | | `PERMISSION_DENIED` | 403 | The caller lacks the workspace permission to read a restricted file (`.env`, `.env.production`). | | `FILE_NOT_FOUND` | 404 | No file exists at the given path. | | `FILE_TOO_LARGE` | 413 | The file is larger than 10 MB, the most the file manager reads. | ## Related * CLI: [`squarecloud app file read`](/en/cli-reference/files#squarecloud-app-file-read) * SDKs: [`api.apps.files.read()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.read()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.Read()`](/en/sdks/go/managing_files) (Go) # Delete an application file Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/filemanager/delete DELETE https://api.squarecloud.app/v2/apps/{app_id}/files Delete a single file from an application by path with DELETE /v2/apps/{app_id}/files. It takes effect at once, without restarting or redeploying the app. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `files:write` [scope](/en/api-reference/authentication#scopes). Delete File removes a single file from a running application by path, without touching the rest of the file tree or restarting the process. Use it for cleaning up generated files, old logs, or stray uploads without redeploying. The deletion happens directly on the application's storage on the cluster node, so it takes effect immediately; there is no undo short of restoring from a prior [snapshot](/en/api-reference/endpoint/apps/snapshots/restore). To remove a whole application instead of one file, see [Delete Application](/en/api-reference/endpoint/apps/delete). To rename or move a file instead of deleting it, use [Move File](/en/api-reference/endpoint/apps/filemanager/patch). On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). Members without the restricted-files permission cannot delete files on the excluded list (such as `.env` or `.env.production`), the request is rejected with `PERMISSION_DENIED` first. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The path of the file to delete, up to 256 characters. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_PATH` | 400 | The `path` field failed validation (traversal, invalid characters, or longer than 256 characters). | | `DELETE_FAILED` | 400 | The cluster could not delete the file. | | `PERMISSION_DENIED` | 403 | The caller lacks the workspace permission to delete a restricted file. | ## Related * CLI: [`squarecloud app file delete`](/en/cli-reference/files#squarecloud-app-file-delete) * SDKs: [`api.apps.files.delete()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.delete()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.Delete()`](/en/sdks/go/managing_files) (Go) # List application files Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/filemanager/list GET https://api.squarecloud.app/v2/apps/{app_id}/files List the files and directories at a path inside an application with GET /v2/apps/{app_id}/files, each with its type, size and last-modified time. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `files:read` [scope](/en/api-reference/authentication#scopes). List Files returns the files and directories at a given path inside an application, each entry carrying its type, size, and last-modified time. Use it to browse an application's storage from a dashboard or script before reading, writing, or deleting a specific file. The listing reflects the application's storage on its cluster node at request time; it is not cached. Pair it with [Read File](/en/api-reference/endpoint/apps/filemanager/content) to fetch a file's contents, or [Create/Modify File](/en/api-reference/endpoint/apps/filemanager/put) to write one. Omitting `path` lists the application root. On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles), and members without the restricted-files permission never see `.env` or `.env.production` in the results, those entries are filtered out of the response rather than erroring. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The path of the directory whose files you want to list, up to 256 characters. Default is the root directory. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The list of files and directories in the specified path. The type of the entry. Can be `file` or `directory`. The name of the file or directory. The size of the file in bytes. For directories, it is 0. The last modified timestamp of the file or directory in milliseconds since the epoch. ```json theme={"system"} { "status": "success", "response": [ { "type": "file", "name": ".env", "size": 86, "lastModified": 1676168978000 }, { "type": "file", "name": ".gitignore", "size": 8, "lastModified": 1675125328000 }, { "type": "file", "name": "index.js", "size": 614, "lastModified": 1676168350000 }, { "type": "file", "name": "squarecloud.app", "size": 65, "lastModified": 1676169188000 }, { "type": "directory", "name": "src", "lastModified": 1676155738000 } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_PATH` | 400 | The `path` query parameter failed validation (traversal, invalid characters, or longer than 256 characters), or the cluster could not read the directory. | | `BLOCKED_PATH` | 403 | The requested path is inside a blocked directory. | | `FILE_NOT_FOUND` | 404 | The directory does not exist. | ## Related * CLI: [`squarecloud app file list`](/en/cli-reference/files#squarecloud-app-file-list) * SDKs: [`api.apps.files.list()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.list()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.List()`](/en/sdks/go/managing_files) (Go) # Move or rename an application file Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/filemanager/patch PATCH https://api.squarecloud.app/v2/apps/{app_id}/files Move or rename a file inside an application with PATCH /v2/apps/{app_id}/files, from path to to, without re-uploading it or restarting the app. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `files:write` [scope](/en/api-reference/authentication#scopes). Move File renames or relocates a single file inside an application's storage, from `path` to `to`, without downloading and re-uploading its contents. Use it to reorganize a directory structure or rename a config file in place. `path` and `to` must both pass path validation and must be different, sending the same value for both is rejected with `INVALID_PATH`. This only moves the file on the running application's storage; it does not restart the process, so a running process reading the old path will not see the change until it reloads or the app is [restarted](/en/api-reference/endpoint/apps/restart). To delete a file instead of moving it, see [Delete File](/en/api-reference/endpoint/apps/filemanager/delete). On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). The restricted-files check applies to both the source and destination names, so a member without that permission cannot rename an allowed file into a protected name like `.env` to plant or overwrite it. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The path of the file to move, up to 256 characters. The path to move the file to, up to 256 characters. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_PATH` | 400 | `path` or `to` failed validation, or `path` and `to` were identical. | | `RENAME_FAILED` | 400 | The cluster could not rename the file. | | `PERMISSION_DENIED` | 403 | The caller lacks the workspace permission to rename a restricted file, checked on both the source and destination names. | ## Related * CLI: [`squarecloud app file move`](/en/cli-reference/files#squarecloud-app-file-move) * SDKs: [`api.apps.files.move()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.move()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.Move()`](/en/sdks/go/managing_files) (Go) # Create or update an application file Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/filemanager/put PUT https://api.squarecloud.app/v2/apps/{app_id}/files Create or overwrite a file in an application with PUT /v2/apps/{app_id}/files. Send base64 content for binary files, up to 10 MB each, with no restart. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `files:write` [scope](/en/api-reference/authentication#scopes). Create/Modify File writes `content` to `path` inside a running application, creating the file if it does not exist or overwriting it if it does. For binary files, send `content` base64-encoded together with `encoding: "base64"`, the recommended format. `content` also accepts a UTF-8 string for text files, a plain array of byte values (`[104, 105]`) or a `{ type: "Buffer", data: number[] }` object. An empty `content` (`""` or `[]`) writes an empty file. Each write takes up to 10 MB, measured on the decoded bytes. Writes are rate limited to 10 requests every 5 seconds per user. Use it for small, targeted edits, such as tweaking a config value or dropping in a generated file, without re-uploading the whole application; for bulk changes or a `.zip`, use [Commit Application](/en/api-reference/endpoint/apps/commit) instead. Writing to `squarecloud.app` or `squarecloud.config` is treated specially: the platform parses it as the application's config (display name, description, memory, autorestart, subdomain) and validates each field, an invalid value returns a specific error code (for example `INVALID_MEMORY` or `INVALID_SUBDOMAIN`) instead of writing the file. These config rewrites are rate limited to 1 request every 15 seconds per user. On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles), and members without the restricted-files permission are blocked from writing to excluded paths like `.env`. Like other file manager routes, this does not restart the application, call [Restart Application](/en/api-reference/endpoint/apps/restart) to apply changes that need a fresh process. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The path where the file should be created, up to 256 characters. Example: /test.txt The content of the file to be created: base64 when `encoding` is `base64`, otherwise a UTF-8 string or an array of bytes. Set to `base64` when `content` is the file base64-encoded. Recommended for binary files. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_PATH` | 400 | The `path` field failed validation (traversal, invalid characters, or longer than 256 characters). | | `INVALID_CONTENT` | 400 | `content` is missing, not one of the accepted shapes, or not valid base64 when `encoding` is `base64`. | | `INVALID_DISPLAY_NAME` / `INVALID_DESCRIPTION` / `INVALID_MEMORY` / `INVALID_AUTORESTART` / `INVALID_SUBDOMAIN` | 400 | A field parsed from a `squarecloud.app`/`squarecloud.config` write failed validation. | | `CANNOT_SET_SUBDOMAIN` | 400 | The parsed config tried to set a subdomain the plan or account cannot use. | | `BLOCKED_PATH` | 403 | The caller lacks the workspace permission to write to a restricted file. | | `FILE_TOO_LARGE` | 413 | The decoded `content` is larger than 10 MB; use Commit Application for bigger files. | | `KEEP_CALM` | 429 | More than 10 writes in 5 seconds; wait a few seconds and retry. | | `SAVE_FAILED` | 500 | The parsed config update could not be persisted. | ## Related * CLI: [`squarecloud app file write`](/en/cli-reference/files#squarecloud-app-file-write) * SDKs: [`api.apps.files.write()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.write()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.Write()`](/en/sdks/go/managing_files) (Go) # Get application info Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/info GET https://api.squarecloud.app/v2/apps/{app_id} Get an application's metadata with GET /v2/apps/{app_id}: name, owner, cluster, allocated RAM, language and domain. Works for workspace-shared apps too. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This endpoint returns an application's identity and configuration: its name, owner, cluster, allocated RAM, programming language, and DNS setup. It is the endpoint to call when you need to look up an application's metadata before acting on it, for example to confirm which cluster it lives on or which subdomain it is reachable at. Access is scoped to the caller: if the application belongs to a workspace you are a member of, it is returned automatically without any extra parameter. For live resource usage instead of static metadata, see [Get Application Status](/en/api-reference/endpoint/apps/status); for configured hostnames across your whole account, see [List Domains](/en/api-reference/endpoint/apps/domains). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The application's name. The application's ID. The ID of the application owner. The application's cluster. The application's RAM usage in MB. The application's programming language. The application's domain (null if not applicable). Custom information about the application (null if not applicable). The application's creation date. ```json Response theme={"system"} { "status": "success", "response": { "name": "Best bot forever", "id": "64d0c750212742ca8704fb458c9771af", "owner": "3133971456989594464", "cluster": "nasa-cluster", "ram": 1024, "language": "rust", "domain": null, "custom": null, "created_at": "2023-02-20T14:30:00Z" } } ``` ## Related * CLI: [`squarecloud app info`](/en/cli-reference/apps#squarecloud-app-info) * SDKs: [`api.apps.get()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.get()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Get()`](/en/sdks/go/managing_application) (Go) # Get application logs Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/logs GET https://api.squarecloud.app/v2/apps/{app_id}/logs Get a point-in-time snapshot of an application's recent stdout and stderr with GET /v2/apps/{app_id}/logs. For live logs, use the realtime SSE stream. This endpoint is strictly rate limited. Exceeding **any** of the limits returns `429 Too Many Requests`: * **1 request every 5 seconds** per user, per application. * **20 requests every 10 seconds** per user across all applications, followed by a **short cooldown**. When you receive a `429`, stop polling that application and wait for the cooldown to end before retrying. Use this endpoint only for a **point-in-time snapshot** of logs (opening the logs tab or a manual refresh). For **live, continuous logs**, use the [Real-time Logs](/en/api-reference/endpoint/apps/realtime) (SSE) endpoint, which streams logs in real time without hitting this rate limit. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This endpoint fetches the application's most recent stdout/stderr buffer directly from the cluster: it is a short-lived snapshot, not a stream. stdout and stderr are returned concatenated in the order they were written, with no per-line distinction between the two, unlike the [Real-time Logs](/en/api-reference/endpoint/apps/realtime) event which prefixes each line with its stream id. Use it when you need a one-off look at recent output, for example rendering the logs tab on page load or after a manual refresh button. It returns `404` when the application is offline, has never been deployed, or the cluster returns a transient error. Workspace members with access to the application can call it the same way the owner does. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The latest logs from the application. ```json theme={"system"} { "status": "success", "response": { "logs": "Working!" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `LOGS_UNAVAILABLE` | 404 | The logs could not be returned: the application is offline, has never been deployed, or a transient error occurred. Retry shortly. | ## Related * CLI: [`squarecloud app logs`](/en/cli-reference/logs#squarecloud-app-logs) * SDKs: [`api.apps.logs()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.logs()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Logs()`](/en/sdks/go/managing_application) (Go) # Get application metrics Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/metrics GET https://api.squarecloud.app/v2/apps/{app_id}/metrics Get an application's CPU, RAM and network history with GET /v2/apps/{app_id}/metrics: up to 288 points over the last 24 hours, one every 5 minutes. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This endpoint returns historical resource usage rather than the current snapshot: up to 288 data points covering the last 24 hours, sampled every 5 minutes, for CPU, RAM, and network. Points come newest first. Use it to render a usage chart or to spot trends over time; for the application's current live numbers, use [Get Application Status](/en/api-reference/endpoint/apps/status) or the `status` events on [Real-time Logs](/en/api-reference/endpoint/apps/realtime) instead. Metrics collection requires at least **512 MB of RAM** allocated to the application; smaller applications return `METRICS_NOT_SUPPORTED`. Results are cached for 2.5 minutes per (owner, application), and the endpoint is rate limited to 10 requests every 5 seconds per user, with a short block once that cap is hit. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The date in ISO format. The CPU usage percentage at the given point in time. The RAM usage in MB at the given point in time. An array representing total network used. First the input, second the output. ```json theme={"system"} { "status": "success", "response": [ { "date": "2025-08-13T12:55:01.348Z", "cpu": 0.45, "ram": 111.27, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:50:01.349Z", "cpu": 0.45, "ram": 111.22, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:45:01.350Z", "cpu": 0.58, "ram": 111.36, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:40:01.348Z", "cpu": 0.43, "ram": 118.44, "net": [ 16834, 126 ] } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `METRICS_NOT_SUPPORTED` | 400 | The application has less than 512 MB of RAM allocated and does not collect metrics. | ## Related * CLI: [`squarecloud app metrics`](/en/cli-reference/status-and-metrics#squarecloud-app-metrics) * SDKs: [`api.apps.metrics()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.metrics()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Metrics()`](/en/sdks/go/managing_application) (Go) # Get website traffic analytics Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/analytics GET https://api.squarecloud.app/v2/apps/{app_id}/network/analytics Get edge traffic analytics for an application's domains with GET /v2/apps/{app_id}/network/analytics: requests, bandwidth, visitors and breakdowns. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Analytics aggregates Cloudflare edge traffic for the application's default `squareweb.app` domain and any attached custom domain: request counts, bandwidth, visitor counts, and breakdowns by country, device, OS, browser, protocol, method, path, referer, and client network. Use it to build traffic dashboards or spot unusual patterns without pulling raw request logs. Results are cached in 5-minute buckets, so polling the same window repeatedly is cheap. Cache misses share one limit of 20 requests per 60 seconds per application owner, across the analytics, errors, logs and performance endpoints. Cached responses do not count. During platform-wide busy periods the endpoint may return the most recent cached data for the requested window instead. The maximum lookback is 7 days, and the effective start is clamped to the application's creation date. Unlike [Network Logs](/en/api-reference/endpoint/apps/network/logs) and [Network Performance](/en/api-reference/endpoint/apps/network/performance), this endpoint is available on every plan, not just Pro and Enterprise. For error-focused traffic instead of overall traffic, see [Network Errors](/en/api-reference/endpoint/apps/network/errors). To purge cached edge responses after a deploy, see [Purge Cache](/en/api-reference/endpoint/apps/network/purge_cache). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ISO 8601 start timestamp for the analysis window. The maximum retention window is 7 days; the start is clamped to the application's creation date. ISO 8601 end timestamp. Must be after `start`. ### Drill-down filters Optional filters that narrow **every** breakdown to the matching traffic. Feed back the exact `type` value returned by the corresponding breakdown in a previous response. Filters combine (AND). A single client country (2-character code), as returned in the `countries` breakdown. A single client IP (exact IPv4/IPv6 match), as returned in the `ips` breakdown. Request paths starting with this prefix (e.g. `/api` covers `/api/*`). Max 256 chars. A single edge response status code (3 digits), as returned in the `status_codes` breakdown. A single client OS, as returned in the `os` breakdown. A single client browser, as returned in the `browsers` breakdown. A single HTTP protocol, as returned in the `protocols` breakdown. A single referer host, as returned in the `referers` breakdown (`Direct` = no referer). A single client network, with the exact `type` value the `providers` breakdown returns, for example `GOOGLE (15169)`. A bare ASN number or `SQUARE-CLOUD-PLATFORM` also work. Any other value answers `INVALID_FILTER`. A single response content type, as returned in the `content_types` breakdown (`Unknown` = unclassified). A single verified-bot category, as returned in the `bots` breakdown (`Unverified` = regular non-bot traffic). ## Response This route can send a response in a compressed format, optimizing data transmission. Indicates whether the call was successful: `success` if it was, `error` if not. Each breakdown is an array of buckets. `type` identifies the dimension, `visits` is unique visitors, `requests` is the request count, `bytes` is the response bytes served, and `date` is the 15-minute window start. The `ips`, `status_codes`, `bots`, and `content_types` breakdowns are window totals (top-N over the whole window) and carry **no** `date` field. Returns an empty object (`{}`) when the requested window starts before the application's creation date. ```json theme={"system"} { "status": "success", "response": { "visits": [ { "visits": 1024, "requests": 1247, "bytes": 8421000, "date": "2026-05-21T10:00:00Z" } ], "countries": [ { "type": "BR", "visits": 612, "requests": 743, "bytes": 5012000, "date": "2026-05-21T10:00:00Z" } ], "devices": [ { "type": "desktop", "visits": 820, "requests": 998, "bytes": 6700000, "date": "2026-05-21T10:00:00Z" } ], "os": [ { "type": "Windows", "visits": 540, "requests": 651, "bytes": 4400000, "date": "2026-05-21T10:00:00Z" } ], "browsers": [ { "type": "Chrome", "visits": 720, "requests": 870, "bytes": 5800000, "date": "2026-05-21T10:00:00Z" } ], "protocols": [ { "type": "HTTP/2", "visits": 900, "requests": 1100, "bytes": 7400000, "date": "2026-05-21T10:00:00Z" } ], "methods": [ { "type": "GET", "visits": 850, "requests": 1020, "bytes": 6900000, "date": "2026-05-21T10:00:00Z" } ], "paths": [ { "type": "/", "visits": 410, "requests": 498, "bytes": 3320000, "date": "2026-05-21T10:00:00Z" } ], "referers": [ { "type": "Direct", "visits": 380, "requests": 462, "bytes": 3100000, "date": "2026-05-21T10:00:00Z" } ], "providers": [ { "type": "GOOGLE (15169)", "visits": 210, "requests": 254, "bytes": 1700000, "date": "2026-05-21T10:00:00Z" } ], "ips": [ { "type": "203.0.113.45", "visits": 40, "requests": 3120, "bytes": 2100000 } ], "status_codes": [ { "type": "200", "visits": 950, "requests": 1180, "bytes": 8100000 } ], "bots": [ { "type": "Search Engine Crawler", "visits": 0, "requests": 84, "bytes": 410000 } ], "content_types": [ { "type": "json", "visits": 310, "requests": 720, "bytes": 4200000 } ] } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_TIME_RANGE` | 400 | `start`/`end` are missing, malformed, or invert the time range. | | `INVALID_FILTER` | 400 | A drill-down filter does not match its expected format. | | `RATE_LIMITED` | 429 | The shared limit of cache misses was reached. Wait and retry. | | `UNABLE_TO_FETCH_ANALYTICS` | 500 | Failed to fetch analytics from the edge provider. | | `ANALYTICS_BUSY` | 503 | Edge analytics are temporarily busy. Try again in a minute. | ## Related * CLI: [`squarecloud app network analytics`](/en/cli-reference/edge-analytics#squarecloud-app-network-analytics) * SDKs: [`api.apps.network.analytics()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.analytics()`](/en/sdks/py/network) (Python), [`c.Apps.Network.Analytics()`](/en/sdks/go/network) (Go) # Set custom domain Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/custom POST https://api.squarecloud.app/v2/apps/{app_id}/network/custom Attach a custom domain to an application with POST /v2/apps/{app_id}/network/custom, or send @ to remove it. Available on Standard, Pro and Enterprise. **Is necessary to have at least the [Standard plan](https://squarecloud.app/en/pricing) to use this route.** The same account may attach one domain to multiple applications (load balancing): up to 2 applications on Standard, 5 on Pro, and 10 on Enterprise. See [List Load Balancers](/en/api-reference/endpoint/apps/network/load-balancers). The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:write` [scope](/en/api-reference/authentication#scopes). Replacing an existing custom domain releases the previous hostname at the edge before attaching the new one, unless another application on the same account still points at it. The same validation runs whether attaching or removing (`custom: "@"`): on a workspace-shared application, the caller needs the workspace `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles) or ownership. A domain can only be claimed by one account at a time: attaching a hostname already held by another account returns `DOMAIN_ALREADY_EXISTS`. To see every hostname configured across your applications, see [List Domains](/en/api-reference/endpoint/apps/domains). Once attached, fetch the required validation records with [Get DNS Records](/en/api-reference/endpoint/apps/network/dns). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The fully qualified domain to attach, or `@` to remove the application's current custom domain. It cannot be a Square Cloud domain (`squareweb.app`, `squarecloud.app`, ...). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. On failure, the response includes an error `code`: | Status | Code | Meaning | | - | - | - | | `400` | `INVALID_DOMAIN` | The domain is not a valid fully qualified domain name. | | `400` | `RESERVED_DOMAIN` | Square Cloud domains cannot be used as a custom domain. | | `403` | `UPGRADE_REQUIRED` | The active plan does not include custom domains (Standard, Pro, or Enterprise required). | | `403` | `LOAD_BALANCER_LIMIT_REACHED` | The plan's limit of applications on this domain was reached. | | `409` | `DOMAIN_ALREADY_EXISTS` | The domain is already attached to an application owned by another account. | | `502` | `DNS_FAILED` | The domain attachment failed at the edge provider. | ```json theme={"system"} { "status": "success" } ``` ## Related * CLI: [`squarecloud app network domain`](/en/cli-reference/domains#squarecloud-app-network-domain) * SDKs: [`api.apps.network.setDomain()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.set_domain()`](/en/sdks/py/network) (Python), [`c.Apps.Network.SetDomain()`](/en/sdks/go/network) (Go) # Get custom domain DNS records Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/dns GET https://api.squarecloud.app/v2/apps/{app_id}/network/dns Get the TXT and CNAME records a custom domain needs for validation and SSL with GET /v2/apps/{app_id}/network/dns, to add at your domain registrar. **A custom domain must already be attached to the application to use this route.** Custom domains are available on the [Standard plan](https://squarecloud.app/en/pricing) and above. This route is rate limited to 3 requests every 10 seconds. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). These are the records Cloudflare needs to validate ownership of the custom domain and issue its SSL certificate: typically one or two `txt` records (domain and ACME challenge validation) plus a `cname` record pointing at `cname.squareweb.app`, which is what actually routes traffic to the application. Add them at your domain registrar; Cloudflare polls for them automatically, no re-request needed. The response is cached for 30 seconds per owner and application, and the same cache backs the Cubic AI agent when it inspects an application's domain setup. If the custom hostname has not been registered at the edge yet, the response is an empty array rather than an error. To attach a custom domain in the first place, see [Set Custom Domain](/en/api-reference/endpoint/apps/network/custom). See also [List Domains](/en/api-reference/endpoint/apps/domains) for every hostname configured across your applications. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The type of the DNS record. The name of the DNS record. The value of the DNS record. The status of the DNS record. It can be `pending_validation`, `pending` or `active`. ```json theme={"system"} { "status": "success", "response": [ { "type": "txt", "name": "_acme-challenge.example.com", "value": "hmo-jMx_KCWQU5CWG6xmrkI4AOZOJXlQtjEtc7zI1PA", "status": "pending_validation" }, { "type": "cname", "name": "example.com", "value": "cname.squareweb.app", "status": "pending" } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `NO_CUSTOM_DOMAIN` | 400 | The application does not have a custom domain attached. | ## Related * CLI: [`squarecloud app network dns`](/en/cli-reference/domains#squarecloud-app-network-dns) * SDKs: [`api.apps.network.dns()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.dns()`](/en/sdks/py/network) (Python), [`c.Apps.Network.DNS()`](/en/sdks/go/network) (Go) # Get edge error breakdown Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/errors GET https://api.squarecloud.app/v2/apps/{app_id}/network/errors Get edge error counts by status, path, method and time with GET /v2/apps/{app_id}/network/errors. Only 5xx by default; include_4xx=true adds 4xx. Returns aggregated edge error counts for the application over a time window, grouped by status code, time bucket, request path and HTTP method. By default only 5xx responses are included; pass `include_4xx=true` to also count 4xx responses. Cache misses share one limit of 20 requests per 60 seconds per application owner, across the analytics, errors, logs and performance endpoints. Cached responses do not count. During platform-wide busy periods the endpoint may return the most recent cached data for the requested window instead. Returns an empty breakdown when there are no matching errors or when the window precedes the application's creation date. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Because 4xx errors include client-caused hits like scanner probes and expired links, they are excluded by default; enable `include_4xx=true` only when you specifically need that noise, for example while auditing bot traffic. 5xx codes reflect problems at the edge or the application itself, so they are always included. This endpoint is available on every plan, the same as [Network Analytics](/en/api-reference/endpoint/apps/network/analytics). If you need per-request detail instead of aggregated counts, see [Network Logs](/en/api-reference/endpoint/apps/network/logs) (Pro and Enterprise only). For latency instead of error rate, see [Network Performance](/en/api-reference/endpoint/apps/network/performance). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ISO 8601 start timestamp for the analysis window. ISO 8601 end timestamp. Must be after `start`. Whether to include 4xx responses alongside 5xx errors. Accepts `true` or `false`. Defaults to `false`. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. Aggregated error breakdown for the window. High-level totals for the window. Total number of error responses in the window. Totals split by HTTP status class. Total 4xx responses (only populated when `include_4xx=true`). Total 5xx responses. Number of requests grouped by each individual HTTP status code observed. HTTP status code (e.g. `502`, `504`). Total requests that returned this status code. Time-bucketed counts across the analysis window. Bucket start timestamp in ISO 8601 format. Object keyed by HTTP status code with the count observed in this bucket. Total errors observed in this bucket. Paths that produced the most errors during the window. Request path. HTTP method. Total errors for this path/method. Counts per HTTP status code observed for this path/method. Aggregated error totals grouped by HTTP method. HTTP method. Total errors for this method. Counts per HTTP status code observed for this method. ```json theme={"system"} { "status": "success", "response": { "summary": { "total": 42, "by_class": { "4xx": 0, "5xx": 42 } }, "by_status": [ { "status": 502, "requests": 30 }, { "status": 504, "requests": 12 } ], "timeseries": [ { "date": "2025-12-01T12:00:00.000Z", "buckets": { "502": 5, "504": 2 }, "total": 7 } ], "top_paths": [ { "path": "/api/users", "method": "GET", "total": 18, "by_status": { "502": 15, "504": 3 } } ], "by_method": [ { "method": "GET", "total": 30, "by_status": { "502": 22, "504": 8 } } ] } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_TIME_RANGE` | 400 | `start`/`end` are missing, malformed, or invert the time range. | | `RATE_LIMITED` | 429 | The shared limit of cache misses was reached. Wait and retry. | | `UNABLE_TO_FETCH_ERRORS` | 500 | Failed to fetch error data from the edge provider. | | `ANALYTICS_BUSY` | 503 | Edge analytics are temporarily busy. Try again in a minute. | ## Related * CLI: [`squarecloud app network errors`](/en/cli-reference/edge-analytics#squarecloud-app-network-errors) * SDKs: [`api.apps.network.errors()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.errors()`](/en/sdks/py/network) (Python), [`c.Apps.Network.Errors()`](/en/sdks/go/network) (Go) # List load balancers Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/load-balancers GET https://api.squarecloud.app/v2/apps/load-balancers List the account's custom domains and the applications serving each with GET /v2/apps/load-balancers, plus the plan's limit of apps per domain. Groups the account's applications by attached custom domain. Every custom domain appears as one group with the applications serving it; a group with two or more applications is an active load balancer, where traffic is balanced across the applications at the edge with automatic failover when one is offline. Attach the same domain to multiple applications with the [Set Custom Domain](/en/api-reference/endpoint/apps/network/custom) route. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This endpoint reads from the same cached project list used elsewhere in the API, so it does not call out to the edge provider and is not subject to the per-application network rate limits that gate [Network Analytics](/en/api-reference/endpoint/apps/network/analytics) and [Network Errors](/en/api-reference/endpoint/apps/network/errors). It is rate limited to 20 requests per 60 seconds per user instead. `limit` reflects the caller's own plan tier (2 on Standard, 5 on Pro, 10 on Enterprise), so check it before attempting to add another application to an existing group. Attach or detach applications from a domain with [Set Custom Domain](/en/api-reference/endpoint/apps/network/custom), or see every hostname on the account with [List Domains](/en/api-reference/endpoint/apps/domains). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. Maximum number of applications allowed on one domain for the account's plan: 2 on Standard, 5 on Pro, 10 on Enterprise. Custom domains grouped by hostname. Empty array when no application has a custom domain. The custom domain. Applications serving this domain (`id`, `name`, and the `cluster` currently hosting each). ```json theme={"system"} { "status": "success", "response": { "limit": 2, "balancers": [ { "hostname": "example.com", "apps": [ { "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d", "name": "web-1", "cluster": "suki-cluster" }, { "id": "f6e5d4c3b2a14f0e9d8c7b6a5f4e3d2c", "name": "web-2", "cluster": "nasa-cluster" } ] } ] } } ``` ## Related * CLI: [`squarecloud app load-balancers`](/en/cli-reference/domains#squarecloud-app-load-balancers) * SDKs: [`api.apps.loadBalancers()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.load_balancers()`](/en/sdks/py/managing_application) (Python), [`c.Apps.LoadBalancers()`](/en/sdks/go/managing_application) (Go) # Get edge request logs Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/logs GET https://api.squarecloud.app/v2/apps/{app_id}/network/logs Get per-request edge logs for an application's domains with GET /v2/apps/{app_id}/network/logs, up to 7 days back. Available on Pro and Enterprise. Returns per-request edge logs (HTTP, country, status, bytes) for the application's primary domain and any configured custom domain. Maximum retention window is 7 days; the start is clamped to the application's creation date. Available only on **Pro** and **Enterprise** plans. Cache misses share one limit of 20 requests per 60 seconds per application owner, across the analytics, errors, logs and performance endpoints. Cached responses do not count. During platform-wide busy periods the endpoint may return the most recent cached data for the requested window instead. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). This is a sample of raw, per-request edge traffic, not the application's own runtime output; for stdout/stderr from the container, see [Get Application Logs](/en/api-reference/endpoint/apps/logs) instead. Each entry captures the client (IP, country, user agent), the request (method, path, query, protocol), and the response (status, content type, cache HIT/MISS) as Cloudflare saw it. Results are cached in 5-minute buckets, the same alignment used by [Network Analytics](/en/api-reference/endpoint/apps/network/analytics), so repeated polling of a moving window reuses the cached sample instead of re-fetching from the edge on every call. Combine with [Network Errors](/en/api-reference/endpoint/apps/network/errors) to correlate a spike in 5xx responses with the specific requests that triggered it. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ISO 8601 start timestamp. Cannot be earlier than the application's creation date or older than 7 days. ISO 8601 end timestamp. Must be after `start`. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. Timestamp of the request in ISO format. Information about the client that made the request. The client's IP address. The client's country code. The client's country name (e.g. `Brazil`). The client's ASN. The client's user agent. The client category (e.g. bot, human). Information about the incoming request. Whether the request was mitigated by edge protections. HTTP method used. Host header value. Request path. Query string. Protocol used (e.g. HTTP/2). Referer header value. Information about the response served at the edge. HTTP status code returned. Response content type. Cache status (e.g. HIT, MISS). ```json theme={"system"} { "status": "success", "response": [ { "timestamp": "2025-12-01T12:00:00.000Z", "client": { "ip": "203.0.113.45", "country": "BR", "location": "Brazil", "asn": "12345 - Example ISP", "agent": "Mozilla/5.0", "category": null }, "request": { "mitigated": false, "method": "GET", "host": "my-app.squareweb.app", "path": "/api/users", "query": "?limit=10", "protocol": "HTTP/2", "referer": null }, "response": { "status": 200, "contentType": "application/json", "cache": "MISS" } } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_TIME_RANGE` | 400 | `start`/`end` are missing, malformed, or invert the time range. | | `UPGRADE_REQUIRED` | 403 | Analytics logs are available for Pro and Enterprise plans only. | | `RATE_LIMITED` | 429 | The shared limit of cache misses was reached. Wait and retry. | | `UNABLE_TO_FETCH_ANALYTICS` | 500 | Failed to fetch logs from the edge provider. | | `ANALYTICS_BUSY` | 503 | Edge analytics are temporarily busy. Try again in a minute. | ## Related * CLI: [`squarecloud app network logs`](/en/cli-reference/edge-analytics#squarecloud-app-network-logs) * SDKs: [`api.apps.network.logs()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.logs()`](/en/sdks/py/network) (Python), [`c.Apps.Network.Logs()`](/en/sdks/go/network) (Go) # Get edge and origin latency Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/performance GET https://api.squarecloud.app/v2/apps/{app_id}/network/performance Get edge and origin latency percentiles with GET /v2/apps/{app_id}/network/performance, by country, colo and slowest path. For Pro and Enterprise. Returns edge and origin response-time percentiles (`p50`, `p95`, `p99`) for the application over a time window, plus per-country, per-colo and slowest-path breakdowns. Useful for diagnosing latency regressions and identifying which routes or regions are slowest. Available only on **Pro** and **Enterprise** plans. Cache misses share one limit of 20 requests per 60 seconds per application owner, across the analytics, errors, logs and performance endpoints. Cached responses do not count. During platform-wide busy periods the endpoint may return the most recent cached data for the requested window instead. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Edge latency (`edge`) measures time-to-first-byte at Cloudflare's network; origin latency (`origin`) measures how long the application itself took to respond once the edge reached it. A gap between the two that grows during a window usually points at the application or its cluster node, while both rising together points at network conditions between the client and the edge. This measures network latency, not container resource usage; for CPU, RAM, and bandwidth sampled from the container itself, see [Get Application Metrics](/en/api-reference/endpoint/apps/metrics). Combine `colos` and `countries` with [Network Analytics](/en/api-reference/endpoint/apps/network/analytics) to see whether a slow region is also a low-traffic one before prioritizing a fix. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ISO 8601 start timestamp for the analysis window. ISO 8601 end timestamp. Must be after `start`. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. Latency percentiles and breakdowns for the window. Aggregate latency percentiles across the whole window. Edge-side latency percentiles in milliseconds. 50th percentile (median) edge latency. 95th percentile edge latency. 99th percentile edge latency. Origin-side latency percentiles in milliseconds. 50th percentile (median) origin latency. 95th percentile origin latency. 99th percentile origin latency. Total number of requests analysed in the window. Latency percentiles bucketed across the analysis window. Bucket start timestamp in ISO 8601 format. Requests observed in the bucket. Edge `p50`/`p95`/`p99` for this bucket. Origin `p50`/`p95`/`p99` for this bucket. Latency breakdown by client country. Two-letter country code (e.g. `BR`, `US`). Median latency for this country in milliseconds. 95th percentile latency for this country in milliseconds. Requests served to this country. Latency breakdown by edge colo (data center). Colo identifier (e.g. `GRU`, `IAD`). City where the colo is located. Country where the colo is located. Median latency at this colo in milliseconds. 95th percentile latency at this colo in milliseconds. Requests served through this colo. Paths with the highest latency in the window. Request path. 95th percentile latency for this path in milliseconds. 99th percentile latency for this path in milliseconds. Requests observed for this path. ```json theme={"system"} { "status": "success", "response": { "summary": { "edge": { "p50": 42, "p95": 180, "p99": 320 }, "origin": { "p50": 28, "p95": 150, "p99": 280 }, "requests": 12450 }, "timeseries": [ { "date": "2025-12-01T12:00:00.000Z", "requests": 540, "edge": { "p50": 41, "p95": 175, "p99": 310 }, "origin": { "p50": 27, "p95": 148, "p99": 270 } } ], "countries": [ { "type": "BR", "p50": 35, "p95": 160, "requests": 8200 }, { "type": "US", "p50": 55, "p95": 210, "requests": 3100 } ], "colos": [ { "type": "GRU", "city": "São Paulo", "country": "BR", "p50": 34, "p95": 158, "requests": 8100 } ], "slowest_paths": [ { "path": "/api/reports/generate", "p95": 820, "p99": 1500, "requests": 230 } ] } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_TIME_RANGE` | 400 | `start`/`end` are missing, malformed, or invert the time range. | | `UPGRADE_REQUIRED` | 403 | Performance analytics are available for Pro and Enterprise plans only. | | `RATE_LIMITED` | 429 | The shared limit of cache misses was reached. Wait and retry. | | `UNABLE_TO_FETCH_PERFORMANCE` | 500 | Failed to fetch performance data from the edge provider. | | `ANALYTICS_BUSY` | 503 | Edge analytics are temporarily busy. Try again in a minute. | ## Related * CLI: [`squarecloud app network performance`](/en/cli-reference/edge-analytics#squarecloud-app-network-performance) * SDKs: [`api.apps.network.performance()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.performance()`](/en/sdks/py/network) (Python), [`c.Apps.Network.Performance()`](/en/sdks/go/network) (Go) # Purge an application's edge cache Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/network/purge_cache POST https://api.squarecloud.app/v2/apps/{app_id}/network/purge_cache Clear every cached edge response for an application's domains with POST /v2/apps/{app_id}/network/purge_cache, so the next request is served fresh. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:write` [scope](/en/api-reference/authentication#scopes). Purging clears every cached response Cloudflare is holding for the application's primary domain and any attached custom domain, forcing the next request for each URL to be served fresh from the application. Use it right after deploying a change to static assets or an API response that a previous request already cached, when you cannot wait for the resource's own cache TTL to expire. The purge itself is asynchronous: the edge provider acknowledges the request, but propagation across edge locations is not instant. On workspace-shared applications, the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). To push the changed files first, see [Commit Application](/en/api-reference/endpoint/apps/commit) or [Upload Application](/en/api-reference/endpoint/apps/upload). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `KEEP_CALM` | 429 | More than 1 purge in 60 seconds. | | `PURGE_CACHE_FAILED` | 500 | The edge cache purge could not be completed; retry in a moment. | ## Related * CLI: [`squarecloud app network purge-cache`](/en/cli-reference/edge-analytics#squarecloud-app-network-purge-cache) * SDKs: [`api.apps.network.purgeCache()`](/en/sdks/js/network) (JavaScript), [`client.apps.network.purge_cache()`](/en/sdks/py/network) (Python), [`c.Apps.Network.PurgeCache()`](/en/sdks/go/network) (Go) # Stream real-time logs and metrics (SSE) Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/realtime GET https://api.squarecloud.app/v2/apps/{app_id}/realtime Open a Server-Sent Events stream with GET /v2/apps/{app_id}/realtime for live logs, metrics, status and deploy progress. A connection lasts up to 10 minutes. The API Playground is disabled for this endpoint due to the nature of SSE connections, which are not universally supported by browsers. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Use this endpoint whenever you need a live view of an application instead of polling: watching a deploy progress, tailing logs as they are written, or driving a dashboard's CPU/RAM graph without hammering [Get Application Status](/en/api-reference/endpoint/apps/status) or [Get Application Logs](/en/api-reference/endpoint/apps/logs) on a timer. It replaces both for the duration of the connection. Internally, opening a connection here dials a single upstream stream on the application's cluster and relays it back over SSE, with one transparent internal reconnect if that upstream drops. Because each open connection holds a socket for up to 10 minutes, opens are rate limited separately from the concurrent-connection caps described below: 1 open every 5 seconds per (user, application), and 20 opens every 10 seconds per user across all applications, with a short cooldown after that. ## Parameters The ID of the application whose logs you want to monitor. This ID can be found in the URL of your application's management panel. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. In case of failure, the response will include a `code` field along with the error status, detailing the cause. If the request is successful, the response will be a `text/event-stream` stream containing the application's realtime feed. Each connection lasts up to **10 minutes**. Each account may hold **5 concurrent realtime connections** (`REALTIME_MAX_CONNECTIONS`) and each application **30 across all users** (`REALTIME_MAX_CONNECTIONS_APP`); exceeding either returns `429`. ## Server-Sent Events (SSE) structure The response is a continuous stream in `text/event-stream` format. Each message is composed of an `event` field and a `data` field. Shapes vary by event, so parse payloads defensively. ### Event types * `system`: Protocol-level signals. The `data` line is a single uppercase code: `REALTIME_CONNECTING | ` on connect, then any of `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT`, or `REALTIME_ERROR`. * `logs`: A single log line whose **first character is a stream-id byte**: `\x01` (stdout) or `\x02` (stderr). Read `data.charCodeAt(0)` (1 = stdout, 2 = stderr), then `data.slice(1)` for the text. A line without that prefix byte is stdout. * `status`: Live container metrics as a JSON string, about one frame per second. The **first frame** of each (re)connection is complete: `{ cpu, cpuLimit, ram: [usedMB, limitMB], status, netIO: { i, o, new: { i, o } }, bIO: { i, o }, uptime }` (`cpuLimit` is the number of CPU cores allocated; `uptime` is the start time as epoch ms; `netIO.new` is bytes per second). **Every later frame is lean**, carrying only `{ cpu, ram, netIO, bIO }`: merge each onto the last complete frame, keeping the previous `cpuLimit`, `status`, and `uptime`. While this stream is open, prefer it over polling `GET /v2/apps/{app_id}/status`, which can be up to about a minute stale for an app with an open realtime stream. * `error`: Carries an error code such as `CONTAINER_NOT_FOUND`. In the example below, `\x01` / `\x02` stand for the raw stdout / stderr prefix bytes. ```text Stream example theme={"system"} event: system data: REALTIME_CONNECTING | abc123-1716000000000-deadbeef event: status data: {"cpu":12.5,"cpuLimit":1,"ram":[128,512],"status":"running","netIO":{"i":2048,"o":4096,"new":{"i":64,"o":128}},"bIO":{"i":0,"o":0},"uptime":1716000000000} event: status data: {"cpu":13.1,"ram":[131,512],"netIO":{"i":2176,"o":4288,"new":{"i":72,"o":140}},"bIO":{"i":0,"o":0}} event: logs data: \x01Server listening on :3000 event: logs data: \x02Error: connect ECONNREFUSED ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `REALTIME_MAX_CONNECTIONS` | 429 | The caller already has 5 concurrent realtime connections open. | | `REALTIME_MAX_CONNECTIONS_APP` | 429 | The application already has 30 concurrent realtime connections open across all users. | ## Related * CLI: [`squarecloud app realtime`](/en/cli-reference/logs#squarecloud-app-realtime) * SDKs: [`api.apps.realtime()`](/en/sdks/js/realtime) (JavaScript), [`client.apps.realtime()`](/en/sdks/py/realtime) (Python), [`c.Apps.Realtime()`](/en/sdks/go/realtime) (Go) # Restart application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/restart POST https://api.squarecloud.app/v2/apps/{app_id}/restart Restart an application with POST /v2/apps/{app_id}/restart, stopping and starting it again. Call it after a commit so the new files take effect. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:control` [scope](/en/api-reference/authentication#scopes). Restarts a running application: it stops the application and then starts it again. This is the endpoint to call after [Commit Application](/en/api-reference/endpoint/apps/commit) so newly pushed files take effect, since committing on its own does not restart the application. On workspace-shared applications, the caller needs the `manager`, `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). The request is rate limited to 1 restart per 3 seconds per application, and to 20 lifecycle actions per 15 seconds per user across all applications, with a short block once that cap is hit. A restart can fail, for example when the application doesn't come back up: check [Get Application Status](/en/api-reference/endpoint/apps/status) and the [logs](/en/api-reference/endpoint/apps/logs), and [start](/en/api-reference/endpoint/apps/start) it again if needed. The request is also rejected with `403 RESTORE_IN_PROGRESS` while a snapshot restore runs on the application (up to about 2 minutes): wait for the restore to finish and try again. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is running on this application; wait for it to finish (up to about 2 minutes). | | `ACTION_FAILED` | 409 | The cluster rejected the action, for example the application is already mid-deploy. | ## Related * CLI: [`squarecloud app restart`](/en/cli-reference/apps#squarecloud-app-restart) * SDKs: [`api.apps.restart()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.restart()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Restart()`](/en/sdks/go/managing_application) (Go) # Create an application snapshot Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/snapshots/create POST https://api.squarecloud.app/v2/apps/{app_id}/snapshots Back up an application's files as a .zip with POST /v2/apps/{app_id}/snapshots. Returns a download URL, or 202 while a large snapshot keeps generating. Each account can perform up to (RAM / 256) \* 2 snapshots every 24 hours. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:write` [scope](/en/api-reference/authentication#scopes). Create Snapshot captures a point-in-time `.zip` copy of an application's full storage and returns a signed download URL, giving you a restore point before a risky change or a way to pull a full backup outside the platform. To bring the application back to that state later, pass the resulting snapshot to [Restore Snapshot](/en/api-reference/endpoint/apps/snapshots/restore); to inspect or download past snapshots without creating a new one, use [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list). Snapshots are only available with an active plan, and the daily quota scales with the application's RAM ((RAM / 256) × 2 per 24 hours). On workspace-shared applications the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Soft deadline behavior This route follows a **soft deadline** model: it no longer always responds synchronously. * If the snapshot finishes within **\~90 seconds**, the route responds with `200 success` and a signed download URL (valid for 30 days), exactly as before. * If the snapshot takes longer than **\~90 seconds** to generate, the route responds **immediately** with `202` and the code `SNAPSHOT_PROCESSING`. **This is not a failure.** The snapshot keeps generating in the background and will appear in the [snapshot listing](/en/api-reference/endpoint/apps/snapshots/list) on its own, typically within \~2 minutes. This is expected behavior for large applications. Do not use this `POST` endpoint as a polling mechanism. To check whether a `SNAPSHOT_PROCESSING` snapshot has completed, use the [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list) (`GET`) endpoint: **not** another `POST`. Re-posting after the snapshot has finished starts a brand-new snapshot from scratch. The client should branch on the response as follows: | Response | Meaning | What to do | | - | - | - | | `status === "success"` | Snapshot is ready. | Use the `url` to download it. | | `status === "error"` and `code === "SNAPSHOT_PROCESSING"` | Snapshot is still generating. | Wait \~2 minutes, then confirm via [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list) (`GET`). Do **not** re-`POST`. | | `status === "error"` with any other `code` | Actual failure. | Handle the error (see below). | ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. Present only when `status` is `success`. The URL to download the snapshot of your application. The key to download the snapshot of your application. Returned when the snapshot exceeds the \~90 second soft deadline. The snapshot is still being generated in the background and will appear in the snapshot listing on its own, typically within \~2 minutes. Not an error: wait and confirm via the `GET` listing endpoint. ## Errors A snapshot request can be rejected with `429 Too Many Requests`. Use the `code` field to tell the two cases apart: Short-term cooldown: you hit the per-user (1 request / 5s) or per-application (1 request / 180s) limit. Back off and retry shortly. Daily quota reached: the account used up its plan's daily snapshot allowance ((RAM / 256) × 2 per 24h). The quota frees up as the rolling 24-hour window advances; for a higher daily allowance, upgrade the plan. ```json 200 Success theme={"system"} { "status": "success", "response": { "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D", "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D" } } ``` ```json 202 SNAPSHOT_PROCESSING theme={"system"} { "status": "error", "code": "SNAPSHOT_PROCESSING" } ``` ```json 429 KEEP_CALM theme={"system"} { "status": "error", "code": "KEEP_CALM", "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s" } ``` ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={"system"} { "status": "error", "code": "DAILY_SNAPSHOTS_LIMIT_REACHED", "message": "You are being rate limited for daily snapshots. 8r/24h" } ``` ## Related * CLI: [`squarecloud app snapshot create`](/en/cli-reference/snapshots#squarecloud-app-snapshot-create) * SDKs: [`api.apps.snapshots.create()`](/en/sdks/js/snapshots) (JavaScript), [`client.apps.snapshots.create()`](/en/sdks/py/snapshots) (Python), [`c.Apps.Snapshots.Create()`](/en/sdks/go/snapshots) (Go) # List application snapshots Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/snapshots/list GET https://api.squarecloud.app/v2/apps/{app_id}/snapshots List the stored snapshots of an application with GET /v2/apps/{app_id}/snapshots, each with its size, date, download URL and the IDs to restore it. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:read` [scope](/en/api-reference/authentication#scopes). List Snapshots returns every snapshot stored for an application, each with its size, last-modified date, and a signed `url` for downloading it. Use it to build a restore picker, or to confirm a snapshot from [Create Snapshot](/en/api-reference/endpoint/apps/snapshots/create) has finished generating after a `202 SNAPSHOT_PROCESSING` response, poll this endpoint rather than re-posting to create. The result is cached for 30 minutes per owner/application pair, so a snapshot that just finished generating in the background may take a short while to show up here even after the cluster has written it. Once you have a snapshot's `name` and `version_id`, pass them as `snapshotId` and `versionId` to [Restore Snapshot](/en/api-reference/endpoint/apps/snapshots/restore) to roll the application back to that point. Snapshots are only available with an active plan, the daily snapshot quota scales with the application's RAM allocation. On workspace-shared applications the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The snapshot's name: the application ID, optionally suffixed with `_` and `_`. Pass it unchanged as `snapshotId` when restoring. Size of the backup in bytes. Date of the last modification of the backup. The signed query string of the download URL. The snapshot's version. Pass it as `versionId` when restoring. A signed URL that downloads the snapshot, valid for 30 days. Runtime the snapshot was taken from: the application's language (`javascript`, `python`, `rust`...) or the database engine (`mongo`, `mysql`, `postgres`, `redis`). `null` on snapshots taken before this field existed. How the snapshot was created: `manual` (requested through the API, dashboard or CLI) or `automatic` (the daily scheduled snapshot). `null` on older snapshots. ```json theme={"system"} { "status": "success", "response": [ { "name": "1d2cdc0d6ebd435c91315c6329d12eab_javascript_manual", "size": 12900705, "modified": "2024-06-27T06:23:42.326Z", "key": "AWSAccessKeyId=access key", "version_id": "3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY", "url": "https://snapshots.squarecloud.app/applications//.zip?", "runtime": "javascript", "origin": "manual" }, { "name": "1d2cdc0d6ebd435c91315c6329d12eab_javascript_automatic", "size": 12900705, "modified": "2024-06-26T07:05:40.000Z", "key": "AWSAccessKeyId=access key", "version_id": "Qm8cFZ2vY1tBn4LhXw0e.KpR7sUjD9aGz", "url": "https://snapshots.squarecloud.app/applications//.zip?", "runtime": "javascript", "origin": "automatic" }, { "name": "1d2cdc0d6ebd435c91315c6329d12eab", "size": 12900705, "modified": "2024-06-25T05:15:51.533Z", "key": "AWSAccessKeyId=access key", "version_id": "yT5wN0cE3hJ.bV8mLq2XoZr6dAiK4sPf", "url": "https://snapshots.squarecloud.app/applications//.zip?", "runtime": null, "origin": null } ] } ``` Download a snapshot from its `url`. The link stays valid for 30 days. ## Common errors | Code | HTTP | Meaning | | - | - | - | | `APP_NOT_FOUND` | 404 | No application with that ID exists for the resolved owner. | ## Related * CLI: [`squarecloud app snapshot list`](/en/cli-reference/snapshots#squarecloud-app-snapshot-list) * SDKs: [`api.apps.snapshots.list()`](/en/sdks/js/snapshots) (JavaScript), [`client.apps.snapshots.list()`](/en/sdks/py/snapshots) (Python), [`c.Apps.Snapshots.List()`](/en/sdks/go/snapshots) (Go) # Restore an application snapshot Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/snapshots/restore POST https://api.squarecloud.app/v2/apps/{app_id}/snapshots/restore Roll an application's files back to a snapshot with POST /v2/apps/{app_id}/snapshots/restore, using the snapshotId and versionId from the list. This route has a rate limit of 1 request every 60 seconds. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:write` [scope](/en/api-reference/authentication#scopes). Restore Snapshot rolls an application's storage back to a previous [snapshot](/en/api-reference/endpoint/apps/snapshots/create), replacing its current files with the ones captured at snapshot time. Use it to recover from a bad deploy or accidental deletion. Get the `snapshotId` and `versionId` values from [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list), they are not something you construct by hand. `snapshotId` is the snapshot `name` exactly as [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list) returns it (the application ID, optionally suffixed with `_` and `_`), and `versionId` must match the S3 version-key format; malformed values are rejected before the restore is dispatched. The restore stops the application, replaces its files with the snapshot's and starts it again, so no separate restart is needed. While it runs (up to about 2 minutes), [start](/en/api-reference/endpoint/apps/start), [stop](/en/api-reference/endpoint/apps/stop), [restart](/en/api-reference/endpoint/apps/restart) and delete answer `403 RESTORE_IN_PROGRESS`. Snapshots (and therefore restores) are only available with an active plan. On workspace-shared applications the caller needs the `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. The snapshot `name` from the listing (the application ID, optionally suffixed with `_` and `_`), passed exactly as returned. The snapshot's `version_id`, as [List Snapshots](/en/api-reference/endpoint/apps/snapshots/list) returns it. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `MISSING_PARAMETERS` | 400 | `snapshotId` or `versionId` is missing. | | `INVALID_SNAPSHOT_ID` | 400 | `snapshotId` is not a snapshot name as returned by the listing (an ID, optionally with up to two `_` suffixes). | | `INVALID_VERSION_ID` | 400 | `versionId` does not match the expected S3 version-key format. | | `SNAPSHOT_NOT_FOUND` | 404 | No snapshot exists at that ID and version for this application. | | `APP_NOT_FOUND` | 404 | The application does not exist, or its owner no longer exists. | | `SNAPSHOT_RESTORE_FAILED` | 404 | The restore failed. This is the only failure code; `SNAPSHOT_NOT_FOUND` means the snapshot does not exist. | ## Related * CLI: [`squarecloud app snapshot restore`](/en/cli-reference/snapshots#squarecloud-app-snapshot-restore) * SDKs: [`api.apps.snapshots.restore()`](/en/sdks/js/snapshots) (JavaScript), [`client.apps.snapshots.restore()`](/en/sdks/py/snapshots) (Python), [`c.Apps.Snapshots.Restore()`](/en/sdks/go/snapshots) (Go) # Start application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/start POST https://api.squarecloud.app/v2/apps/{app_id}/start Start a stopped application with POST /v2/apps/{app_id}/start. Returns 409 when it is already running, and it never deploys new code. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:control` [scope](/en/api-reference/authentication#scopes). Starts a stopped application on its assigned cluster. If the application is already running, the request answers `409 CONTAINER_ALREADY_STARTED` instead of doing nothing, so check [Get Application Status](/en/api-reference/endpoint/apps/status) first or treat that code as success in scripts. Starting only brings the existing files and configuration online, it does not deploy new code; use [Upload Application](/en/api-reference/endpoint/apps/upload) for a first deployment or [Commit Application](/en/api-reference/endpoint/apps/commit) to push a change first. On workspace-shared applications, the caller needs the `manager`, `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). The request is rate limited to 1 start per 3 seconds per application, and to 20 lifecycle actions per 15 seconds per user across all applications, with a short block once that cap is hit. The request is also rejected with `403 RESTORE_IN_PROGRESS` while a snapshot restore runs on the application (up to about 2 minutes): wait for the restore to finish and try again. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is running on this application; wait for it to finish (up to about 2 minutes). | | `CONTAINER_ALREADY_STARTED` | 409 | The application is already running. | | `ACTION_FAILED` | 409 | The cluster rejected the action, for example the application is mid-deploy. | ## Related * CLI: [`squarecloud app start`](/en/cli-reference/apps#squarecloud-app-start) * SDKs: [`api.apps.start()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.start()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Start()`](/en/sdks/go/managing_application) (Go) # Get application status Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/status GET https://api.squarecloud.app/v2/apps/{app_id}/status Get an application's live CPU, RAM, storage, network and uptime with GET /v2/apps/{app_id}/status. Pass rawData=true for numbers instead of strings. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Returns the application's current CPU, RAM, storage, network, and uptime figures, formatted as human-readable strings by default (e.g. `"120.4MB"`, `"602 KB ↑ 134 KB ↓"`). Pass `rawData=true` to get the same fields as raw numbers instead, which is easier to work with if you are charting the values yourself. If you also have a [Real-time Logs](/en/api-reference/endpoint/apps/realtime) connection open for the same application, prefer the `status` events on that stream: while a realtime connection is active, this endpoint's numbers can lag behind by up to about a minute. To check every application at once instead of one at a time, see [All Applications Status](/en/api-reference/endpoint/apps/status-all). ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. When `true`, `cpu`, `ram` and the other figures come as numbers instead of formatted strings. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The CPU usage of the application. The RAM in use, for example `"120.4MB"`. It does not include the allocated limit. The status of the application. Indicates whether the application is currently running. The storage used by the application. The total network usage of the application. The current network usage of the application. The uptime of the application in milliseconds. ```json theme={"system"} { "status": "success", "response": { "cpu": "0.01%", "ram": "120.4MB", "status": "running", "running": true, "storage": "2.72MB", "network": { "total": "602 KB ↑ 134 KB ↓", "now": "14 KB ↑ 3.3 KB ↓" }, "uptime": 1662927833666 } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `APP_NOT_FOUND` | 404 | The application does not exist or does not belong to the caller. | ## Related * CLI: [`squarecloud app status`](/en/cli-reference/status-and-metrics#squarecloud-app-status) * SDKs: [`api.apps.status()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.status()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Status()`](/en/sdks/go/managing_application) (Go) # All applications status Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/status-all GET https://api.squarecloud.app/v2/apps/status Get the live CPU, RAM and running state of every application you own with GET /v2/apps/status. Pass workspaceId to list a workspace's apps instead. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:read` [scope](/en/api-reference/authentication#scopes). Returns live CPU, RAM, and running state for every application you own in a single call, which is more efficient than looping over [Get Application Status](/en/api-reference/endpoint/apps/status) once per application. Pass `workspaceId` to scope the listing to a shared workspace instead of your own applications; the caller must be the workspace owner or a member. This is the endpoint the dashboard's applications overview polls. It is rate limited to 15 requests every 60 seconds per user; the equivalent per-application endpoint has its own, separate limits. For continuous updates instead of polling, open a [Real-time Logs](/en/api-reference/endpoint/apps/realtime) connection per application. ## Parameters A workspace id. You can found it below your workspace name on dashboard. If `workspaceId` isn't provided, will get your account applications status. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The application ID. The CPU usage of the application. The RAM usage of the application. Indicates whether the application is currently running. ```json theme={"system"} { "status": "success", "response": [ { "id": "5bbd020126ee4692aga43e0ca0a75454", "cpu": "0.00%", "ram": "55.88MB", "running": true }, { "id": "e1b286ba30f14a87baed4b4ad3b53c47", "cpu": "0.01%", "ram": "68.44MB", "running": true } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `WORKSPACE_NOT_FOUND` | 404 | The `workspaceId` does not exist or the caller is not the owner or a member. | ## Related * SDKs: [`api.apps.statusAll()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.status_all()`](/en/sdks/py/managing_application) (Python), [`c.Apps.StatusAll()`](/en/sdks/go/managing_application) (Go) # Stop application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/stop POST https://api.squarecloud.app/v2/apps/{app_id}/stop Stop a running application with POST /v2/apps/{app_id}/stop, keeping its files, variables and configuration. Returns 409 when it is already stopped. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:control` [scope](/en/api-reference/authentication#scopes). Shuts down a running application without deleting it: the container stops, but the application's files, environment variables, and configuration are kept, so it can be started again at any time with [Start Application](/en/api-reference/endpoint/apps/start). If the application is already stopped, the request answers `409 CONTAINER_ALREADY_STOPPED` instead of doing nothing. This is the endpoint to reach for when you want to free up an application's resources temporarily, for example pausing a background worker outside business hours, without giving up the application slot the way [Delete Application](/en/api-reference/endpoint/apps/delete) would. On workspace-shared applications, the caller needs the `manager`, `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles). The request is rate limited to 1 stop per 3 seconds per application, and to 20 lifecycle actions per 15 seconds per user across all applications, with a short block once that cap is hit. The request is also rejected with `403 RESTORE_IN_PROGRESS` while a snapshot restore runs on the application (up to about 2 minutes): wait for the restore to finish and try again. ## Parameters The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is running on this application; wait for it to finish (up to about 2 minutes). | | `CONTAINER_ALREADY_STOPPED` | 409 | The application is already stopped. | | `ACTION_FAILED` | 409 | The cluster rejected the action, for example the application is mid-deploy. | ## Related * CLI: [`squarecloud app stop`](/en/cli-reference/apps#squarecloud-app-stop) * SDKs: [`api.apps.stop()`](/en/sdks/js/managing_application) (JavaScript), [`client.apps.stop()`](/en/sdks/py/managing_application) (Python), [`c.Apps.Stop()`](/en/sdks/go/managing_application) (Go) # Upload application Source: https://docs.squarecloud.app/en/api-reference/endpoint/apps/upload POST https://api.squarecloud.app/v2/apps Create and deploy a new application from a .zip of up to 100 MB with POST /v2/apps. The runtime is detected automatically; use commit for later changes. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `apps:write` [scope](/en/api-reference/authentication#scopes). Upload creates a brand-new application from a zip archive: it detects the runtime and version, provisions a container on whichever cluster currently has the lowest RAM usage, and starts it. Use this for a first deployment; for pushing a change to an application that already exists, use [Commit Application](/en/api-reference/endpoint/apps/commit) instead, which is faster because it does not re-provision the container. The caller needs at least **256 MB of available memory** on their plan before the upload is accepted, and the zip is capped at **100 MB**. The response fields depend on your `squarecloud.config`: `description` and `domain` are only present when set there, and `language` reports the detected runtime and version. Requests are rate limited to 1 upload every 3 seconds per user. The request body is limited to **101 MB** (a file of up to 100 MB plus form overhead): a larger request is rejected with `413 FILE_TOO_LARGE` while it is still uploading. Only the first file part is read; additional form fields are ignored. Once the application is running, manage it with [Start](/en/api-reference/endpoint/apps/start), [Stop](/en/api-reference/endpoint/apps/stop), and [Restart](/en/api-reference/endpoint/apps/restart), and check on it with [Get Application Status](/en/api-reference/endpoint/apps/status). ## Parameters The application to be uploaded must be compressed in a zip file (.zip) and the Content-Type must be multipart/form-data. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the uploaded application. The name of the uploaded application. The description of the uploaded application. The full host of the application, for example `my-app.squareweb.app`. Present only when `squarecloud.config` sets `SUBDOMAIN`. It is the same field that [Get Application Info](/en/api-reference/endpoint/apps/info) returns. The memory allocated to the application, in MB. The CPU allocated to the application. The detected runtime, in lowercase (for example `javascript`), as in Get Application Info. The recommended version of the programming language. The cluster where the application is cloud hosted. ```bash cURL theme={"system"} curl --request POST \ --url https://api.squarecloud.app/v2/apps \ --header 'Authorization: YOUR_API_KEY' \ --form 'file=@./application.zip' ``` ```javascript JavaScript theme={"system"} import fs from 'node:fs'; const form = new FormData(); form.append('file', new Blob([fs.readFileSync('./application.zip')]), 'application.zip'); const response = await fetch('https://api.squarecloud.app/v2/apps', { method: 'POST', headers: { Authorization: 'YOUR_API_KEY' }, body: form, }); ``` ```python Python theme={"system"} import requests with open('application.zip', 'rb') as f: response = requests.post( 'https://api.squarecloud.app/v2/apps', headers={'Authorization': 'YOUR_API_KEY'}, files={'file': ('application.zip', f, 'application/zip')}, ) ``` ```json theme={"system"} { "status": "success", "response": { "id": "945f574e6cc14ea6818f91d7d56de101", "name": "My Website", "description": "My first website on Square Cloud", "domain": "my-website.squareweb.app", "ram": 1024, "cpu": 6, "language": { "name": "javascript", "version": "recommended" } } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_CONTENT_TYPE` | 415 | The request body is not `multipart/form-data`. | | `INVALID_FILE` | 400 | No file field was found in the form data. | | `INVALID_FILENAME` | 400 | The file name contains path separators, `..`, or control characters. | | `INSUFFICIENT_MEMORY` | 400 | The account has less than 256 MB of available memory on its plan. | | `UPLOAD_ABORTED` | 400 | The client disconnected before the upload finished. | | `STORAGE_UPLOAD_FAILED` | 400 | The file failed to upload to storage; retry later. | | `CLUSTER_SELECTION_FAILED` | 400 | No cluster was available to host the application. | | `EMPTY_RESPONSE` | 400 | The cluster did not return a usable response. | | `UPLOAD_FAILED` | 400 | An unexpected error occurred while processing the upload. | | `FILE_TOO_LARGE` | 413 | The file exceeded 100 MB or the request body exceeded 101 MB. | | `CLUSTER_MAINTENANCE_TRY_LATER` | 503 | Application provisioning is temporarily unavailable due to maintenance. | | `UPLOAD_BUSY` | 503 | Too many uploads are being processed right now; retry in a moment. | ## Related * CLI: [`squarecloud upload`](/en/cli-reference/deploy#squarecloud-upload) * SDKs: [`api.apps.create()`](/en/sdks/js/commit_and_upload) (JavaScript), [`client.apps.create()`](/en/sdks/py/commit_and_upload) (Python), [`c.Apps.Create()`](/en/sdks/go/commit_and_upload) (Go) # Create database Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/create POST https://api.squarecloud.app/v2/databases Create a managed MongoDB, MySQL, PostgreSQL or Redis database with POST /v2/databases. The password and certificate are returned once, so save them. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:write` [scope](/en/api-reference/authentication#scopes). Provisions a managed database on Square Cloud (MongoDB, MySQL, PostgreSQL or Redis), picks the cluster with the most available RAM, and allocates a public DNS record (`square-cloud-db-.squareweb.app`) pointing to it. The `password` and `certificate` in the response are shown only once, save them immediately since neither can be retrieved again later, only reset via [Reset Credentials](/en/api-reference/endpoint/databases/credentials/reset). Database hosting requires a Standard, Pro or Enterprise plan. The requested `memory` must be at least the engine's minimum (512 MB for Redis, 1024 MB for MongoDB, MySQL and PostgreSQL) and cannot exceed your account's available memory. Rate limited to 1 creation every 3 seconds per user. A creation that fails leaves nothing behind, so it is safe to try again. Once created, use [Edit Database](/en/api-reference/endpoint/databases/edit) to rename it or resize its memory, and [Create Snapshot](/en/api-reference/endpoint/databases/snapshots/create) to back it up. ## Parameters The name of the database. 1–32 characters: letters, numbers, underscores (`_`), hyphens (`-`) and spaces, and must include at least one letter, number or underscore. The RAM allocated to it, in MB, as a whole number. Redis minimum is 512 and Mongo, 1024. The database type, mongo, redis, postgres, mysql. The version of the database.\\ Postgres 17, MySQL 9, Mongo 8, Redis 8. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the database. The name you chose for the database The memory allocated to the database The number of vCPUs allocated to the database The type of the database. The password for the database. The certificate needed to connect to it. You can save it in a `.pem` file. It can be `null`. The URL to connect to the database. The user is `default` for MongoDB and Redis, and `squarecloud` for PostgreSQL and MySQL. ```json theme={"system"} { "status":"success", "response": { "id": "a14b8d5e1cb7405a851eb4c075506121", "name": "test", "memory": 1024, "cpu": 2, "type": "mongo", "password": "PASSWORD", "certificate": "CERTIFICATE_IN_BASE_64_FORMAT", "connection_url": "mongodb://default:PASSWORD@square-cloud-db-ID.squareweb.app:PORT" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_NAME` | 400 | The name fails the 1-32 character validation. | | `INVALID_DATABASE_TYPE` | 400 | `type` is not one of `mongo`, `mysql`, `redis`, `postgres`. | | `INVALID_DATABASE_VERSION` | 400 | `version` is not a supported version for the chosen `type`. | | `INSUFFICIENT_MEMORY` | 400 | The requested `memory` is not a whole number of MB, is below the engine's minimum or exceeds the account's available memory. | | `CLUSTER_SELECTION_FAILED` | 400 | No cluster with enough capacity could be selected. | | `DATABASE_CREATION_FAILED` | 400 / 500 | Provisioning failed, or the cluster response was incomplete. Nothing is left behind, so you can retry. | | `UPGRADE_REQUIRED` | 403 | The account has no active plan, or its plan does not include database hosting. | | `CLUSTER_MAINTENANCE_TRY_LATER` | 503 | Database provisioning is temporarily unavailable due to maintenance. | ## Related * CLI: [`squarecloud db create`](/en/cli-reference/databases#squarecloud-db-create) * SDKs: [`api.databases.create()`](/en/sdks/js/databases) (JavaScript), [`client.databases.create()`](/en/sdks/py/databases) (Python), [`c.Databases.Create()`](/en/sdks/go/databases) (Go) # Edit database Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/edit PATCH https://api.squarecloud.app/v2/databases/{database_id} Rename a database or change its memory with PATCH /v2/databases/{database_id}, without restarting it or changing its credentials and connection URL. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:write` [scope](/en/api-reference/authentication#scopes). Updates a database's display name and/or its allocated memory without recreating the container or rotating its credentials, connection URL and port stay the same. At least one of `name` or `ram` must be present in the request body. Changing `ram` is applied live against the database's cluster; it fails if the new value is invalid for the plan or engine. This does not restart the database. To check whether a memory change is reflected, see [Get Database Info](/en/api-reference/endpoint/databases/info) or [Get Database Status](/en/api-reference/endpoint/databases/status). Rate limited to 1 update every 5 seconds per user. ## Parameters The ID of the database. The name of the database. 1–32 characters: letters, numbers, underscores (`_`), hyphens (`-`) and spaces, and must include at least one letter, number or underscore. The amount of RAM to allocate, in megabytes. Minimums: Redis 512 MB, MongoDB and PostgreSQL 1024 MB. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `NO_UPDATE_DATA` | 400 | Neither `name` nor `ram` was provided in the request body. | | `INVALID_NAME` | 400 | The new name fails the 1-32 character validation. | | `INVALID_MEMORY` | 400 | The new `ram` value is not valid for this database's engine or plan. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `INTERNAL_SERVER_ERROR` | 500 | The memory update could not be applied. | ## Related * CLI: [`squarecloud db update`](/en/cli-reference/databases#squarecloud-db-update) * SDKs: [`api.databases.update()`](/en/sdks/js/databases) (JavaScript), [`client.databases.update()`](/en/sdks/py/databases) (Python), [`c.Databases.Update()`](/en/sdks/go/databases) (Go) # Get database info Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/info GET https://api.squarecloud.app/v2/databases/{database_id} Get a database's metadata with GET /v2/databases/{database_id}: name, owner, cluster, allocated RAM, engine type and port, without live usage. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:read` [scope](/en/api-reference/authentication#scopes). Returns the static identity of a database: its name, owner, hosting cluster, allocated RAM, engine type and connection port. This is metadata only, it does not include live resource usage, use [Get Database Status](/en/api-reference/endpoint/databases/status) or [Get Database Metrics](/en/api-reference/endpoint/databases/metrics) for that. Useful for confirming a database's configuration after [Create Database](/en/api-reference/endpoint/databases/create) or [Edit Database](/en/api-reference/endpoint/databases/edit), or for looking up which cluster it lives on before contacting support. ## Parameters The ID of the database. You can find this in the Square Cloud dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The database's name. The database's ID. The ID of the database owner. The database's cluster. The database's RAM usage in MB. The database's type (e.g., mongodb, postgresql). The database's port. The database's creation date. ```json Response theme={"system"} { "status": "success", "response": { "name": "my-database", "id": "db1234567890", "owner": "123456789012345678", "cluster": "suki-cluster", "ram": 1024, "type": "mongodb", "port": 27017, "created_at": "2023-01-15T10:00:00Z" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | ## Related * CLI: [`squarecloud db info`](/en/cli-reference/databases#squarecloud-db-info) * SDKs: [`api.databases.get()`](/en/sdks/js/databases) (JavaScript), [`client.databases.get()`](/en/sdks/py/databases) (Python), [`c.Databases.Get()`](/en/sdks/go/databases) (Go) # Get database metrics Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/metrics GET https://api.squarecloud.app/v2/databases/{database_id}/metrics Get a database's CPU, RAM and network history with GET /v2/databases/{database_id}/metrics: up to 288 points over 24 hours, one every 5 minutes. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:read` [scope](/en/api-reference/authentication#scopes). Returns historical CPU, RAM and network usage for a database, sampled every 5 minutes over the last 24 hours (up to 288 points), newest first. Use it to plot usage graphs or to decide whether the database needs more memory before calling [Edit Database](/en/api-reference/endpoint/databases/edit). For a single current reading instead of a time series, use [Get Database Status](/en/api-reference/endpoint/databases/status). Responses are cached for 2.5 minutes per user and database, and the endpoint is rate limited to 10 requests per 5 seconds per user, with a short block once that cap is hit. A database with no recent samples returns an empty array rather than an error. ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The date in ISO format. The current CPU usage percentage. The current RAM usage in MB. An array representing total network used. First the input, second the output. ```json theme={"system"} { "status": "success", "response": [ { "date": "2025-08-13T12:55:01.348Z", "cpu": 0.45, "ram": 111.27, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:50:01.349Z", "cpu": 0.45, "ram": 111.22, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:45:01.350Z", "cpu": 0.58, "ram": 111.36, "net": [ 16834, 126 ] }, { "date": "2025-08-13T12:40:01.348Z", "cpu": 0.43, "ram": 118.44, "net": [ 16834, 126 ] } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | ## Related * CLI: [`squarecloud db metrics`](/en/cli-reference/databases#squarecloud-db-metrics) * SDKs: [`api.databases.metrics()`](/en/sdks/js/databases) (JavaScript), [`client.databases.metrics()`](/en/sdks/py/databases) (Python), [`c.Databases.Metrics()`](/en/sdks/go/databases) (Go) # Start database Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/start POST https://api.squarecloud.app/v2/databases/{database_id}/start Start a stopped database with POST /v2/databases/{database_id}/start. It comes back with the same connection URL, port and credentials as before. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:write` [scope](/en/api-reference/authentication#scopes). Starts a database that was previously stopped, bringing it back online at the same connection URL, port and credentials it had before. Use this to bring a managed MongoDB, MySQL, PostgreSQL or Redis instance back up after maintenance or a manual [Stop](/en/api-reference/endpoint/databases/stop). The request is rejected while a snapshot restore is running on the same database. Rate limited to 1 start per 3 seconds per user. Check [Get Database Status](/en/api-reference/endpoint/databases/status) to confirm the database is actually running, since a `success` response only means the action was dispatched. ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is currently running for this database; wait for it to finish. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `CONTAINER_ALREADY_STARTED` | 409 | The database is already running. | | `CONTAINER_TEMPORARILY_SUSPENDED` | 409 | The database is temporarily suspended. | | `ACTION_FAILED` | 409 | The cluster rejected the action for another reason. | ## Related * CLI: [`squarecloud db start`](/en/cli-reference/databases#squarecloud-db-start) * SDKs: [`api.databases.start()`](/en/sdks/js/databases) (JavaScript), [`client.databases.start()`](/en/sdks/py/databases) (Python), [`c.Databases.Start()`](/en/sdks/go/databases) (Go) # Get database status Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/status GET https://api.squarecloud.app/v2/databases/{database_id}/status Get a database's live CPU, RAM, network, storage and uptime with GET /v2/databases/{database_id}/status. Pass rawData=true for numbers, not strings. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:read` [scope](/en/api-reference/authentication#scopes). Returns live runtime stats for a single database: CPU, RAM, network usage, storage and uptime. Pass `rawData=true` to get raw numeric values instead of the formatted strings (`"0.54%"`, `"111.32MB"`) shown in the example below, useful when you want to do your own formatting or math client-side. To fetch this for every owned database at once, use [All Databases Status](/en/api-reference/endpoint/databases/status-all). For historical trends instead of a live reading, see [Get Database Metrics](/en/api-reference/endpoint/databases/metrics). ## Parameters The ID of the database. When `true`, `cpu`, `ram` and the other figures come as numbers instead of formatted strings. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The current CPU usage percentage. The RAM in use, for example `"120.4MB"`. It does not include the allocated limit. The boolean value if is running. The current storage it is using. The network usage and total used. The total used. The current use. The timestamp representing the uptime. ```json theme={"system"} { "status": "success", "response": { "cpu": "0.54%", "ram": "111.32MB", "status": "running", "running": true, "storage": "210.1MB", "network": { "total": "16.83KB ↑ 126B ↓", "now": "0B ↑ 0B ↓" }, "uptime": 1755028584438 } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | ## Related * CLI: [`squarecloud db status`](/en/cli-reference/databases#squarecloud-db-status) * SDKs: [`api.databases.status()`](/en/sdks/js/databases) (JavaScript), [`client.databases.status()`](/en/sdks/py/databases) (Python), [`c.Databases.Status()`](/en/sdks/go/databases) (Go) # All databases status Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/status-all GET https://api.squarecloud.app/v2/databases/status Get the live CPU, RAM and running state of every database you own in one call with GET /v2/databases/status, instead of one request per database. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:read` [scope](/en/api-reference/authentication#scopes). Returns live runtime stats, whether it's running, CPU and RAM usage, for every database owned by the caller in a single call. Use it to render a dashboard overview instead of calling [Get Database Status](/en/api-reference/endpoint/databases/status) once per database. This collection form is rate limited to 15 requests per 60 seconds per user, with a short block once that cap is hit; the single-database form is not subject to this limit. For historical CPU/RAM/network trends instead of a live snapshot, see [Get Database Metrics](/en/api-reference/endpoint/databases/metrics). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the database. The boolean value if is running. The current CPU usage percentage. The current RAM usage ```json theme={"system"} { "status": "success", "response": [ { "id": "a14b8d5e1cb7405a851eb4c075506121", "running": true, "ram": "118.95MB", "cpu": "0.40%" } ] } ``` ## Related * SDKs: [`api.databases.statusAll()`](/en/sdks/js/databases) (JavaScript), [`client.databases.status_all()`](/en/sdks/py/databases) (Python), [`c.Databases.StatusAll()`](/en/sdks/go/databases) (Go) # Stop database Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/stop POST https://api.squarecloud.app/v2/databases/{database_id}/stop Stop a running database with POST /v2/databases/{database_id}/stop. Its data is kept, and it starts again with the same credentials and connection URL. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:write` [scope](/en/api-reference/authentication#scopes). Stops a running database container. The data volume is preserved, so a subsequent [Start Database](/en/api-reference/endpoint/databases/start) call brings it back with the same credentials, port and connection URL. Use this to pause billing-relevant usage or take a database offline before maintenance. The request is rejected while a snapshot restore is in progress on the same database. Rate limited to 1 stop per 3 seconds per user. To check whether the stop actually took effect, poll [Get Database Status](/en/api-reference/endpoint/databases/status). ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is currently running for this database; wait for it to finish. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `CONTAINER_ALREADY_STOPPED` | 409 | The database is already stopped. | | `CONTAINER_TEMPORARILY_SUSPENDED` | 409 | The database is temporarily suspended. | | `ACTION_FAILED` | 409 | The cluster rejected the action for another reason. | ## Related * CLI: [`squarecloud db stop`](/en/cli-reference/databases#squarecloud-db-stop) * SDKs: [`api.databases.stop()`](/en/sdks/js/databases) (JavaScript), [`client.databases.stop()`](/en/sdks/py/databases) (Python), [`c.Databases.Stop()`](/en/sdks/go/databases) (Go) # Get service status Source: https://docs.squarecloud.app/en/api-reference/endpoint/service/status GET https://api.squarecloud.app/v2/service/status Check the overall health of the Square Cloud platform with GET /v2/service/status. It is public, needs no API key and is served from a 5-minute cache. Service Status returns the aggregate health of the Square Cloud platform, the same signal that powers the public status page and internal alerting. It's a public route with no API key required, which makes it a good fit for automated uptime checks or a small status widget on your own site. The payload is served from a 5-minute cache, so it can lag a transient incident by up to that window and should not be treated as a live incident feed. If the cached value can't be read, the endpoint still responds successfully with `status: "unknown"` instead of failing the request. For per-application health instead of the whole platform, see [Get Application Status](/en/api-reference/endpoint/apps/status) or [Get All Applications Status](/en/api-reference/endpoint/apps/status-all). This route has a 5-minute cache and does not reflect the real-time status of status.squarecloud.app. ## Response The current status of Square Cloud, with `online` indicating the service is online, `degraded` indicating issues, and `unknown` indicating unavailable. Message about the current status of Square Cloud services. ```json theme={"system"} { "status": "online", "message": "All services are online." } ``` ## Related * CLI: [`squarecloud status`](/en/cli-reference/global-flags-and-ci#squarecloud-status) * SDKs: [`api.service.status()`](/en/sdks/js/client) (JavaScript), [`client.service.status()`](/en/sdks/py/client) (Python), [`c.Service.Status()`](/en/sdks/go/client) (Go) # Get account information Source: https://docs.squarecloud.app/en/api-reference/endpoint/users/me GET https://api.squarecloud.app/v2/users/me Get your account in one call with GET /v2/users/me: profile, plan, memory usage and every application and database you own, ready for an overview page. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `account:read` [scope](/en/api-reference/authentication#scopes). Account Information returns everything about your own Square Cloud account in a single call: profile, plan and memory usage, and every application and database you own. It's a good root call for dashboards or CLI tools that need to render an account overview without querying each application and database individually. The response is scoped to the authenticated token; there is no way to request another account's data through this route. Applications include their domain and cluster, and databases include their type and RAM, both enough to build a listing UI without extra roundtrips. To drill into a single application instead, see [Get Application Info](/en/api-reference/endpoint/apps/info); for the account's backups, see [List Snapshots](/en/api-reference/endpoint/users/snapshots). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The response content. The user's ID. The user's name. The user's email. The user's locale. The user's plan name. The user's plan memory details. The user's plan memory limit in MB. The user's plan available memory in MB. The user's plan used memory in MB. When the plan expires, as a Unix timestamp in milliseconds. The user's account creation date. The application's name. The application's ID. The application's description. The application's RAM usage. The application's language. The application's domain. The application's custom domain. The application's cluster. The application's creation date. The database's ID. The database's name. The database's RAM usage. The database's type. The database's cluster. The database's creation date. ```json Response theme={"system"} { "status": "success", "response": { "user": { "id": "123456789012345678", "name": "John Doe", "email": "john@example.com", "plan": { "name": "standard-4", "memory": { "limit": 4096, "available": 3840, "used": 256 }, "duration": 1732072955446 }, "created_at": "2022-01-10T12:00:00Z" }, "applications": [ { "name": "Square Example APP", "id": "446b0b4118634a1c99e73bac9a54e475", "desc": "This is a example of description", "ram": 512, "lang": "javascript", "domain": "square-example-app.squareweb.app", "custom": "mydomain.com", "cluster": "suki-cluster", "created_at": "2023-02-20T14:30:00Z" } ], "databases": [ { "id": "db1234567890", "name": "example-database", "type": "mongodb", "cluster": "suki-cluster", "ram": 1024, "created_at": "2023-01-15T10:00:00Z" } ] } } ``` ## Related * CLI: [`squarecloud auth whoami`](/en/cli-reference/authentication#squarecloud-auth-whoami) * SDKs: [`api.account.me()`](/en/sdks/js/client) (JavaScript), [`client.account.me()`](/en/sdks/py/client) (Python), [`c.Account.Me()`](/en/sdks/go/client) (Go) # List all account snapshots Source: https://docs.squarecloud.app/en/api-reference/endpoint/users/snapshots GET https://api.squarecloud.app/v2/users/snapshots List the automatic snapshots of all your applications or databases with GET /v2/users/snapshots, with size, date and download URL. Needs an active plan. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:read` [scope](/en/api-reference/authentication#scopes). List Snapshots returns the automatic backups Square Cloud keeps for your applications or databases, each entry pairing a signed download URL fragment with its size and last-modified date. Use it to build a restore picker or audit retention in your own tooling instead of checking the dashboard manually. Results are cached per user and scope for 30 minutes; a cache miss counts against a tighter limit of 3 calls per 60 seconds, after which the caller is blocked for a short period. Listing snapshots requires an active plan, an account without one gets a 402. Snapshots are grouped by scope, applications by default or databases via the `scope` parameter below. For application details, see [Get Application Info](/en/api-reference/endpoint/apps/info); for database details, see [Get Database Info](/en/api-reference/endpoint/databases/info). ## Parameters Specifies the type of snapshots to retrieve. * `applications` (default): Returns snapshots of applications * `databases`: Returns snapshots of databases ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The snapshot's name: the ID of the application or database it belongs to, optionally suffixed with `_` and `_`. Pass it unchanged as `snapshotId` when restoring. Size of the snapshot in bytes. Date of the last modification of the snapshot. AWS access key for the snapshot. Runtime the snapshot was taken from: the application's language (`javascript`, `python`, `rust`...) or the database engine (`mongo`, `mysql`, `postgres`, `redis`). `null` on snapshots taken before this field existed. How the snapshot was created: `manual` (requested through the API, dashboard or CLI) or `automatic` (the daily scheduled snapshot). `null` on older snapshots. ```json Response theme={"system"} { "status": "success", "response": [ { "name": "1d2cdc0d6ebd435c91315c6329d12eab_javascript_manual", "size": 12900705, "modified": "2024-06-27T06:23:42.326Z", "key": "AWSAccessKeyId=accesskey", "runtime": "javascript", "origin": "manual" }, { "name": "1d2cdc0d6ebd435c91315c6329d12eab_javascript_automatic", "size": 12900705, "modified": "2024-06-26T07:05:40.000Z", "key": "AWSAccessKeyId=accesskey", "runtime": "javascript", "origin": "automatic" } ] } ``` The format of the URL to download the desired snapshot is: [https://snapshots.squarecloud.app/applications/\{accountID}/\{name}.zip?\{key}](https://snapshots.squarecloud.app/applications/\{accountID}/\{name}.zip?\{key}) ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_SCOPE` | 400 | The `scope` query parameter is not `applications` or `databases`. | | `UPGRADE_REQUIRED` | 402 | The account has no active plan; listing snapshots requires one. | | `RATE_LIMITED` | 429 | The rate limit was reached. Wait and retry. | ## Related * SDKs: [`api.account.snapshots()`](/en/sdks/js/snapshots) (JavaScript), [`client.account.snapshots()`](/en/sdks/py/snapshots) (Python), [`c.Account.Snapshots()`](/en/sdks/go/snapshots) (Go) # API error codes and how to fix them Source: https://docs.squarecloud.app/en/api-reference/errors Every error code the Square Cloud API returns, grouped by area, with its HTTP status, what it means and what to do next, plus the rules for retries. Every failed request to the Square Cloud API answers with an HTTP status and a JSON body that carries a machine-readable `code`. This page lists every code, grouped by area. Each endpoint page also lists the codes that endpoint returns most often. [Blob Storage](/en/blob-reference/errors) has its own list of codes, and the [AI Gateway](/en/api-reference/ai-gateway#errors) answers in the OpenAI error format with lowercase codes. Neither is covered here. ## Error format ```json theme={"system"} { "status": "error", "code": "APP_NOT_FOUND", "message": "Optional explanation for humans." } ``` | Field | Description | | - | - | | `status` | Always `"error"` on a failure. | | `code` | The error code, in `UPPER_SNAKE_CASE`. Branch on this field. | | `message` | Optional. A human-readable explanation that may change at any time, so show it to people but never parse it. | The list of codes grows over time. Treat a code you don't know as a generic failure of the HTTP status it came with: fix the request on a `4xx`, wait on a `429`, and retry later on a `5xx`. ## Retries The API sends no `Retry-After` header (the [AI Gateway](/en/api-reference/ai-gateway#retries) is the exception), so the decision is yours. A safe policy: | Answer | What to do | | - | - | | `400`, `401`, `403`, `404`, `409`, `413`, `415` | Don't retry the same request: it fails the same way. Fix the input, the credential or the plan first. | | `429` | Wait before the next request. Retrying in a loop keeps you blocked. See [Rate limits](#rate-limits). | | `503 UPLOAD_BUSY`, `503 ANALYTICS_BUSY` | Retry after a short pause, with exponential backoff. | | `503 DATABASE_UNAVAILABLE` | Retry a read after a few seconds. A write may already have been applied, so check the resource before you repeat it. | | `500` and other `5xx` | Retry once or twice with backoff. If it keeps failing, check the [service status](/en/api-reference/endpoint/service/status). | `202 SNAPSHOT_PROCESSING` keeps the error envelope for compatibility, but it is **not a failure**: the snapshot is still being generated and shows up in the listing on its own. Don't request it again. ## Rate limits Two codes answer `429`, and they mean different things: * **`RATE_LIMITED`**: the request budget of your account or API key, counted per 60 seconds and set by your plan (see the [per-plan values](/en/api-reference/limitations-and-restrictions#api-limits)). Past it, the API refuses your requests for up to 30 minutes. A few endpoints also answer `RATE_LIMITED` for their own limits, and an IP address that keeps sending API keys that belong to no account is blocked for a short period. * **`KEEP_CALM`**: one endpoint's own limit, such as one restart every few seconds. Wait a moment and try again. The limit of each endpoint is on its page. ## Authentication and permissions | Code | HTTP | Meaning and fix | | - | - | - | | `ACCESS_DENIED` | 401 | The API key is missing, mistyped, revoked or expired, or its account no longer exists. Check the key in your [account security settings](https://squarecloud.app/en/account/security) and don't retry in a loop. | | `MISSING_SCOPE` | 403 | The key is valid but lacks the scope this endpoint needs. Scopes can't be edited, so create a key with that scope. See [Scopes](/en/api-reference/authentication#scopes). | | `RESOURCE_NOT_ALLOWED` | 403 | The key is restricted to applications and databases that don't include this one, or the endpoint is account-wide and the key is restricted. Use a key that covers the resource. | | `PERMISSION_DENIED` | 403 | Your workspace role doesn't allow this action on a shared application, such as reading `.env` without the `admin` role. See [workspace roles](/en/api-reference/endpoint/workspace/members/invite#roles). | | `SCOPE_NOT_GRANTABLE` | 403 | A restricted API key tried to grant more access than it holds, for example adding an `admin` member with a key that lacks `envs:write`. Use a key that holds every scope of that role, or the dashboard. | | `UPGRADE_REQUIRED` | 402 / 403 | The feature needs a higher plan: databases, custom domains and workspaces need Standard or above, network logs and performance need Pro or above, and listing account snapshots needs an active plan (`402`). The `message` names the plan when it can. | ## Request validation | Code | HTTP | Meaning and fix | | - | - | - | | `INVALID_JSON_BODY` | 400 | The body is not valid JSON. Send `Content-Type: application/json` and a well-formed body. | | `INVALID_INPUT` | 400 | A field failed validation. The `message` says which. | | `INVALID_ID` | 400 | A required id, usually `workspaceId`, is missing or malformed. | | `INVALID_CONTENT_TYPE` | 415 | Upload and commit need `multipart/form-data` with the zip in a `file` field. | | `PAYLOAD_TOO_LARGE` | 413 | The body is larger than this endpoint accepts. | | `ROUTE_NOT_FOUND` | 404 | The path or the HTTP method is wrong. Compare it with the endpoint page. | ## Quotas and connection limits | Code | HTTP | Meaning and fix | | - | - | - | | `RATE_LIMITED` | 429 | The request budget of your account or key was reached, or an endpoint's own limit. See [Rate limits](#rate-limits). | | `KEEP_CALM` | 429 | Too many requests to this endpoint in a short time. Wait a moment and retry. | | `DAILY_SNAPSHOTS_LIMIT_REACHED` | 429 | The plan's allowance of manual snapshots per 24 hours is used up. Wait before the next one, or upgrade for a larger allowance. | | `REALTIME_MAX_CONNECTIONS` | 429 | Your account already has 5 [realtime](/en/api-reference/endpoint/apps/realtime) connections open. Close one first. | | `REALTIME_MAX_CONNECTIONS_APP` | 429 | The application already has 30 realtime connections open across all users. | ## Applications | Code | HTTP | Meaning and fix | | - | - | - | | `APP_NOT_FOUND` | 404 | The application doesn't exist, isn't yours, or you are not a member of the workspace it is shared in. Check the id. Workspace routes answer `400` when `appId` is missing from the body. | | `CONTAINER_ALREADY_STARTED` | 409 | The application or database is already running. You can treat it as a success. | | `CONTAINER_ALREADY_STOPPED` | 409 | The application or database is already stopped. You can treat it as a success. | | `CONTAINER_TEMPORARILY_SUSPENDED` | 409 | The resource is suspended. Check the email of the account for the reason. | | `CONTAINER_NOT_FOUND` | 409 | The resource's container wasn't found on its server. Try again in a moment, and contact support if it persists. | | `CONTAINER_INSUFFICIENT_DISK_SPACE` | 409 | There isn't enough disk space to start. Remove files you don't need and try again. | | `CONTAINER_NETWORK_CONFLICT` | 409 | A network or port conflict stopped the start. Try again in a moment. | | `ACTION_FAILED` | 409 | The start, stop or restart was refused for another reason, for example during a deploy. Check the status and retry. | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is running on this resource. Wait for it to finish before you start, stop, restart or delete the application, or start, stop or delete the database. | | `DELETE_FAILED` | 404 | The node that hosts the resource refused the deletion. Retry. On the file manager, the same code answers `400`. | | `LOGS_UNAVAILABLE` | 404 | The logs couldn't be read: the application is offline, was never deployed, or the node didn't answer. Retry shortly. | | `METRICS_NOT_SUPPORTED` | 400 | Metrics are collected only for applications with at least 512 MB of RAM. | ## Upload and commit | Code | HTTP | Meaning and fix | | - | - | - | | `INVALID_FILE` | 400 | The form has no file in the `file` field. | | `INVALID_FILENAME` | 400 | The file name has path separators, `..` or control characters. | | `INVALID_PATH` | 400 | The `path` of a commit contains traversal or shell characters. | | `FILE_TOO_LARGE` | 413 | The zip is over 100 MB. | | `UPLOAD_ABORTED` | 400 | The connection closed before the upload finished. Upload again. | | `UPLOAD_BUSY` | 503 | Too many uploads are in progress on the platform. Retry after a short pause. | | `STORAGE_UPLOAD_FAILED` | 400 | The zip couldn't be stored. Retry later. | | `UPLOAD_FAILED` | 400 | The upload couldn't be processed. Retry, and check the zip if it happens again. When the message says the result could not be confirmed, the application may still be being created: check your application list before retrying, or you may end up with a duplicate. | | `COMMIT_FAILED` | 400 | The commit couldn't be applied. Retry, and check the zip if it happens again. | | `INSUFFICIENT_MEMORY` | 400 | Your plan doesn't have enough free memory for the application or database, or `MEMORY` is below the minimum: 256 MB, or 512 MB for a website with a `SUBDOMAIN`. Adjust `MEMORY`, delete something, or upgrade. | | `CLUSTER_SELECTION_FAILED` | 400 | No server had room for the new application or database right now. Retry later. | | `CLUSTER_MAINTENANCE_TRY_LATER` | 503 | New applications and databases are paused for maintenance. Retry later. | | `EMPTY_RESPONSE` | 400 | The server that received the upload gave no usable answer, so the application was not created. Upload again. | ## Zip and configuration checks When you [upload](/en/api-reference/endpoint/apps/upload) an application, the server that will run it checks the zip and its [configuration file](/en/getting-started/config-file) (`squarecloud.app` or `squarecloud.config`). A failed check answers `400` with one of these codes, and nothing is deployed. Fix the zip and upload it again. A [commit](/en/api-reference/endpoint/apps/commit) doesn't read the configuration file: it can only fail with `FAILED_EXTRACT` or `CONTAINER_INSUFFICIENT_DISK_SPACE` from this list. | Code | HTTP | Meaning and fix | | - | - | - | | `FAILED_EXTRACT` | 400 | The zip couldn't be extracted. Create it again with a standard zip tool and check that it isn't damaged. | | `DOWNLOAD_FAILED` | 400 | The server couldn't fetch the zip after it was received. Upload again. | | `MISSING_CONFIG` | 400 | The zip has no `squarecloud.app` or `squarecloud.config` at its root, or the file is empty. | | `MISSING_MEMORY`, `MISSING_DISPLAY_NAME`, `MISSING_VERSION` | 400 | A required field of the configuration file is missing or empty. The code names the first one missing. | | `MISSING_MAIN` | 400 | The configuration has neither [`MAIN`](/en/getting-started/config-file#main) nor [`RUNTIME`](/en/getting-started/config-file#runtime). Set one of them. | | `INVALID_MAIN` | 400 | `MAIN` has characters other than letters, digits, `_`, `.`, `/` and `-`, or more than 32 characters. Without `RUNTIME`, it also fails when the file isn't in the zip, is empty, points outside the project, or has no extension or one that matches no supported language. | | `INVALID_RUNTIME` | 400 | `RUNTIME` is not one of the supported values listed in the [configuration file](/en/getting-started/config-file#runtime) reference. | | `INVALID_VERSION` | 400 | `VERSION` must be `recommended` or `latest`. An exact version number is refused. | | `INVALID_START` | 400 | `START` is longer than 256 characters. | | `INVALID_DEPENDENCY` | 400 | The dependency file of the language is missing or empty: `package.json` for JavaScript and TypeScript, `requirements.txt` or `pyproject.toml` for Python, `go.mod` or `go.work` for Go, `Cargo.toml` for Rust, `Gemfile` for Ruby, `mix.exs` for Elixir. | | `INVALID_DISPLAY_NAME` | 400 | `DISPLAY_NAME` must have 1 to 32 characters: letters, digits, spaces, `_` and `-`. | | `INVALID_DESCRIPTION` | 400 | `DESCRIPTION` is longer than 280 characters. | | `INVALID_SUBDOMAIN` | 400 | `SUBDOMAIN` is malformed, reserved or already taken. Pick another. | | `CONTAINER_INSUFFICIENT_DISK_SPACE` | 400 | On a commit, there isn't enough disk space for the new files. Delete files you don't need and commit again. | | `ACCESS_FORBIDDEN` | 400 | The server couldn't load your account for this upload. Retry, and contact support if it persists. | ## Environment variables | Code | HTTP | Meaning and fix | | - | - | - | | `STATIC_APP_ENV_NOT_SUPPORTED` | 400 | Static sites don't support environment variables. | | `INVALID_ENV_CONTENT` | 400 | `envs` is missing or has the wrong shape: an object to add or replace, an array of keys to remove. | | `TOO_MANY_ENV_VARS` | 400 | The application would have more than 256 variables. | | `ENV_NAME_TOO_LONG` | 400 | A key is longer than 1024 characters, or is not a string. | | `ENV_CONTENT_TOO_LONG` | 400 | A value is longer than 4096 characters. | | `READ_FAILED` | 400 | The variables couldn't be read from the application. Retry. The certificate route uses the same code. | ## Files | Code | HTTP | Meaning and fix | | - | - | - | | `INVALID_PATH` | 400 | The path has traversal or invalid characters, is longer than 256 characters, or the source and destination of a move are the same. | | `BLOCKED_PATH` | 403 | The path is in a protected directory, or your workspace role can't write that file. | | `INVALID_ENCODING` | 400 | `encoding` accepts only `base64`. | | `INVALID_CONTENT` | 400 | `content` is missing, has an unsupported shape, or isn't valid base64. | | `FILE_NOT_FOUND` | 404 | There is no file or directory at that path. | | `FILE_TOO_LARGE` | 413 | The file manager reads and writes files of up to 10 MB. Use [commit](/en/api-reference/endpoint/apps/commit) for bigger files. | | `RENAME_FAILED` | 400 | The file couldn't be moved or renamed. Retry. | | `DELETE_FAILED` | 400 | The file couldn't be deleted. Retry. | | `INVALID_DISPLAY_NAME`, `INVALID_DESCRIPTION`, `INVALID_MEMORY`, `INVALID_AUTORESTART`, `INVALID_SUBDOMAIN` | 400 | A write to the [configuration file](/en/getting-started/config-file) has a field that fails validation, or a `SUBDOMAIN` that is already taken. Fix that field. | | `CANNOT_SET_SUBDOMAIN` | 400 | The configuration of a website has no `SUBDOMAIN`. A website always keeps one, so set it back. | | `SAVE_FAILED` | 500 | The new configuration couldn't be saved. Retry. | ## Deploys and GitHub | Code | HTTP | Meaning and fix | | - | - | - | | `GIT_REF_NOT_SUPPORTED` | 202 | The [Git webhook](/en/api-reference/endpoint/apps/deploy/webhooks) received a push of a tag or another ref that isn't a branch. Nothing was deployed, and the push didn't use up the webhook's rate limit. | | `GIT_BRANCH_DELETED` | 202 | The [Git webhook](/en/api-reference/endpoint/apps/deploy/webhooks) received a push that deletes a branch. Nothing was deployed, and the push didn't use up the webhook's rate limit. | | `INVALID_ACCESS_TOKEN` | 400 | The webhook token is neither a GitHub token (`ghp_...`, `github_pat_...`) nor `@`. | | `MISSING_REQUIRED_FIELDS` | 400 | `repositoryName` or `repositoryBranch` is missing. | | `INVALID_BRANCH_LENGTH` | 400 | The branch name is longer than 256 characters. | | `BRANCH_NOT_FOUND` | 400 | The branch doesn't exist in the repository. | | `GIT_ALREADY_CONFIGURED` | 400 | The application already has a linked repository. Unlink it first. | | `GIT_NOT_CONFIGURED` | 400 | The application has no linked repository to unlink. | | `GITHUB_NOT_CONNECTED` | 403 | Your Square Cloud account has no working GitHub connection. Connect or reconnect GitHub in the dashboard. | | `REPOSITORY_NOT_AVAILABLE` | 403 | The Square Cloud GitHub App isn't installed on the repository through your GitHub account. | | `REPOSITORY_PERMISSION_REQUIRED` | 403 | Your GitHub account needs write access to the repository. | | `REPOSITORY_NOT_FOUND` | 404 | The repository doesn't exist or your GitHub account can't see it. | | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 409 | Another application, of any account, already uses this repository and branch. | | `FAILED_TO_FETCH` | 502 | GitHub didn't confirm the branch. Retry. | | `VALIDATION_FAILED` | 500 / 502 | The repository couldn't be validated. Retry. | | `VALIDATION_TIMEOUT` | 504 | Validating the repository took too long. Retry. | A failed Git deploy is not an HTTP error: it shows up in the [deploy history](/en/api-reference/endpoint/apps/deploy/list) as an event with `state: "error"` and a `code` such as `DEPLOY_FAILED`. ## Network and domains | Code | HTTP | Meaning and fix | | - | - | - | | `INVALID_TIME_RANGE` | 400 | `start` or `end` is missing or malformed, or `start` is after `end`. | | `INVALID_FILTER` | 400 | A filter of the analytics endpoint has the wrong format. | | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | 500 | The edge provider didn't return the data. Retry later. | | `ANALYTICS_BUSY` | 503 | Network analytics are busy across the platform. Retry after a short pause. | | `NO_CUSTOM_DOMAIN` | 400 | The application has no custom domain, so it has no DNS records to show. | | `INVALID_DOMAIN` | 400 | The value is not a valid domain name. | | `RESERVED_DOMAIN` | 400 | Square Cloud's own domains and their subdomains can't be used as a custom domain. | | `DOMAIN_ALREADY_EXISTS` | 409 | Another account already uses this domain. Remove it there first. | | `LOAD_BALANCER_LIMIT_REACHED` | 403 | Your plan doesn't allow this domain on more applications. The `message` gives the limit. | | `DNS_FAILED` | 502 | The edge provider couldn't attach the domain. Your previous domain stays in place. Retry. | | `PURGE_CACHE_FAILED` | 500 | The cache purge didn't complete. Retry in a moment. | ## Snapshots | Code | HTTP | Meaning and fix | | - | - | - | | `SNAPSHOT_PROCESSING` | 202 | Not an error: the snapshot is still being generated. Check the listing in a couple of minutes. | | `SNAPSHOT_FAILED` | 404 | The snapshot couldn't be created. Retry later. | | `MISSING_PARAMETERS` | 400 | `snapshotId` or `versionId` is missing. | | `INVALID_SNAPSHOT_ID` | 400 | `snapshotId` is not a `name` from the snapshot listing. | | `INVALID_VERSION_ID` | 400 | `versionId` is not a `version_id` from the snapshot listing. | | `SNAPSHOT_NOT_FOUND` | 404 | No snapshot matches that id and version. | | `SNAPSHOT_RESTORE_FAILED` | 404 | The restore failed. Retry, or restore another snapshot. | | `SNAPSHOT_DATABASE_MISMATCH` | 400 | The snapshot is from a different database engine than the target database. | | `INVALID_SCOPE` | 400 | The `scope` of the account snapshot listing must be `applications` or `databases`. | ## Databases | Code | HTTP | Meaning and fix | | - | - | - | | `DATABASE_NOT_FOUND` | 404 | The database doesn't exist or isn't yours. | | `INVALID_NAME` | 400 | The name must have 1 to 32 characters. Workspaces follow the same rule. | | `INVALID_DATABASE_TYPE` | 400 | `type` must be `mongo`, `mysql`, `postgres` or `redis`. | | `INVALID_DATABASE_VERSION` | 400 | The version isn't available for that engine. | | `INVALID_MEMORY` | 400 | The memory isn't valid for this engine or plan. | | `DATABASE_CREATION_FAILED` | 400 / 500 | The database couldn't be created. Nothing was left behind, so you can retry. | | `DATABASE_NOT_RUNNING` | 400 | Start the database before you read its certificate or reset its credentials. | | `INVALID_RESET_TYPE` | 400 | `reset` must be `password` or `certificate`. | | `RESET_FAILED` | 500 | The credentials couldn't be reset. Retry. | | `NO_UPDATE_DATA` | 400 | Send `name`, `ram` or both to update a database. | ## Workspaces | Code | HTTP | Meaning and fix | | - | - | - | | `WORKSPACE_NOT_FOUND` | 404 | The workspace doesn't exist, or you are neither its owner nor a member. | | `WORKSPACE_LIMIT_REACHED` | 400 | Your account already has the most workspaces its plan allows. | | `WORKSPACE_CREATION_FAILED` | 400 | The workspace couldn't be created. Retry. | | `INVALID_CODE` | 400 | The invite code is missing, malformed or expired. Ask the person for a new one. | | `INVALID_GROUP` | 400 | `group` must be `view`, `manager`, `maintain` or `admin`. | | `CANNOT_INVITE_OWNER` | 400 | The invite code is yours, and you already own the workspace. | | `CANNOT_EDIT_OWNER` | 400 | The owner's role can't be changed. | | `CANNOT_LEAVE_OWNER` | 400 | The owner can't leave the workspace. Delete it instead. | | `MEMBERS_LIMIT_REACHED` | 400 | The workspace already has the most members the owner's plan allows. | | `MEMBER_ALREADY_ADDED` | 400 | That person is already a member. | | `MEMBER_NOT_FOUND` | 400 / 404 | `memberId` is missing (`400`) or that person isn't a member anymore (`404`). | | `APPLICATIONS_LIMIT_REACHED` | 400 | The workspace already shares 100 applications. | | `APP_ALREADY_IN_WORKSPACE` | 400 | The application is already shared in this workspace. | ## Platform | Code | HTTP | Meaning and fix | | - | - | - | | `INTERNAL_SERVER_ERROR` | 500 | An unexpected failure. Retry once, and contact support if it persists. | | `DATABASE_UNAVAILABLE` | 503 | The platform database is briefly unavailable. Retry in a few seconds. An existing resource is never reported as not found in this state. | | `CLUSTER_TIMEOUT` | 400 | The server that hosts the resource didn't answer in time. Retry. | | `CLUSTER_UNAVAILABLE` | 400 | The server that hosts the resource can't be reached right now. Retry shortly. | | `REQUEST_ABORTED` | 400 | The request was cancelled before the server that hosts the resource answered. Retry. | | `INVALID_PARAMETERS` | 400 | An internal request was malformed. Retry, and contact support if it persists. | The `AI_*` codes (`AI_DAILY_LIMIT_REACHED`, `AI_WEEKLY_LIMIT_REACHED`, `AI_NO_PLAN_LIMIT_REACHED`, `AI_MAX_CONCURRENT_STREAMS`, `AI_UNAVAILABLE`) belong to the dashboard's AI assistant, which needs a dashboard session. An API key never receives them. ## Related * [Authentication and scopes](/en/api-reference/authentication) * [Rate limits per plan](/en/api-reference/limitations-and-restrictions) * JavaScript SDK: [`SquareCloudAPIError`](/en/sdks/js/errors) * Python SDK: [`SquareCloudAPIError`](/en/sdks/py/errors) * Go SDK: [`*APIError`](/en/sdks/go/errors) # Square Cloud API: base URL and first request Source: https://docs.squarecloud.app/en/api-reference/introduction 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: ``` 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 `-` in the path, for example `/v2/apps/-/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. 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. ## Next steps Pick the scopes each integration needs. Every code the API returns and how to handle it. Deploy a zip with one request. Request budgets per plan. # API rate limits and regional restrictions Source: https://docs.squarecloud.app/en/api-reference/limitations-and-restrictions Per-plan request limits of the Square Cloud API, the countries blocked by sanctions or regulations, and the countries that must solve a captcha first. Due to regulations, local laws, security and privacy issues, certain countries may be blocked from accessing our services and APIs. We are constantly working to expand our services to more countries, but we cannot guarantee that we will be able to provide services in your country. ## Blocked countries by sanctions or regulatory restrictions The following countries are currently blocked from accessing our services and APIs due to sanctions and regulatory restrictions: | Country | Code | Reason | | :- | :- | :- | | Afghanistan | AF | Regulatory restrictions | | Belarus | BY | Regulatory restrictions | | Cuba | CU | Regulatory restrictions | | China | CN | Regulatory restrictions | | Iran | IR | Regulatory restrictions | | North Korea | KP | Regulatory restrictions | | Russia | RU | Regulatory restrictions | | Syria | SY | Regulatory restrictions | | Antarctica | AQ | Regulatory restrictions | | All TOR IP's | T1 | Regulatory restrictions | ## Captcha countries The following countries are required to solve a captcha before accessing our services and APIs: | Country | Code | Reason | | :- | :- | :- | | Bangladesh | BD | Security reasons | | India | IN | Security reasons | | Iraq | IQ | Security reasons | | Philippines | PH | Security reasons | | Ukraine | UA | Security reasons | | Venezuela | VE | Security reasons | | Vietnam | VN | Security reasons | | Indonesia | ID | Security reasons | | Malaysia | MY | Security reasons | ## API limits Illegal or abusive use of our API may result in your account being blocked. If you are rate limited, you will receive a `429 Too Many Requests` response. If you receive this response, you should wait **30 minutes before making another request**. Applications hosted **outside of Square Cloud** have a **maximum** rate limit of **300 requests per minute**. On routes that take a large body, such as `PUT /v2/apps/{appId}/files` and `POST`/`PUT /v2/apps/{appId}/envs`, authentication, permission and rate-limit errors are returned before the body is validated, and an invalid body counts toward the endpoint's rate limit. The API is subject to rate limits (subject to change). The current rate limits are: | Account Plan | Rate Limit (60s) | Max daily requests | | :- | :-: | :-: | | HOBBY-1 | 30 requests | 43,200 requests | | HOBBY-2 | 60 requests | 86,400 requests | | STANDARD-4 | 120 requests | 172,800 requests | | STANDARD-6 | 180 requests | 259,200 requests | | STANDARD-8 | 240 requests | 345,600 requests | | PRO-12 | 300 requests | 432,000 requests | | PRO-16 | 300 requests | 432,000 requests | | PRO-24 | 360 requests | 518,400 requests | | ENTERPRISE-32 | 480 requests | 691,200 requests | | ENTERPRISE-48 | 720 requests | 1,036,800 requests | | ENTERPRISE-64 | 960 requests | 1,382,400 requests | | ENTERPRISE-96 | 1,200 requests | 1,728,000 requests | | ENTERPRISE-128 | 1,600 requests | 2,304,000 requests | | ENTERPRISE-160 | 2,000 requests | 2,880,000 requests | | ENTERPRISE-192 | 2,400 requests | 3,456,000 requests | | ENTERPRISE-224 | 2,800 requests | 4,032,000 requests | | ENTERPRISE-256 | 3,200 requests | 4,608,000 requests | | ENTERPRISE-288 | 3,600 requests | 5,184,000 requests | | ENTERPRISE-320 | 4,000 requests | 5,760,000 requests | | ENTERPRISE-384 | 4,800 requests | 6,912,000 requests | | ENTERPRISE-448 | 5,600 requests | 8,064,000 requests | | ENTERPRISE-512 | 6,400 requests | 9,216,000 requests | | ENTERPRISE-640 | 8,000 requests | 11,520,000 requests | | ENTERPRISE-768 | 9,600 requests | 13,824,000 requests | | ENTERPRISE-1024 | 12,800 requests | 18,432,000 requests | It is important to note that these API usage limits are set to ensure that the Square Cloud platform can be used equitably by all users and to protect the integrity of the systems. If you need more requests per minute or other broader limitations, it may be possible to upgrade to a higher tier plan that offers these additional features. # Square Cloud API OpenAPI specification Source: https://docs.squarecloud.app/en/api-reference/openapi Get the machine-readable OpenAPI specification of the Square Cloud API at GET /v2/openapi.json to generate clients or import it into Postman or Insomnia. # Blob SDK: install and create the client Source: https://docs.squarecloud.app/en/sdks/blob/client Install @squarecloud/blob and create a SquareCloudBlob client with an API key or an upload token. The only option is maxRetries. This page documents **`@squarecloud/blob` v4**. Upgrading from v3? Read the [v3 → v4 migration guide](/en/sdks/blob/migrating_to_v4). `@squarecloud/blob` is the official JavaScript SDK for [Square Cloud Blob Storage](/en/services/blob). It covers every [Blob API](/en/blob-reference/authentication) endpoint plus the [S3 gateway](/en/blob-reference/s3-compatibility). ## Requirements * **Node.js 20** or newer, or any modern browser. The SDK only uses `fetch`, `FormData` and `Blob`. * Ships as **ESM and CommonJS**, with **zero runtime dependencies**. * `@aws-sdk/client-s3` is an **optional peer dependency**, only needed if you call [`s3()`](/en/sdks/blob/s3). ## Installation ```bash theme={"system"} npm install @squarecloud/blob ``` ```bash theme={"system"} yarn add @squarecloud/blob ``` ```bash theme={"system"} pnpm add @squarecloud/blob ``` ```bash theme={"system"} bun add @squarecloud/blob ``` ## Creating the client The examples read the key from the `SQUARECLOUD_API_KEY` environment variable. Set it in the terminal where you run them: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` ```powershell theme={"system"} $env:SQUARECLOUD_API_KEY = "your-api-key" ``` ```typescript theme={"system"} import { SquareCloudBlob } from "@squarecloud/blob"; const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); ``` ```javascript theme={"system"} const { SquareCloudBlob } = require("@squarecloud/blob"); const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); ``` Check the client with a first call. `stats()` reads your usage: ```typescript theme={"system"} const { usage } = await blob.stats(); console.log(`${usage.objects} objects, ${usage.storage} bytes`); ``` It prints the number of objects and the bytes they use, for example: ```text theme={"system"} 12 objects, 5242880 bytes ``` ### Constructor ```typescript theme={"system"} new SquareCloudBlob(credential, { maxRetries: 2 }); ``` | Parameter | Type | Default | Description | | - | - | - | - | | `credential` | `string` | required | An **API key**, or an **upload token** (`squp_...`) that can only call `put()`. | | `options.maxRetries` | `number` | `2` | How many times a safe-to-repeat request (a `GET` or a multipart part) is retried after a network error or a `5xx`. `0` disables retries. See [Retry policy](/en/sdks/blob/errors#retry-policy). | ## Credentials The credential is sent **as-is** in the `Authorization` header, with no `Bearer` prefix. | Credential | Where it comes from | What it can do | | - | - | - | | API key | [Square Cloud dashboard](https://squarecloud.app/en/account/security) | Every method, subject to its `blob:read` / `blob:write` [scopes](/en/blob-reference/authentication#scopes). | | Upload token (`squp_...`) | [`blob.uploadTokens.create()`](/en/sdks/blob/uploads#uploading-from-the-browser), on your server | Only `put()`. Any other method fails with `403 UPLOAD_TOKEN_NOT_ALLOWED`. | Never ship an API key to a browser. Mint an upload token on your server and hand only the token to the client. ## What you cannot configure `maxRetries` is the **only** option. The client does not accept: * **A base URL.** It is fixed at `https://blob.squarecloud.app/v1/`. * **A custom `fetch`.** Requests use the global `fetch`. * **A timeout or an `AbortSignal`.** A call lasts as long as `fetch` waits, and there is no way to cancel it. * **Custom headers.** ## Methods Every method returns plain data (no classes), except `s3()`, which returns an `S3Client`. Options and results use the API's own field names, mostly snake\_case (`security_hash`, `expires_at`), so the [Blob API reference](/en/blob-reference/authentication) applies as-is. | Group | Methods | Page | | - | - | - | | `blob` | `put(file, options)` | [Uploads](/en/sdks/blob/uploads) | | `blob.uploadTokens` | `create(options)` | [Uploads](/en/sdks/blob/uploads#uploading-from-the-browser) | | `blob` | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Objects](/en/sdks/blob/objects) | | `blob.shares` | `create(object, options)`, `list()`, `revoke(id)` | [Sharing](/en/sdks/blob/sharing) | | `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()` | [Rules and stats](/en/sdks/blob/rules_and_stats) | | `blob` | `s3Credentials()`, `s3()` | [S3](/en/sdks/blob/s3) | The package also exports `SquareCloudBlobError`, the `BlobErrorCode` type and every option and result type (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). See [Errors](/en/sdks/blob/errors). ## Object ids Every object is identified by an **opaque id**, such as `pub/...` for a public object or `prv/...` for a private one. * **Store the id exactly as returned.** Never build one by hand and never parse it. * **Changing `private` or `expire` changes the id.** Always replace your stored id with the one [`update()`](/en/sdks/blob/objects#updating-objects) returns. * **Use the `url` from the response** instead of building URLs. Private objects have `url: null`: get a link with [`downloadUrl()`](/en/sdks/blob/objects#download-links) or a [share](/en/sdks/blob/sharing). ```typescript theme={"system"} const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" }); // save `id` as-is; use `url` to serve the file ``` ## Next steps Upload files and mint upload tokens. Base URL and a first upload with curl. What each plan includes. # Blob SDK: errors and retries Source: https://docs.squarecloud.app/en/sdks/blob/errors SquareCloudBlobError, the BlobErrorCode list, network errors that are not wrapped, and exactly which calls @squarecloud/blob retries. ## `SquareCloudBlobError` Every API failure throws a `SquareCloudBlobError`. | Property | Type | Description | | - | - | - | | `status` | `number` | HTTP status of the response. | | `code` | `BlobErrorCode` | The API error code, e.g. `OBJECT_NOT_FOUND`. | | `message` | `string` | The server's explanation, or the code when there is none. | | `extra` | `Record` | Every other field of the error body, e.g. `prefix` on rule errors. | | `isUpgradeRequired()` | `() => boolean` | `true` for `UPGRADE_REQUIRED`, the code of every plan refusal (limit, feature or plan). The `message` says which. | ```typescript theme={"system"} import { SquareCloudBlob, SquareCloudBlobError } from "@squarecloud/blob"; const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); try { await blob.shares.create(id, { password: "secret123" }); } catch (error) { if (error instanceof SquareCloudBlobError) { if (error.isUpgradeRequired()) { console.error(error.message); // your plan lacks this feature or limit } else if (error.code === "OBJECT_NOT_FOUND") { // ... } else { console.error(error.status, error.code, error.extra); } } else { throw error; // network error or file error, see below } } ``` ### What is not a `SquareCloudBlobError` * **Network errors are not wrapped.** When a request gets no complete response (DNS failure, connection reset, a body cut off mid-read), the original `fetch` error is thrown as-is, after any [retries](#retry-policy). * **File errors.** In Node.js, a `put()` path that cannot be opened throws a plain `Error` (`Cannot open file: `, original error in `cause`). In a browser, a path fails with the error from importing `node:fs`. * **A missing `@aws-sdk/client-s3`.** [`s3()`](/en/sdks/blob/s3) throws the module import error. ### `UNKNOWN_ERROR` `UNKNOWN_ERROR` is the **only code the SDK creates itself**. It is used when the response has no error code: a non-JSON body (a proxy error page, for example) or a `2xx` response without `status: "success"`. `status` still holds the real HTTP status. ### Per-object failures Batch operations report failures in their result instead of throwing: * [`update()`](/en/sdks/blob/objects#updating-objects): each result has `ok: false` and a `code`. * [`delete([ids])`](/en/sdks/blob/objects#deleting): missing objects go to `not_found`, other failures to `failed`. ## Error codes `BlobErrorCode` is the Blob Storage API's own list of codes. It is **not** the same list as the main Square Cloud API's error codes. For each code's HTTP status and meaning, see the [Blob API errors reference](/en/blob-reference/errors). `ACCESS_DENIED`, `RATE_LIMITED`, `MISSING_SCOPE`, `RESOURCE_NOT_ALLOWED`, `UPLOAD_TOKEN_NOT_ALLOWED`, `UPLOAD_TOKEN_USED`, `PREFIX_NOT_ALLOWED`, `PERMISSION_DENIED`, `ACCOUNT_BLOCKED`, `UPGRADE_REQUIRED`, `STORAGE_QUOTA_EXCEEDED`, `PRIVATE_STORAGE_UNAVAILABLE`, `PUBLIC_STORAGE_UNAVAILABLE`, `TOO_MANY_CONCURRENT_UPLOADS`, `UPLOAD_FAILED`, `INTERNAL_SERVER_ERROR`, `NOT_FOUND` `RATE_LIMIT` is **deprecated**: the service no longer sends it (see `RATE_LIMITED`), but it stays in the type. `OBJECT_NOT_FOUND`, `OBJECT_ALREADY_EXISTS`, `OBJECT_IS_LEGACY`, `CHECKSUM_MISMATCH`, `INVALID_CONTENT_TYPE`, `FILE_TOO_LARGE`, `FILE_TOO_SMALL`, `BLOCKED_FILE_TYPE`, `INVALID_FILE_TYPE`, `FILE_TYPE_NOT_ALLOWED`, `NOTHING_TO_UPDATE`, `VISIBILITY_CHANGE_FAILED`, `UPDATE_FAILED`, `DELETE_FAILED`, `TOO_MANY_OBJECTS`, `SAME_OBJECT`, `INVALID_DESTINATION`, `COPY_FAILED`, `PREFIX_REQUIRED`, `INVALID_CONTINUATION_TOKEN` `TOO_MANY_CONCURRENT_CHUNKS`, `TOO_MANY_OPEN_UPLOADS`, `INVALID_UPLOAD_TOKEN`, `UPLOAD_NOT_FOUND`, `NO_CHUNKS_UPLOADED`, `EMPTY_CHUNK`, `INVALID_CHUNK_PART`, `CHUNK_TOO_SMALL`, `CHUNK_TOO_LARGE` `TOO_MANY_RULES`, `DUPLICATE_RULE_PREFIX`, `INVALID_RULES`, `UPLOAD_TOKEN_TOO_LARGE`, `TOO_MANY_SHARES`, `SHARE_NOT_FOUND`, `INVALID_SHARE`, `API_KEY_REQUIRED`, `LEGACY_API_KEY` Any `INVALID_*` code, such as `INVALID_OBJECT`, `INVALID_OBJECT_NAME` or `INVALID_RULE_PREFIX`. Rule errors carry the offending `prefix` in `error.extra`. `UNKNOWN_ERROR`: the response had no error code (see [above](#unknown_error)). `BlobErrorCode` also accepts any other string, so a code the service adds later still type-checks. ## Retry policy The SDK only retries what is **safe to repeat**: `GET` calls and multipart upload **parts** (each part number can be sent again). | Retried | Calls | | - | - | | **Yes**, up to `maxRetries` (default 2) | `list()`, `listPage()`, `info()`, `downloadUrl()`, `stats()`, `rules.get()`, `shares.list()`, `s3Credentials()`, and each part of a multipart `put()` | | **No**, single attempt | Simple `put()`, starting, completing and aborting a multipart upload, `update()`, `copy()`, `move()`, `delete()`, `rules.set()`, `uploadTokens.create()`, `shares.create()`, `shares.revoke()` | A retryable call is retried on: * a **network error** (including a body cut off mid-read); * **any `5xx`** response; * `TOO_MANY_CONCURRENT_CHUNKS` on a multipart part: the server refuses the part before reading it, so it is sent again within the same budget. It is **never** retried on any other `4xx`, **including `429`**. `RATE_LIMITED` can be an account block that lasts about 30 minutes, so the SDK leaves the decision to you. ### Backoff Before retry `n` (starting at 0), the SDK waits: ```text theme={"system"} min(8 s, 500 ms · 2^n) · U(0.5, 1) ``` That is, exponential backoff capped at 8 seconds, with jitter between 50 % and 100 % of the delay. With the default `maxRetries: 2`, a call makes at most 3 attempts. ### Retrying writes yourself A write that fails with a network error or a `5xx` may or may not have been applied. Retry it only when repeating it is safe for you, for example a `put()` to the same `name` with `overwrite: true`. ```typescript theme={"system"} import { SquareCloudBlobError } from "@squarecloud/blob"; async function putWithRetry(file, options, attempts = 3) { for (let i = 0; ; i++) { try { return await blob.put(file, { ...options, overwrite: true }); } catch (error) { // fetch network errors are TypeErrors; 5xx are SquareCloudBlobErrors const retryable = error instanceof SquareCloudBlobError ? error.status >= 500 : error instanceof TypeError; if (!retryable || i + 1 >= attempts) throw error; await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); } } } ``` Do not retry `429 RATE_LIMITED` in a tight loop: going over the account-wide budget can block the account for about 30 minutes. See the [Blob API errors reference](/en/blob-reference/errors). ### Timeouts There is no client timeout and no way to cancel a call: a request lasts as long as `fetch` waits. ## Next steps Every Blob error code, with its HTTP status. Credentials and client options. # Blob SDK: migrating from v3 to v4 Source: https://docs.squarecloud.app/en/sdks/blob/migrating_to_v4 What changed in @squarecloud/blob 4.0.0: a safer retry policy, fewer default retries, an optional SavedRule.active_from and a consistent one-id batch delete. Version 4.0.0 changes **how the SDK retries**, so that it only repeats what is safe to repeat. **No method, option or export was renamed or removed.** ## Requirements Unchanged: **Node.js 20** or newer, or a browser; ESM and CommonJS. ## Breaking changes summary | v3.x | v4.x | | - | - | | `429` retried | **Never retried** (except `TOO_MANY_CONCURRENT_CHUNKS` on a multipart part) | | Writes retried on network errors and `5xx` | Writes get **a single attempt** | | Retried on `500` and `503` only | Retried on **any `5xx`** (reads and multipart parts) | | `maxRetries` default `5` | Default **`2`** | | Backoff capped at 30 s | Capped at **8 s**: `min(8 s, 500 ms · 2^n) · U(0.5, 1)` | | `SavedRule.active_from: string` | `active_from?: string` (**optional**) | | `delete([id])` with one id throws `PREFIX_NOT_ALLOWED` | Reports it in `failed` | | `RATE_LIMIT` in `BlobErrorCode` | **Deprecated** (still in the type) | ## `429` is no longer retried `RATE_LIMITED` covers both a per-route window and an account or IP block that can last about 30 minutes, so the SDK no longer retries it. This includes the simple upload limit and `TOO_MANY_CONCURRENT_UPLOADS`. Handle it yourself, and wait before trying again: ```typescript theme={"system"} import { SquareCloudBlobError } from "@squarecloud/blob"; try { await blob.put(file, { name: "report" }); } catch (error) { if (error instanceof SquareCloudBlobError && error.code === "RATE_LIMITED") { // back off: queue the job for later instead of retrying right away } throw error; } ``` The one exception is `TOO_MANY_CONCURRENT_CHUNKS` on a multipart part: the server refuses the part before reading it, so the SDK sends it again within `maxRetries`. ## Writes get a single attempt Network errors and `5xx` are now retried only on `GET` calls and on multipart upload parts. These calls get **one attempt**: * simple `put()`, and starting, completing and aborting a multipart upload; * `update()`, `copy()`, `move()`, `delete()`; * `rules.set()`, `uploadTokens.create()`, `shares.create()`, `shares.revoke()`. Retry a write yourself only when repeating it is safe for you, for example a `put()` to the same name with `overwrite: true`. See [Retrying writes yourself](/en/sdks/blob/errors#retrying-writes-yourself). ## Fewer retries, shorter backoff `maxRetries` now defaults to `2` (was `5`), and the backoff is capped at 8 seconds (was 30). To keep the old budget on reads and multipart parts: ```typescript theme={"system"} const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY, { maxRetries: 5 }); ``` This does not bring back retries on `429` or on writes. ## `SavedRule.active_from` is optional The API only sends `active_from` for rules with `delete_after_days`. In TypeScript, handle `undefined`: ```typescript theme={"system"} const rules = await blob.rules.get(); for (const rule of rules) { if (rule.active_from) { console.log(`${rule.prefix} starts deleting at ${rule.active_from}`); } } ``` ## `delete([id])` with a single id A batch with one id now reports `PREFIX_NOT_ALLOWED` in `failed`, like any other batch, instead of throwing: ```typescript theme={"system"} // v3: threw SquareCloudBlobError (PREFIX_NOT_ALLOWED) // v4: const { failed } = await blob.delete([id]); // failed: [{ id, code: "PREFIX_NOT_ALLOWED" }] ``` `delete(id)` with a plain string still throws. ## `RATE_LIMIT` is deprecated The service no longer sends `RATE_LIMIT`: the account or IP block is `RATE_LIMITED`. The old code stays in `BlobErrorCode` so existing comparisons still compile; switch them to `RATE_LIMITED`. `DUPLICATE_RULE_PREFIX` was added. ## Fixes * A response body cut off mid-read is now a **network error**: it is retried on `GET` calls and multipart parts, and otherwise the original `fetch` error is thrown (it used to be `UNKNOWN_ERROR`). * A failed multipart upload now **waits for the parts still in flight** before aborting, so no part lands after the abort and no request outlives `put()`. ## Checklist Catch `RATE_LIMITED` and back off; the SDK no longer retries it. Add your own retry only to writes that are safe to repeat. Pass `{ maxRetries: 5 }` if you relied on the old number of attempts on reads and multipart parts. Handle `active_from` being `undefined`, and replace `RATE_LIMIT` with `RATE_LIMITED`. ## Next steps Install the SDK and create a client. The retry policy in detail. # Blob SDK: manage objects and links Source: https://docs.squarecloud.app/en/sdks/blob/objects List, inspect, update, delete, copy and move Blob Storage objects with the @squarecloud/blob SDK, and get permanent or temporary download links. Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client). Object ids are opaque (`pub/...`, `prv/...`). Store them as returned, never build or parse them, and replace your stored id whenever [`update()`](#updating-objects) returns a new one. See [Object ids](/en/sdks/blob/client#object-ids). ## Listing `list()` is an **async generator** that follows the cursor through every page. Order is not guaranteed. ```typescript theme={"system"} for await (const object of blob.list({ prefix: "avatars/" })) { console.log(object.id, object.size, object.url); } ``` `listPage()` fetches **one page**. Use it for manual pagination or to get `folders`: ```typescript theme={"system"} const { objects, folders, continuationToken } = await blob.listPage({ prefix: "avatars/", delimiter: "/", }); // next page if (continuationToken) { const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken }); } ``` | Option | Type | Description | | - | - | - | | `prefix` | `string` | Only objects under this prefix. | | `delimiter` | `"/"` | Groups by folder: the page also returns `folders`. | | `private` | `boolean` | Only private (`true`) or public (`false`) objects. | | `limit` | `number` | Objects per page, 1 to 1000 (default 1000). | | `cursor` | `string` | `listPage()` only: the previous page's `continuationToken`. | A page has `objects`, `folders` (only with `delimiter`) and `continuationToken` (**absent on the last page**). Each listed object has `id`, `size`, `created_at`, `expires_at`, `private`, `url` and `etag`. See [Object List](/en/blob-reference/endpoint/list). ## Object details ```typescript theme={"system"} const info = await blob.info(id); ``` Returns `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` and `legacy`. See [Object Info](/en/blob-reference/endpoint/info). `created_at` is the storage's last-modified time: an update that copies the object (visibility, expiration, headers) resets it. ## Download links ```typescript theme={"system"} const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 }); ``` * A **public** object gets its **permanent CDN URL**, with `expires_at: null`. * A **private** object, or any call with `disposition` or `filename`, gets a **temporary link** that lives `expires` seconds (up to 24 hours). A temporary link **cannot be revoked**. For revocable, password-protected or download-capped links, use a [share](/en/sdks/blob/sharing). | Option | Type | Description | | - | - | - | | `expires` | `number` | Link lifetime in seconds, 60 to 86400 (default 3600). | | `disposition` | `"inline"` \| `"attachment"` | Overrides `Content-Disposition` for this link. | | `filename` | `string` | File name the browser saves the download as. | The result has `url`, `expires_at`, `private`, `size` and `content_type`. See [Object Download](/en/blob-reference/endpoint/download). ## Updating objects `update()` changes the visibility, expiration, cache, disposition or metadata of **one object or up to 50**. It **always returns an array**, one result per object, and each result reports its own success in `ok`. ```typescript theme={"system"} const [result] = await blob.update(id, { private: true, expire: null }); if (result.ok) { id = result.id; // the id changed: store the new one } else { console.error(result.code); } ``` | Change | Type | Description | | - | - | - | | `private` | `boolean` | Makes the object private or public. **Changes the id.** | | `expire` | `string \| null` | New expiration; `null` removes it. **Changes the id.** | | `cache_control` | `string \| null` | `null` removes it. | | `disposition` | `"inline"` \| `"attachment"` \| `null` | `null` removes it. | | `metadata` | `Record \| null` | `{ key: null }` removes one key; `null` removes all. | A successful result (`ok: true`) has `object` (the id you sent), `changed`, `id` (**the id after the change**), `private`, `url`, `expires_at` and `size`. A failed result (`ok: false`) has `object` and `code`. A batch does not throw for per-object failures. See [Object Update](/en/blob-reference/endpoint/update). ## Deleting Deletion is **immediate and permanent**: there is no trash. ```typescript theme={"system"} // Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing await blob.delete(id); // Batch, up to 100 ids const { deleted, not_found, failed } = await blob.delete([id1, id2]); ``` | Call | Returns | On a missing object | | - | - | - | | `delete(id)` | `void` | Throws `SquareCloudBlobError` (`OBJECT_NOT_FOUND`). | | `delete([ids])` | `{ deleted, not_found, failed }` | Reported in `not_found`. `failed` lists `{ id, code }`. | With **a single id in an array**, the SDK still returns `{ deleted, not_found, failed }`: a missing object goes to `not_found`, and `DELETE_FAILED` or `PREFIX_NOT_ALLOWED` go to `failed` instead of throwing. Any other error (authentication, rate limit, network) still throws. See [Delete Objects](/en/blob-reference/endpoint/delete). ## Copying, moving and renaming Both run on the server, without downloading the file. ```typescript theme={"system"} // Copy: counts toward your storage quota await blob.copy(id, { name: "photo_copy", prefix: "backup" }); // Move or rename: does not count toward the quota const moved = await blob.move(id, { name: "renamed" }); id = moved.id; ``` `move(source, destination, options)` is `copy()` with `move: true`. | Destination field | Type | Description | | - | - | - | | `name` | `string` | Required. Name **without extension**: the destination keeps the source's extension. | | `prefix` | `string` | Destination prefix. | | `private` | `boolean` | Destination visibility. | | `security_hash` | `boolean` | Appends `_` to the name. | | `expire` | `string \| null` | Omitted keeps the source's expiration; `null` removes it. | | Option | Accepted by | Description | | - | - | - | | `overwrite` | `copy()`, `move()` | `true` replaces an existing object at the destination. | | `move` | `copy()` | `true` removes the source once the copy succeeds (same as calling `move()`). | The result has `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` and `replaced`. See [Object Copy](/en/blob-reference/endpoint/copy). `update()`, `delete()`, `copy()` and `move()` are writes: they get a **single attempt** and are never retried. See [Retry policy](/en/sdks/blob/errors#retry-policy). ## Next steps Links that expire, count downloads or ask for a password. The REST endpoints behind these methods. # Blob SDK: prefix rules and usage stats Source: https://docs.squarecloud.app/en/sdks/blob/rules_and_stats Read and replace per-prefix Blob Storage rules with @squarecloud/blob (visibility, expiration, size, extensions, auto-delete) and read account usage stats. Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client). ## Rules Rules set defaults and limits for every object under a prefix: visibility, expiration, maximum size, allowed extensions, cache and automatic deletion. They apply to every upload under the prefix, whether it comes from the SDK, an upload token or the dashboard. See [Update Settings](/en/blob-reference/endpoint/settings-put) for plan limits and matching. ### `rules.get()` ```typescript theme={"system"} const rules = await blob.rules.get(); ``` Returns the saved rules as an array. Each rule has the fields below plus `created_at`, and `active_from` when it has `delete_after_days`. `active_from` is **optional**: the API only sends it for rules with `delete_after_days`. In TypeScript, handle it being `undefined`. ### `rules.set(rules)` ```typescript theme={"system"} await blob.rules.set([ { prefix: "tmp/", delete_after_days: 7 }, { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] }, ]); ``` `rules.set()` **replaces the whole list**. Send every rule you want to keep; `rules.set([])` removes them all. To add one rule, read the list first: ```typescript theme={"system"} const current = await blob.rules.get(); await blob.rules.set([ ...current.map(({ created_at, active_from, ...rule }) => rule), { prefix: "exports/", expire: "30d" }, ]); ``` It returns the saved list, like `rules.get()`. | Field | Type | Description | | - | - | - | | `prefix` | `string` | Required. The prefix the rule applies to, e.g. `"a/b/"`. | | `private` | `boolean` | Default visibility. | | `expire` | `string` | Default expiration (`"30d"`, `"168h"`, ...). | | `max_size` | `number` | Maximum file size in bytes, 512 B to 10 GiB. | | `extensions` | `string[]` | 1 to 50 allowed extensions, matching `^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$`. | | `cache_control` | `string` | Default `Cache-Control`. | | `delete_after_days` | `number` | Deletes objects this many days after they were written, 7 to 3650 (Enterprise from 1). | `delete_after_days` only takes effect **24 hours after the rule is saved** (see `active_from`). Once active, deleted objects cannot be recovered. When a rule is rejected, the error's [`extra`](/en/sdks/blob/errors#squarecloudbloberror) carries the offending `prefix`: ```typescript theme={"system"} import { SquareCloudBlobError } from "@squarecloud/blob"; try { await blob.rules.set(rules); } catch (error) { if (error instanceof SquareCloudBlobError) { console.error(error.code, error.extra.prefix); } } ``` `rules.get()` is a read and is [retried](/en/sdks/blob/errors#retry-policy). `rules.set()` gets a **single attempt**. ## Stats ```typescript theme={"system"} const stats = await blob.stats(); console.log(stats.usage.objects); // total objects console.log(stats.usage.storage); // storage used, in bytes ``` | Field | Description | | - | - | | `usage.objects` | Number of objects. | | `usage.storage` | Storage used, in bytes. | | `plan.included` | Storage included in your plan, in bytes. | | `billing` | `extraStorage`, `storagePrice`, `objectsPrice`, `totalEstimate`. | | `month` | `days` and `average_storage` for the current month. | Stats are an **estimate**, cached by the server for **60 seconds**. `billing` is only an estimate of the storage above your plan, not an invoice. See [Account Stats](/en/blob-reference/endpoint/stats). ## Next steps Reach Blob Storage with any S3 client. The REST endpoints behind these methods. # Blob SDK: S3 gateway client Source: https://docs.squarecloud.app/en/sdks/blob/s3 Get S3 credentials with s3Credentials() and a ready-to-use S3Client with s3() to reach Blob Storage through the S3-compatible gateway. Blob Storage has an [S3-compatible gateway](/en/blob-reference/s3-compatibility) that works with any S3 client. The SDK gives you its credentials, or a ready `S3Client` from the AWS SDK. Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client). Both methods need an **API key**. A client created with an upload token gets `403 UPLOAD_TOKEN_NOT_ALLOWED`, and a key in an old format gets `LEGACY_API_KEY`. ## `s3()` `s3()` returns an `S3Client` from `@aws-sdk/client-s3`, already configured with the gateway's endpoint, region and credentials, and with `forcePathStyle: true`. `@aws-sdk/client-s3` is an **optional peer dependency**: install it only if you use `s3()`. It is loaded lazily, so the SDK itself stays dependency-free. ```bash theme={"system"} npm install @aws-sdk/client-s3 ``` ```bash theme={"system"} yarn add @aws-sdk/client-s3 ``` ```bash theme={"system"} pnpm add @aws-sdk/client-s3 ``` ```bash theme={"system"} bun add @aws-sdk/client-s3 ``` ```typescript theme={"system"} import { ListObjectsV2Command } from "@aws-sdk/client-s3"; import { SquareCloudBlob } from "@squarecloud/blob"; const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); const s3 = await blob.s3(); const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "public" })); ``` ### Buckets | Bucket | Contents | Access | | - | - | - | | `public` | Public objects | Read and write | | `private` | Private objects | Read and write | | `legacy` | Objects uploaded before the current storage | Read, list and delete only | See [Buckets](/en/blob-reference/s3-compatibility#buckets) and [Keys](/en/blob-reference/s3-compatibility#keys) for how S3 keys map to objects, and [Supported operations](/en/blob-reference/s3-compatibility#supported-operations) for what the gateway accepts. ## `s3Credentials()` For other S3 clients (aws-cli, rclone, boto3, ...), `s3Credentials()` returns the raw key pair: ```typescript theme={"system"} const credentials = await blob.s3Credentials(); ``` | Field | Type | Description | | - | - | - | | `access_key_id` | `string` | Access key id. | | `secret_access_key` | `string` | **Secret** access key. | | `endpoint` | `string` | Gateway endpoint. | | `region` | `string` | Region (`auto`). | | `buckets` | `string[]` | `public`, `private` and `legacy`. | | `access` | `{ read, write }` | What the pair may do, following the API key's scopes (typed `boolean \| string[]`). | | `expires_at` | `string \| null` | When the API key, and so the pair, expires; `null` when it does not. | Use **path-style addressing** with any other client. `secret_access_key` gives the same access as the API key. Keep it on the server and store it like the key itself. Revoking or rotating the API key also kills the pair. ### Caching The pair is deterministic per API key, so the SDK **caches it per client instance**: `s3Credentials()` and `s3()` call the API once, and later calls reuse the result. A failed call is not cached, so the next call tries again. The credentials route accepts only 10 requests per hour. Create one `SquareCloudBlob` client and reuse it instead of creating one per request. API reference: [S3 Credentials](/en/blob-reference/endpoint/s3-credentials). ## Next steps Error codes and the retry policy. What the S3 gateway supports. # Blob SDK: share links Source: https://docs.squarecloud.app/en/sdks/blob/sharing Create, list and revoke Blob Storage share links with @squarecloud/blob, with expiration, download limits and passwords, and compare them with downloadUrl(). A **share** is a link to one object that can **expire**, be **revoked**, cap the **number of downloads** and, on Pro and Enterprise, ask for a **password**. See [Links and sharing](/en/blob-reference/links-and-sharing) for how the links behave. Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client). ## Share or `downloadUrl()`? | | [`downloadUrl()`](/en/sdks/blob/objects#download-links) | `shares.create()` | | - | - | - | | Public object | Permanent CDN URL (`expires_at: null`) | Redirects to the permanent public URL (see the warning below) | | Private object | Temporary link, up to 24 hours | Share link, up to 30 days | | Revocable | **No** | Yes, with `shares.revoke()` | | Download limit | No | Yes, `max_downloads` | | Password | No | Yes, Pro and Enterprise | Use `downloadUrl()` for short-lived links you hand out yourself, and a share when you need to take the link back or control who downloads it. ## Creating a share ```typescript theme={"system"} const share = await blob.shares.create(id, { expires_in: 86400, // seconds, 60 to 2592000 (default 86400) max_downloads: 10, // 1 to 10000 password: "secret123", // 8 to 128 characters, Pro and Enterprise }); console.log(share.url); ``` | Option | Type | Description | | - | - | - | | `expires_in` | `number` | Link lifetime in seconds, 60 to 2592000 (30 days). Default 86400. | | `max_downloads` | `number` | 1 to 10000. | | `password` | `string` | 8 to 128 characters. Pro and Enterprise; other plans get `UPGRADE_REQUIRED`. | The result has `id`, `url`, `expires_at`, `max_downloads`, `password` (whether one is set), `object` and `object_is_public`. If `object_is_public` is `true`, the share link redirects to the object's **permanent public URL**: the password, download limit and expiration **protect nothing**, because the file stays reachable at that URL. Make the object private first, then share it: ```typescript theme={"system"} const [result] = await blob.update(id, { private: true }); if (result.ok) { id = result.id; // the id changes const share = await blob.shares.create(id, { max_downloads: 1 }); } ``` ## Listing shares ```typescript theme={"system"} const shares = await blob.shares.list(); ``` Returns an array of shares, each with `id`, `url`, `object`, `expires_at`, `remaining_downloads`, `password` and `created_at`. ## Revoking a share ```typescript theme={"system"} await blob.shares.revoke(share.id); ``` The link stops working. `revoke()` resolves to nothing, and revoking a share that does not exist fails with `SHARE_NOT_FOUND`. Deleting, moving or renaming the object, or changing its visibility, also breaks its share links: they point to the old id. Create new shares for the new id. `shares.create()` and `shares.revoke()` get a **single attempt**. Only `shares.list()`, a read, is [retried](/en/sdks/blob/errors#retry-policy). API reference: [Create Share](/en/blob-reference/endpoint/shares-create), [List Shares](/en/blob-reference/endpoint/shares-list), [Delete Share](/en/blob-reference/endpoint/shares-delete). ## Next steps Per-prefix rules and usage stats. How public URLs, download links and shares behave. # Blob SDK: uploads and upload tokens Source: https://docs.squarecloud.app/en/sdks/blob/uploads Upload files with put(): file paths, Blob/File or bytes, automatic multipart uploads above 90 MiB, and upload tokens for uploading straight from the browser. Examples use the `blob` client from [Creating the client](/en/sdks/blob/client#creating-the-client). ## `put(file, options)` `put()` uploads one file and returns the new object. ```typescript theme={"system"} const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars", }); ``` ### Inputs | Input | Environment | Notes | | - | - | - | | `string` (file path) | **Node.js only** | Opened with `fs.openAsBlob` and **streamed from disk**, never read whole into memory. The extension comes from the path's basename. | | `Blob` / `File` | Node.js and browsers | A `File` gives its `name` (and its extension). | | `Uint8Array` (including `Buffer`) | Node.js and browsers | Pass `filename` to set the extension. | | `ArrayBuffer` | Node.js and browsers | Pass `filename` to set the extension. | The object's extension comes from `filename`, then the path's basename or the `File`'s name. Bytes and a plain `Blob` have no name, so **pass `filename`** (for example `"data.json"`) when uploading them. In Node.js, a path that cannot be opened throws a plain `Error` (`Cannot open file: `, with the original error in `cause`). In a browser, passing a path fails earlier, with the error from importing `node:fs`. Use a `File` from an `` instead. ### Options | Option | Type | Description | | - | - | - | | `name` | `string` | Object name **without extension**, matching `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, no `..`, not ending in `-ex`. Required unless an upload token fixes it. | | `prefix` | `string` | Folder-like path: up to 8 segments of `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 characters. | | `private` | `boolean` | Default `false`. Private objects always get a security hash and have `url: null`. | | `security_hash` | `boolean` | Appends `_` to the name. | | `expire` | `string` | `"30"` (days), `"30d"` or `"168h"`; from 7 to 1825 days (Enterprise down to 1 hour). The expiration becomes part of the id. | | `overwrite` | `boolean` | `false` fails with `OBJECT_ALREADY_EXISTS` when the name is taken. **Simple uploads only.** | | `disposition` | `"inline"` \| `"attachment"` | `Content-Disposition` of the object. | | `auto_download` | `boolean` | Forces a download (`application/octet-stream`). | | `cache_control` | `string` | `immutable`, `max-age=60..31536000` or `no-cache` (Enterprise). | | `metadata` | `Record` | Pro and Enterprise. Keys `^[a-z0-9-]{1,64}$` (never `sq-*`), up to 5 keys and 512 bytes. | | `checksum_sha256` | `string` | 64 lowercase hex characters. A mismatch fails with `CHECKSUM_MISMATCH` and nothing is stored. **Simple uploads only.** | | `filename` | `string` | File name whose extension becomes the object's extension. Defaults to the `File` name or the path's basename. | | `mime_type` | `string` | Only used to pick the extension when `filename` has none. The server derives the `Content-Type`. | See [Object Post](/en/blob-reference/endpoint/post) for the full server-side rules. ### Result | Field | Type | Description | | - | - | - | | `id` | `string` | Opaque object id. [Store it as-is](/en/sdks/blob/client#object-ids). | | `private` | `boolean` | Whether the object is private. | | `url` | `string \| null` | Public URL, or `null` for a private object (use [`downloadUrl()`](/en/sdks/blob/objects#download-links)). | | `expires_at` | `string` | When the object expires, if it has an expiration. | | `size` | `number` | Size in bytes. | | `name`, `prefix`, `sha256`, `replaced` | | Simple uploads only. | | `parts` | `number` | Multipart uploads only: number of parts sent. | ## Simple and multipart uploads `put()` picks the upload flow from the file size: | File size | Flow | Endpoint | | - | - | - | | Up to **90 MiB** (94,371,840 bytes) inclusive | Simple upload, one request | [Object Post](/en/blob-reference/endpoint/post) | | Above 90 MiB, up to **10 GiB** | Multipart (chunked) upload | [Chunked Init](/en/blob-reference/endpoint/chunked-init) | Every file must have **at least 512 bytes**; smaller files fail with `FILE_TOO_SMALL`. A rule or upload token `max_size`, or your storage quota, can lower the 10 GiB ceiling. ### How a multipart upload runs 1. The SDK starts the upload, and the server answers with its part limits (`max_size`, `max_parts`). 2. The file is split into parts of `min(max_size, max(16 MiB, ceil(size / max_parts)))` bytes. A part is usually 16 MiB or more, but it is smaller when the server's `max_size` is smaller. 3. Parts are sent **6 at a time**, the server's limit for parts in flight. A failed part is [retried](/en/sdks/blob/errors#retry-policy) within `maxRetries`. 4. When every part arrived, the SDK completes the upload. If a part fails for good, or completing fails, the SDK **waits for the parts still in flight** and then **aborts** the upload, so no part lands after the abort. The original error is thrown. There is **no resume**: call `put()` again. A multipart upload **does not check `overwrite: false` or `checksum_sha256`**. It always replaces an existing object with the same name. An account can have at most **32 open multipart uploads** (shared with the S3 gateway); one more fails with `TOO_MANY_OPEN_UPLOADS`. Since parts go 6 at a time per account, run **one large upload at a time**. ## Uploading from the browser Never send the API key to a browser. Instead, your server mints a short-lived **upload token** and the browser uploads with it. ```typescript theme={"system"} import { SquareCloudBlob } from "@squarecloud/blob"; const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY); // e.g. inside your API route const { token } = await blob.uploadTokens.create({ prefix: "avatars/", security_hash: true, max_size: 5 * 1024 * 1024, allowed_extensions: ["png", "jpg"], }); // send only `token` to the browser ``` ```typescript theme={"system"} import { SquareCloudBlob } from "@squarecloud/blob"; const upload = new SquareCloudBlob(token); const { url } = await upload.put(input.files[0], { name: "avatar" }); ``` A client created with a token can **only call `put()`**, including multipart uploads. Any other method fails with `403 UPLOAD_TOKEN_NOT_ALLOWED`. ### `uploadTokens.create(options)` The token pins every option it was minted with. | Option | Type | Description | | - | - | - | | `name` | `string` | Fixes the object name. Without it, the security hash is always applied. | | `prefix` | `string` | Fixes the prefix. | | `private` | `boolean` | Fixes the visibility. | | `security_hash` | `boolean` | Appends `_` to the name. | | `expire` | `string` | Object expiration, as in `put()`. | | `max_size` | `number` | Maximum file size in bytes. | | `allowed_extensions` | `string[]` | 1 to 20 extensions. | | `metadata` | `Record` | Metadata applied to the uploaded object. | | `expires_in` | `number` | Token lifetime in seconds, 60 to 3600 (default 900). | | `max_uses` | `number` | Uploads allowed, 1 to 100 (default 1). Then the token fails with `UPLOAD_TOKEN_USED`. | It returns `{ token, expires_at, max_uses }`. See [Upload Tokens](/en/blob-reference/endpoint/upload-tokens) for the server-side rules. `uploadTokens.create()` is a write and gets a **single attempt**: it is never retried. ## Next steps List, update, copy, move and delete objects. The REST endpoints behind put(). # Go SDK: AI Gateway chat Source: https://docs.squarecloud.app/en/sdks/go/ai Call the Square Cloud AI Gateway from the Go SDK (sdk-api-go) with c.AI.Chat: OpenAI-compatible chat completions, without streaming. `c.AI.Chat(ctx, request)` calls the [AI Gateway](/en/api-reference/ai-gateway), an **OpenAI-compatible** chat completions endpoint. It needs the `ai:chat` scope and a Standard plan or above. The shorter snippets below run inside the program from [Running the examples](/en/sdks/go/client#running-the-examples): paste one at a time into `main` and run `goimports`. ```go theme={"system"} package main import ( "context" "fmt" "log" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) func main() { ctx := context.Background() c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) completion, err := c.AI.Chat(ctx, squarecloud.ChatRequest{ Model: "cubic", Messages: []squarecloud.ChatMessage{ {Role: "system", Content: "You are a helpful assistant."}, {Role: "user", Content: "What is Square Cloud?"}, }, MaxTokens: 512, }) if err != nil { log.Fatal(err) } fmt.Println(completion.Choices[0].Message.Content) fmt.Println(completion.Usage.TotalTokens) } ``` ## Request `squarecloud.ChatRequest` fields, with their JSON names: | Field | Description | | - | - | | `Model` (`model`) | `cubic`. Accepted for compatibility: there is no other model. `""` is not sent | | `Messages` (`messages`) | `[]ChatMessage` with `Role`, `Content`, `ToolCallID` (`tool_call_id`) and `ToolCalls` (`tool_calls`). `Role` is `system`, `user`, `assistant` or `tool`. `Content` is always sent, `""` included | | `Tools` / `ToolChoice` (`tools` / `tool_choice`) | OpenAI function calling: `Tools` is a `[]json.RawMessage`, `ToolChoice` any JSON-encodable value | | `MaxTokens` (`max_tokens`) | Maximum tokens of the answer. `0` is not sent | | `Temperature` (`temperature`) | Sampling temperature, a `*float64`. `nil` is not sent | The response is a `ChatCompletion` with the OpenAI shape: `ID`, `Object`, `Created`, `Model`, `Choices` (`Index`, `Message`, `FinishReason`) and `Usage` (`PromptTokens`, `CompletionTokens`, `TotalTokens`). ## No streaming `AI.Chat` does not stream: it returns the whole completion. `ChatRequest` has no `stream` field; the API answers 400 `stream_not_supported` to `stream: true`. ## Timeout The gateway gives each request **90 seconds** in total, then answers 503 `server_overloaded`. Without a `ctx` deadline, the SDK waits at least 2 minutes before timing out, so you get the gateway's answer. ## Errors AI errors use the OpenAI format, so their codes are **lowercase**. They are still returned as an [`*APIError`](/en/sdks/go/errors), with `Code` set to the OpenAI code (or its `type` when there is no code): ```go theme={"system"} _, err := c.AI.Chat(ctx, squarecloud.ChatRequest{ Messages: []squarecloud.ChatMessage{{Role: "user", Content: "Hi"}}, }) var apiErr *squarecloud.APIError if errors.As(err, &apiErr) && apiErr.Code == "server_overloaded" { // safe to retry yourself } ``` | Status | Code | When | | - | - | - | | 400 | `stream_not_supported` | `stream: true` was sent | | 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | A malformed field | | 400 | `context_length_exceeded` | The conversation exceeds the plan's context window | | 401 | `access_denied` | Invalid API key | | 403 | `upgrade_required` | The plan has no AI Gateway access | | 429 | `rate_limit_exceeded`, `concurrent_limit_reached` | Too fast, or a request already in flight | | 429 | `daily_limit_reached`, `weekly_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached` | A daily or weekly limit is used up (daily limits reset at 00:00 UTC, weekly ones on Monday at 00:00 UTC) | | 503 | `server_overloaded` | Capacity is full or the 90 s deadline passed: safe to retry | | 503 | `daily_capacity_reached` | The platform's daily capacity is used up | The SDK **never retries** AI errors: the request is a non-idempotent `POST`. See the [AI Gateway reference](/en/api-reference/ai-gateway) for plan limits. ## Next steps Error class, retries and rate limits. Models, plan limits and the OpenAI-compatible endpoint. # Go SDK: quickstart and client Source: https://docs.squarecloud.app/en/sdks/go/client Install the Square Cloud Go SDK (sdk-api-go v3), create a client with your API key and follow its conventions: context, ids, workspace apps, dates and timeouts. This page documents **`github.com/squarecloudofc/sdk-api-go/v3`** (v3.0.0), a rewrite of the SDK. Coming from v2? Read the [v2 → v3 migration guide](/en/sdks/go/migrating_to_v3). ## Requirements * **Go 1.22** or newer. * An API key (see [API key and scopes](#api-key-and-scopes)). The module has **no dependencies** besides the Go standard library and is licensed under **MIT** (v2 was AGPL-3.0). Its package name is `squarecloud`. ## Installation ```bash theme={"system"} go get github.com/squarecloudofc/sdk-api-go/v3 ``` ```go theme={"system"} import "github.com/squarecloudofc/sdk-api-go/v3" // package squarecloud ``` ## API key and scopes Create a key at [squarecloud.app/account/security](https://squarecloud.app/en/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 returns an [`*APIError`](/en/sdks/go/errors) 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 out of your source code and out of binaries you distribute. Read it from the environment or a secret store. The examples read the key from the `SQUARECLOUD_API_KEY` environment variable. Set it in the terminal where you run them: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` ```powershell theme={"system"} $env:SQUARECLOUD_API_KEY = "your-api-key" ``` ## Creating the client ```go theme={"system"} package main import ( "context" "fmt" "log" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) func main() { ctx := context.Background() c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) me, err := c.Account.Me(ctx) if err != nil { log.Fatal(err) } fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications)) } ``` Save it as `main.go` in a module (`go mod init example.com/hello`, then the `go get` above) and run `go run .`. It prints your account name and the number of apps the key can see: ```text theme={"system"} Hi Jane, you have 3 apps ``` `squarecloud.New(apiKey, opts...)` returns a `*Client` and **never an error**. A `*Client` is safe for concurrent use: build it once and share it between goroutines. Because `New` cannot fail, an empty or whitespace-only key is not rejected there. Instead, every call except `Service.Status` fails locally with `INVALID_API_KEY` (status `0`) before any request. This code exists only in the Go SDK. ### Options Pass options to `New` after the key: ```go theme={"system"} c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"), squarecloud.WithBaseURL(squarecloud.DefaultBaseURL), // "https://api.squarecloud.app/v2" (default) squarecloud.WithTimeout(30*time.Second), squarecloud.WithMaxRetries(2), squarecloud.WithUserAgent("my-bot/1.0"), squarecloud.WithHTTPClient(&http.Client{ // proxy, tracing, tests Transport: &http.Transport{Proxy: http.ProxyFromEnvironment}, }), ) ``` | Option | Default | Description | | - | - | - | | `WithBaseURL(u)` | `https://api.squarecloud.app/v2` | API base URL. A trailing `/` is stripped. Also exported as `DefaultBaseURL`. | | `WithTimeout(d)` | `30*time.Second` | Default deadline of a call whose `ctx` has none. It covers the whole call, retries included. See [Timeouts](#timeouts). | | `WithMaxRetries(n)` | `2` | Retries of safe failures only (up to 3 attempts). A negative value counts as `0`. See [Retries](/en/sdks/go/errors#retries). | | `WithUserAgent(ua)` | `squarecloud-sdk-go/` | Replaces the whole `User-Agent` header. | | `WithHTTPClient(hc)` | `&http.Client{}` | A custom `*http.Client` for proxies, tracing or tests. `nil` keeps the default. | Do not set `Timeout` on the `*http.Client` you pass to `WithHTTPClient`. That timeout also covers reading the body, so it would cut [realtime](/en/sdks/go/realtime) streams and snapshot downloads. Use contexts, `WithTimeout` and `http.Transport` timeouts instead. The SDK never logs. To trace requests, wrap the `http.RoundTripper` of the client you pass to `WithHTTPClient`. The API key is stored in an unexported field of the client. `fmt` prints unexported fields, so don't print the client with `%v` or `%+v`. ## Running the examples The snippets on the Go SDK pages are fragments. Each one runs on its own inside this program, which declares the `ctx`, `c` and `appID` they use: ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" // one of your apps: see Account below ) func main() { // Paste one snippet here, then run goimports. } ``` Paste **one snippet at a time** into `main`, then run `goimports -w .` to add the imports it needs (`fmt`, `log`, `time`, ...). Install it with `go install golang.org/x/tools/cmd/goimports@latest`, or let your editor's Go extension (gopls) add imports on save. Pages that need other ids, such as a database or a workspace, start with their own version of this program. ## Modules | Field | Covers | Page | | - | - | - | | `c.Account` | `Me`, `Snapshots(ctx, scope)` | [Account](#account) and [Snapshots](/en/sdks/go/snapshots) | | `c.Service` | `Status` | [Platform status](#platform-status) | | `c.Apps` | Get, delete, status, lifecycle, logs, metrics, domains, load balancers | [Managing applications](/en/sdks/go/managing_application) | | `c.Apps.Create` / `Commit` | Uploads | [Commit and upload](/en/sdks/go/commit_and_upload) | | `c.Apps.Files` | File manager | [Managing files](/en/sdks/go/managing_files) | | `c.Apps.Envs` | Environment variables | [Environment variables](/en/sdks/go/environment_variables) | | `c.Apps.Deploys` | Webhook and GitHub App deploys | [Deploys](/en/sdks/go/deploys) | | `c.Apps.Network` | Analytics, logs, DNS, custom domain, cache | [Network](/en/sdks/go/network) | | `c.Apps.Realtime` | Live logs and status | [Realtime](/en/sdks/go/realtime) | | `c.Apps.Snapshots` / `c.Databases.Snapshots` / `c.DownloadSnapshot` | Backups | [Snapshots](/en/sdks/go/snapshots) | | `c.Databases` | Managed databases | [Databases](/en/sdks/go/databases) | | `c.Workspaces` | Workspaces, members and shared apps | [Workspaces](/en/sdks/go/workspaces) | | `c.AI` | `Chat` | [AI](/en/sdks/go/ai) | Besides `New` and the `With*` options, the package exports the `DefaultBaseURL` and `Version` constants, the [`APIError`](/en/sdks/go/errors) type with one `Code*` constant per error code, typed constants for enumerated inputs (`DatabaseRedis`, `GroupView`, `ResetPassword`, `SnapshotScopeDatabases`, ...) and one struct per API shape, which you can use in your own code: ```go theme={"system"} func appNames(apps []squarecloud.AppSummary) []string { names := make([]string, 0, len(apps)) for _, app := range apps { names = append(names, app.Name) } return names } ``` ## Conventions ### Context and ids first, typed data back Every method takes a `context.Context` first and the resource id next, and returns **plain structs** (no methods, no cache). The `json` tags are the API's own field names (`created_at`, `version_id`, `lastModified`, `joinedAt`, `netIO`, ...), so the [API reference](/en/api-reference/authentication) applies as-is: `CreatedAt` is `created_at`, `VersionID` is `version_id`. Fields the API adds later are ignored, so they never break decoding. * Mutations return only an `error`, unless the API returns data (`Envs.*`, `Deploys.SetWebhook`, `Deploys.LinkGithubApp`, `Databases.ResetCredentials` and the `Create` methods). * A string result is `""` when the API sends none. * Fields the API may send as `null` are **pointers**: check them for `nil` before use. * Counters and byte sizes are `int64`. * Lists come complete in one call: there is no pagination. ```go theme={"system"} app, err := c.Apps.Get(ctx, appID) if err != nil { log.Fatal(err) } if app.Domain != nil { // *string: nil for apps without a web domain fmt.Println("https://" + *app.Domain) } ``` Resource groups are plain struct fields, so you can keep method values: ```go theme={"system"} restart, logs := c.Apps.Restart, c.Apps.Logs if err := restart(ctx, appID); err != nil { log.Fatal(err) } out, err := logs(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(out) ``` ### Workspace apps Every `appID` also accepts the composite form `-` to act on an app shared with you through a [workspace](/en/sdks/go/workspaces). `Workspaces.Get` and `Workspaces.List` return raw ids; you build the composite id yourself: ```go theme={"system"} workspaceID := "0123456789abcdef0123456789abcdef" if err := c.Apps.Restart(ctx, appID+"-"+workspaceID); err != nil { log.Fatal(err) } ``` ### 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](/en/sdks/go/network)) are `time.Time` values, sent as RFC 3339 in UTC (whole seconds). In responses, the API's ISO 8601 strings decode to `time.Time`, and the fields the API sends as Unix milliseconds stay numbers (`Plan.Duration` and `Uptime` as `*int64`, `FileEntry.LastModified` as `*float64`): convert them with `time.UnixMilli`. ## Timeouts | Call | Default deadline | | - | - | | Every other call | `WithTimeout` (30 s) | | Calls the server holds open: `Start`/`Stop`/`Restart` of apps, `Start`/`Stop` of databases, `Databases.Create`, snapshot `Create`/`Restore`, `AI.Chat` | At least **2 minutes** (a larger `WithTimeout` wins) | | Uploads (`Apps.Create`, `Apps.Commit`), `Files.Write` above 1 MiB, `DownloadSnapshot` | None: cancel `ctx` | | `Apps.Realtime` | Only until the response headers arrive | * The default deadline applies **only when `ctx` has no deadline**. A deadline on `ctx` always wins, shorter or longer than the default, floors included. * One deadline covers the **whole call**: every attempt and the waits between [retries](/en/sdks/go/errors#retries). * `WithTimeout(0)` (or any `d <= 0`) disables **every** default deadline, the 2-minute floors included. Every method takes a `ctx`, so you can bound or cancel any call: ```go theme={"system"} ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second) defer cancel() f, err := os.Open("build.zip") if err != nil { log.Fatal(err) } defer f.Close() if err := c.Apps.Commit(ctx, appID, f, "", ""); err != nil { log.Fatal(err) } ``` A call whose `ctx` expires returns an `*APIError` with `TIMEOUT`, and one whose `ctx` is canceled returns `NETWORK_ERROR`, both with status `0`. They unwrap to the context's error, so `errors.Is(err, context.DeadlineExceeded)` and `errors.Is(err, context.Canceled)` work. A [realtime](/en/sdks/go/realtime) loop returns the bare `ctx.Err()` instead. ## Account `c.Account.Me(ctx)` returns the authenticated user plus the apps and databases the key can see. ```go theme={"system"} me, err := c.Account.Me(ctx) if err != nil { log.Fatal(err) } user := me.User fmt.Println(user.ID, user.Name, user.Email, user.Plan.Name) fmt.Println(user.Plan.Memory.Limit, user.Plan.Memory.Available, user.Plan.Memory.Used) // MB if user.Plan.Duration != nil { fmt.Println("expires", time.UnixMilli(*user.Plan.Duration)) } else { fmt.Println("never expires") } ``` | Field | Description | | - | - | | `User` (`user`) | `ID`, `Name`, `Email`, `Locale`, `CreatedAt` and `Plan` (`Name`, `Memory`, `Duration`: the Unix ms at which the plan **expires**, `nil` if it never does) | | `Applications` (`applications`) | `[]AppSummary`: `ID`, `Name`, `Description` (`desc`), `RAM`, `Lang`, `Domain` (`*string`), `Custom` (`*string`), `Cluster`, `CreatedAt` | | `Databases` (`databases`) | `[]DatabaseSummary`: `ID`, `Name`, `RAM`, `Type`, `Cluster`, `CreatedAt` | `c.Account.Snapshots(ctx, scope)` lists every snapshot of the account: see [Snapshots](/en/sdks/go/snapshots#account-snapshots). ## Platform status `c.Service.Status(ctx)` returns the public platform status. The route needs no key, and it is the only method that also works on a client built with an empty key. ```go theme={"system"} status, err := c.Service.Status(ctx) if err != nil { log.Fatal(err) } fmt.Println(status.Status) // "online" | "degraded" | "unknown" fmt.Println(status.Message) for name, service := range status.Services { fmt.Println(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 Status, lifecycle, logs and metrics. Error class, retries and rate limits. Base URL, authentication and a first request. Deploy and manage apps from the terminal. # Go SDK: upload and commit files Source: https://docs.squarecloud.app/en/sdks/go/commit_and_upload Create applications from a zip with c.Apps.Create and send files to an existing application with c.Apps.Commit, streamed from any io.Reader. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` ## Accepted inputs `Apps.Create` and `Apps.Commit` take any `io.Reader` and stream it as `multipart/form-data`, never loading it into memory: | Input | Notes | | - | - | | `*os.File` | Streamed from disk with a `Content-Length`. Its base name is used as the filename. Can be retried on 503 `UPLOAD_BUSY` | | `*bytes.Reader`, `*strings.Reader` (any `io.ReaderAt` that is also an `io.Seeker`) | Sent with a `Content-Length`. Can be retried on 503 `UPLOAD_BUSY` | | Any other `io.Reader` (a pipe, a response body, ...) | Sent chunked, in a single attempt: it cannot be replayed | Uploads are **limited to 100 MB**. A larger file fails locally with `FILE_TOO_LARGE` (status `0`): before anything is sent when the size is known, otherwise as soon as the stream passes 100 MB. Uploads have **no default deadline**: cancel them with `ctx`. ## Creating an application `Apps.Create(ctx, zip)` deploys a `.zip` that contains a [`squarecloud.app`](/en/getting-started/config-file) configuration file at its root. ```go theme={"system"} f, err := os.Open("bot.zip") if err != nil { log.Fatal(err) } defer f.Close() app, err := c.Apps.Create(ctx, f) if err != nil { log.Fatal(err) } fmt.Println(app.ID, app.Name, app.RAM, app.CPU, app.Language.Name, app.Language.Version) fmt.Println(app.Domain) // ".squareweb.app" for web apps, "" otherwise fmt.Println(app.Cluster) // the cluster the app was placed on ``` | Field | Description | | - | - | | `ID` (`id`) | The new app's id | | `Name` (`name`) | Name from the config file | | `Description` (`description`) | `""` when not set | | `Domain` (`domain`) | Full `.squareweb.app` host; `""` for non-web apps | | `Cluster` (`cluster`) | Cluster the app was placed on | | `RAM` / `CPU` (`ram` / `cpu`) | Allocated resources (`CPU` is a `float64`) | | `Language` (`language`) | `Name` and `Version` | ## Committing to an application `Apps.Commit(ctx, appID, r, path, filename)` uploads a file into an existing app: * A `.zip` is **unpacked** at `path` (`""` for the app root). * Any other file lands at `path/`. The filename is `filename`, else the reader's own name (the base name of an `*os.File`), else `commit.zip`. Pass `""` to use the default. ```go theme={"system"} // Unpack a zip at the root build, err := os.Open("build.zip") if err != nil { log.Fatal(err) } defer build.Close() if err := c.Apps.Commit(ctx, appID, build, "", ""); err != nil { log.Fatal(err) } // Unpack a zip into /src patch, err := os.Open("patch.zip") if err != nil { log.Fatal(err) } defer patch.Close() if err := c.Apps.Commit(ctx, appID, patch, "/src", ""); err != nil { log.Fatal(err) } // A single file from memory: /src/index.js code := strings.NewReader(`console.log("Hello from Square Cloud");`) if err := c.Apps.Commit(ctx, appID, code, "/src", "index.js"); err != nil { log.Fatal(err) } ``` A commit does not restart the app. Call [`Apps.Restart`](/en/sdks/go/managing_application#start-stop-and-restart) to apply it. ## Cancelling an upload ```go theme={"system"} ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second) defer cancel() f, err := os.Open("bot.zip") if err != nil { log.Fatal(err) } defer f.Close() _, err = c.Apps.Create(ctx, f) if errors.Is(err, context.DeadlineExceeded) { fmt.Println("the upload took too long") } ``` A canceled upload returns an `*APIError` (`NETWORK_ERROR` when `ctx` was canceled, `TIMEOUT` when its deadline passed) that unwraps to `context.Canceled` or `context.DeadlineExceeded`. ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | The file is over 100 MB (checked locally) | | 400 | `INVALID_FILE`, `INVALID_FILENAME` | No file, or a file name with path separators, `..` or control characters | | 400 | `INVALID_PATH` | `path` contains traversal or shell metacharacters (commit) | | 400 | `INSUFFICIENT_MEMORY` | Less than 256 MB of available memory on the plan (create) | | 400 | `COMMIT_FAILED` | The commit could not be applied (commit) | | 400 | `UPLOAD_FAILED`, `STORAGE_UPLOAD_FAILED`, `CLUSTER_SELECTION_FAILED` | The upload could not be processed (create) | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance (create) | | 503 | `UPLOAD_BUSY` | Too many uploads in progress: retried automatically when the reader can be replayed | Opening the file is up to your code, so an `os.Open` error never reaches the SDK. A `nil` reader returns a plain error, not an `*APIError`. See [Errors](/en/sdks/go/errors) for the full list. ## Next steps List, read, write, move and delete app files. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: managed databases Source: https://docs.squarecloud.app/en/sdks/go/databases Create, inspect, update, start, stop and delete managed databases, read their status and metrics, and manage their credentials with c.Databases. `c.Databases` manages Square Cloud's managed databases (MongoDB, MySQL, PostgreSQL and Redis). Every method takes `ctx` first and, except `Create` and `StatusAll`, the database id next. To list your databases, use [`c.Account.Me`](/en/sdks/go/client#account): its `Databases` slice has every database the key can see. Database hosting needs a Standard, Pro or Enterprise plan. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) databaseID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` ## Creating a database ```go theme={"system"} db, err := c.Databases.Create(ctx, squarecloud.DatabaseCreate{ Name: "my-db", Type: squarecloud.DatabasePostgres, // DatabaseMongo, DatabaseMySQL, DatabaseRedis, DatabasePostgres Version: "17", // a full version or a prefix Memory: 1024, // MB }) if err != nil { log.Fatal(err) } fmt.Println(db.ID, db.ConnectionURL, db.Cluster) fmt.Println(db.Password) // shown only here: save it if db.Certificate != nil { fmt.Println(*db.Certificate) // base64 PEM (private key, then certificate) } ``` | Field | Description | | - | - | | `Name` (`name`) | 1 to 32 characters | | `Type` (`type`) | `DatabaseMongo`, `DatabaseMySQL`, `DatabaseRedis` or `DatabasePostgres` (`mongo`, `mysql`, `redis`, `postgres`) | | `Version` (`version`) | A full version or a prefix such as `"8"` | | `Memory` (`memory`) | MB, an `int`. At least 512 for Redis and 1024 for the others | The result is a `DatabaseCreated` with `ID`, `Name`, `Memory`, `CPU` (`float64`), `Type`, `Password`, `Certificate` (`*string`, `nil` when the API sends none), `ConnectionURL` (`connection_url`) and `Cluster`. The password and certificate are only returned by `Create` (and by [`ResetCredentials`](#credentials)). Without a `ctx` deadline, the call waits at least 2 minutes before timing out. | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `INVALID_DATABASE_TYPE`, `INVALID_DATABASE_VERSION` | Unknown type or unsupported version | | 400 | `INVALID_MEMORY` | `memory` is not a whole number (a fraction or a string). `Memory` is an `int`, so the Go SDK never sends one | | 400 | `INSUFFICIENT_MEMORY` | `Memory` is below the engine's minimum or exceeds the available memory | | 400 | `CLUSTER_SELECTION_FAILED` | No cluster had enough capacity | | 400 / 500 | `DATABASE_CREATION_FAILED` | Provisioning failed | | 403 | `UPGRADE_REQUIRED` | The plan has no database hosting | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance | ## Getting a database ```go theme={"system"} db, err := c.Databases.Get(ctx, databaseID) if err != nil { log.Fatal(err) } fmt.Println(db.ID, db.Name, db.Type, db.RAM, db.Port, db.Cluster, db.CreatedAt) ``` ## Updating a database `Update(ctx, databaseID, squarecloud.DatabaseUpdate{Name, RAM})` renames or resizes a database. Zero fields are not sent; set at least one (400 `NO_UPDATE_DATA` otherwise). ```go theme={"system"} if err := c.Databases.Update(ctx, databaseID, squarecloud.DatabaseUpdate{Name: "orders", RAM: 2048}); err != nil { log.Fatal(err) } ``` ## Start and stop ```go theme={"system"} if err := c.Databases.Start(ctx, databaseID); err != nil { log.Fatal(err) } if err := c.Databases.Stop(ctx, databaseID); err != nil { log.Fatal(err) } ``` Like app lifecycle calls, without a `ctx` deadline they wait at least 2 minutes, and a refusal is **409** with a code and an empty message: `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` or `ACTION_FAILED`. While a snapshot restore runs, they are 403 `RESTORE_IN_PROGRESS`. ## Status and metrics `Status(ctx, databaseID)` returns formatted values; `StatusRaw(ctx, databaseID)` returns numbers. `StatusAll(ctx)` returns one summary per database. `Metrics(ctx, databaseID)` returns the last 24 hours, one point every 5 minutes, newest first. ```go theme={"system"} status, err := c.Databases.Status(ctx, databaseID) if err != nil { log.Fatal(err) } fmt.Println(status.Running, status.CPU, status.RAM) // true "0.5%" "120.4MB" raw, err := c.Databases.StatusRaw(ctx, databaseID) if err != nil { log.Fatal(err) } fmt.Println(raw.CPU, raw.RAM) // 0.5 120.4 items, err := c.Databases.StatusAll(ctx) if err != nil { log.Fatal(err) } for _, it := range items { fmt.Println(it.ID, it.Running, it.CPU, it.RAM) // CPU and RAM only while running } points, err := c.Databases.Metrics(ctx, databaseID) if err != nil { log.Fatal(err) } if len(points) > 0 { fmt.Println(points[0].Date, points[0].CPU, points[0].RAM) } ``` The status fields are the same as [app status](/en/sdks/go/managing_application#status). ## Credentials `Certificate(ctx, databaseID)` returns the TLS certificate as base64-encoded PEM. `ResetCredentials(ctx, databaseID, reset)` rotates the password (`squarecloud.ResetPassword`, returns the new one) or the certificate (`squarecloud.ResetCertificate`, returns `""`). The database must be running (400 `DATABASE_NOT_RUNNING`). ```go theme={"system"} certificate, err := c.Databases.Certificate(ctx, databaseID) if err != nil { log.Fatal(err) } pem, err := base64.StdEncoding.DecodeString(certificate) if err != nil { log.Fatal(err) } if err := os.WriteFile("database.pem", pem, 0o600); err != nil { log.Fatal(err) } ``` ```go theme={"system"} password, err := c.Databases.ResetCredentials(ctx, databaseID, squarecloud.ResetPassword) if err != nil { log.Fatal(err) } fmt.Println(password) // the new password: save it if _, err := c.Databases.ResetCredentials(ctx, databaseID, squarecloud.ResetCertificate); err != nil { log.Fatal(err) } ``` ## Deleting a database ```go theme={"system"} if err := c.Databases.Delete(ctx, databaseID); err != nil { log.Fatal(err) } ``` Deletion is permanent. Take a [snapshot](/en/sdks/go/snapshots) first if you may need the data again. ## Snapshots `c.Databases.Snapshots` has the same `List`, `Create` and `Restore` as apps. See [Snapshots](/en/sdks/go/snapshots). ## Next steps Share apps with your team. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: GitHub deploys Source: https://docs.squarecloud.app/en/sdks/go/deploys Deploy from GitHub with c.Apps.Deploys: set a webhook, link a repository through the Square Cloud GitHub App, and read the deploy history. `c.Apps.Deploys` connects an app to GitHub so a push deploys it. There are two ways to do it: a **webhook** that you add to the repository, or the **Square Cloud GitHub App**. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` ## Webhook `Deploys.SetWebhook(ctx, appID, accessToken)` configures GitHub webhook deploys with a GitHub access token (`ghp_...` or `github_pat_...`) and returns the webhook URL to add to your repository. ```go theme={"system"} url, err := c.Apps.Deploys.SetWebhook(ctx, appID, os.Getenv("GITHUB_TOKEN")) if err != nil { log.Fatal(err) } fmt.Println(url) // add it as a webhook in the repository settings ``` Pass `"@"` as the token to remove the webhook. The method then returns `""`. ```go theme={"system"} if _, err := c.Apps.Deploys.SetWebhook(ctx, appID, "@"); err != nil { log.Fatal(err) } ``` An invalid token is 400 `INVALID_ACCESS_TOKEN`. ## GitHub App `Deploys.LinkGithubApp(ctx, appID, repository, branch)` links a repository installed through the Square Cloud GitHub App. It needs the `apps:deploy` scope. ```go theme={"system"} repo, err := c.Apps.Deploys.LinkGithubApp(ctx, appID, "octocat/hello-world", "main") if err != nil { log.Fatal(err) } fmt.Println(repo.ID, repo.FullName, repo.Branch) ``` `Deploys.UnlinkGithubApp(ctx, appID)` removes the link. To link another repository or branch, unlink first. ```go theme={"system"} if err := c.Apps.Deploys.UnlinkGithubApp(ctx, appID); err != nil { log.Fatal(err) } ``` Link and unlink share a limit of **3 calls per 60 seconds**. | Status | Code | When | | - | - | - | | 400 | `GIT_ALREADY_CONFIGURED` | The app already has a linked repository: unlink it first | | 400 | `GIT_NOT_CONFIGURED` | `UnlinkGithubApp` with nothing linked | | 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | The branch does not exist, or its name is over 256 characters | | 403 | `GITHUB_NOT_CONNECTED` | Your account has no GitHub App installation | | 403 | `REPOSITORY_NOT_AVAILABLE` | The GitHub App is not installed on the repository through your GitHub account | | 403 | `REPOSITORY_PERMISSION_REQUIRED` | Your GitHub account has no write access to the repository | | 404 | `REPOSITORY_NOT_FOUND` | The repository does not exist or is not visible | | 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | Another app, of any account, already links this repository and branch. Its id is in `Message` only when that app is yours | | 502 | `FAILED_TO_FETCH` | GitHub did not confirm the branch: safe to retry | ## Current configuration `Deploys.Current(ctx, appID)` returns what is configured: `App` for the GitHub App link, `Webhook` for the webhook URL. When nothing is set, it returns the zero value (`App` is `nil` and `Webhook` is `""`). The fields of `App` are pointers, since the API may send them as `null`. ```go theme={"system"} current, err := c.Apps.Deploys.Current(ctx, appID) if err != nil { log.Fatal(err) } if app := current.App; app != nil && app.Name != nil && app.Branch != nil { fmt.Println(*app.Name, *app.Branch) // e.g. "octocat/hello-world" "main" } if current.Webhook != "" { fmt.Println(current.Webhook) } ``` ## Deploy history `Deploys.List(ctx, appID)` returns one **timeline per deploy** (a `[][]DeployEvent`), each a slice of events, oldest event first. Only Git deploys (webhook and GitHub App pushes) are recorded. ```go theme={"system"} timelines, err := c.Apps.Deploys.List(ctx, appID) if err != nil { log.Fatal(err) } for _, timeline := range timelines { if len(timeline) == 0 { continue } last := timeline[len(timeline)-1] fmt.Println(last.ID, last.State, last.Date) if last.State == squarecloud.DeployError { fmt.Println(last.Code, last.Message) } } ``` | Field | Description | | - | - | | `ID` (`id`) | The commit SHA | | `State` (`state`) | `pending`, `clone`, `commit`, `restarting`, `success` or `error` (constants `DeployPending`, `DeployClone`, `DeployCommit`, `DeployRestarting`, `DeploySuccess`, `DeployError`) | | `Date` (`date`) | When the event happened (`time.Time`) | | `Source` (`source`) | Always `"git"` | | `Branch` (`branch`) | On `clone` events | | `Files` (`files`) | On `commit` events: a `*DeployFiles` with `Added`, `Removed` and `Modified`; `nil` otherwise | | `Code` / `Message` (`code` / `message`) | On `error` events: why the deploy failed (for example `CLONE_FAILED`) | ## Next steps Analytics, DNS, custom domains and cache. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: environment variables Source: https://docs.squarecloud.app/en/sdks/go/environment_variables Read, add, replace and remove the environment variables of a Square Cloud application with c.Apps.Envs in the Go SDK, returned as a map of strings. Environment variables live on `c.Apps.Envs`. Every method takes `ctx` and the app id first and returns the app's variables as a `squarecloud.EnvVars` (a `map[string]string`). Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` Static apps have no environment variables: every method answers 400 `STATIC_APP_ENV_NOT_SUPPORTED`. A change takes effect on the next [restart](/en/sdks/go/managing_application#start-stop-and-restart). ## Reading the variables ```go theme={"system"} envs, err := c.Apps.Envs.Get(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(envs["NODE_ENV"]) ``` ## Adding or updating variables `Envs.Set(ctx, appID, envs)` adds the given keys and overwrites the ones that already exist. Other variables are kept. It returns every variable after the change. ```go theme={"system"} envs, err := c.Apps.Envs.Set(ctx, appID, squarecloud.EnvVars{ "NODE_ENV": "production", "LOG_LEVEL": "info", }) if err != nil { log.Fatal(err) } fmt.Println(envs) // every variable of the app ``` ## Replacing every variable `Envs.Replace(ctx, appID, envs)` replaces **all** variables with the given set. Keys not in the map are removed. It returns the new set. ```go theme={"system"} if _, err := c.Apps.Envs.Replace(ctx, appID, squarecloud.EnvVars{"NODE_ENV": "production"}); err != nil { log.Fatal(err) } ``` ## Removing variables `Envs.Delete(ctx, appID, keys...)` removes the given keys and returns the remaining variables. It takes the keys as variadic arguments: pass a slice with `keys...`. ```go theme={"system"} remaining, err := c.Apps.Envs.Delete(ctx, appID, "LOG_LEVEL") if err != nil { log.Fatal(err) } fmt.Println(remaining) ``` ## Limits and errors | Status | Code | When | | - | - | - | | 400 | `STATIC_APP_ENV_NOT_SUPPORTED` | The app is static | | 400 | `INVALID_ENV_CONTENT` | The variables are not a valid object (or, for `Delete`, an empty list) | | 400 | `TOO_MANY_ENV_VARS` | The result would have more than 256 variables | | 400 | `ENV_NAME_TOO_LONG` | A key is over 1024 characters | | 400 | `ENV_CONTENT_TOO_LONG` | A value is over 4096 characters | | 400 | `READ_FAILED` | The cluster could not read the variables | ## Next steps Deploy on every push, with a webhook or the GitHub App. The REST endpoints behind these methods. The same actions from the terminal. Set variables from the dashboard, CLI or API and read them at runtime. # Go SDK: errors and retries Source: https://docs.squarecloud.app/en/sdks/go/errors Handle *APIError in the Go SDK: status, code and message, errors.As and errors.Is, the SDK's own codes, the Code constants, retries, timeouts and rate limits. Every API, network and local failure is one type: `*squarecloud.APIError`. Inspect it with `errors.As`. The shorter snippets below run inside the program from [Running the examples](/en/sdks/go/client#running-the-examples): paste one at a time into `main` and run `goimports`. ```go theme={"system"} package main import ( "context" "errors" "fmt" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) func main() { ctx := context.Background() c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID := "abc123def456abc123def456" err := c.Apps.Start(ctx, appID) var apiErr *squarecloud.APIError if errors.As(err, &apiErr) { fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message) fmt.Println(apiErr.Method, apiErr.Path) // "POST" "/v2/apps//start" } } ``` ## `APIError` | Field | Type | Description | | - | - | - | | `Status` | `int` | HTTP status. `0` when no response arrived (network error, timeout, local check) | | `Code` | `string` | The API's error code, e.g. `APP_NOT_FOUND`, or one of the SDK's codes. Compare it with the [`Code*` constants](#code-constants) | | `Message` | `string` | The server's explanation. `""` when the server sent only a code | | `Method` | `string` | HTTP method of the failed call | | `Path` | `string` | URL path of the failed call, without the query string | `Unwrap()` returns the cause (the transport, decoding or context error) for `NETWORK_ERROR`, `TIMEOUT` and invalid JSON, or `nil`. `Error()` renders `squarecloud: : HTTP : `, without `HTTP ` when the status is `0` and without `: ` when it is empty. Match on the fields, not on this text. ### Canceled and expired contexts A call whose `ctx` is canceled returns an `*APIError` with `NETWORK_ERROR`, and one whose deadline passes returns `TIMEOUT`, both with status `0`. They unwrap to the context's error: ```go theme={"system"} _, err := c.Apps.Get(ctx, appID) switch { case errors.Is(err, context.Canceled): // you canceled ctx case errors.Is(err, context.DeadlineExceeded): // the deadline of ctx, or the default one, passed } ``` A few failures are not `*APIError`: * [`Realtime.Next`](/en/sdks/go/realtime#ending-the-stream) returns the bare `ctx.Err()` when its `ctx` ends, and `io.EOF` when the stream ends normally. * Caller-side problems are plain errors: a `nil` upload reader, a snapshot URL or base URL that cannot be parsed, an input `encoding/json` cannot encode, and an error of the `io.Writer` passed to `DownloadSnapshot`. ## SDK codes | Status | Code | Constant | When | | - | - | - | - | | 0 | `NETWORK_ERROR` | `CodeNetworkError` | No response (DNS, connection reset, body cut off), or `ctx` canceled. The original error is in `Unwrap()` | | 0 | `TIMEOUT` | `CodeTimeout` | No response before the deadline (see [Timeouts](/en/sdks/go/client#timeouts)) | | 0 | `FILE_TOO_LARGE` | `CodeFileTooLarge` | Local check: an upload over 100 MB or a `Files.Write` over 10 MB. Nothing was sent | | 0 | `INVALID_ID` | `CodeInvalidID` | Local check: an id that is empty, `.` or `..`. Nothing was sent | | 0 | `INVALID_API_KEY` | `CodeInvalidAPIKey` | Local check: the client was built with an empty key. Every call except `Service.Status`. Only in the Go SDK | | any | `UNKNOWN_ERROR` | `CodeUnknown` | A response without a code (such as a proxy error page), with the real `Status` and the message `HTTP `. A 2xx body that is not JSON has the message `Invalid JSON in HTTP response` | ## `Code*` constants `Code` is a plain `string`. The package has one constant per public API code, named after it in Go style (`CodeAppNotFound` for `APP_NOT_FOUND`, `CodeInvalidID`, `CodeDNSFailed`, ...), plus the SDK's own codes above. `CodeRateLimit` (`RATE_LIMIT`) and `CodeRateLimitExceeded` (`RATE_LIMIT_EXCEEDED`) are still exported, marked deprecated: the API now answers `RATE_LIMITED` (`CodeRateLimited`) for both. The list of API codes grows. **Handle an unknown code by its HTTP status**: ```go theme={"system"} func handle(err error) error { var apiErr *squarecloud.APIError if !errors.As(err, &apiErr) { return err // not from the SDK } switch apiErr.Code { case squarecloud.CodeAppNotFound, squarecloud.CodeContainerAlreadyStarted: return nil // expected: nothing to do } switch { case apiErr.Status == 429: log.Printf("rate limited, try again later: %v", apiErr) case apiErr.Status >= 500: log.Printf("Square Cloud had a server error: %v", apiErr) } return err } ``` ## API error codes Every other code comes from the API. The [API error reference](/en/api-reference/errors) lists each one with its HTTP status, meaning and fix, and each SDK page lists the codes its methods return most often. Any call can also answer 401 `ACCESS_DENIED` (a bad key), 403 `MISSING_SCOPE` or `RESOURCE_NOT_ALLOWED` (the [limits of the key](/en/sdks/go/client#api-key-and-scopes)), 429 (see [Rate limits](#rate-limits)) or 503 `DATABASE_UNAVAILABLE`. `AI.Chat` errors use lowercase OpenAI codes instead (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...), which `Code` carries verbatim. See [AI](/en/sdks/go/ai#errors). ## Retries The SDK only retries what is safe to repeat, up to `WithMaxRetries` times (default `2`, so up to 3 attempts): | Retried | Methods | | - | - | | `NETWORK_ERROR` | `GET` only (realtime opens and `DownloadSnapshot` before the response included) | | 503 `UPLOAD_BUSY` | Any method | | 503 `ANALYTICS_BUSY` | Any method | | 503 `DATABASE_UNAVAILABLE` | `GET` only | It **never** retries: * `TIMEOUT`; * any **429**: `RATE_LIMITED` can be a block of about 30 minutes, and `KEEP_CALM` is not retried either; * other 5xx; * AI errors. 503 `DATABASE_UNAVAILABLE` can arrive after a mutation was already applied, so the SDK does not retry it outside `GET`. Retry your own idempotent mutations if you need to. An upload is retried only when its body can be replayed: an `io.ReaderAt` with a known size, such as an `*os.File` (see [Commit and upload](/en/sdks/go/commit_and_upload#accepted-inputs)). The wait before retry `n` (starting at 0) is `min(8 s, 500 ms · 2^n) · U(0.5, 1)`: exponential backoff with 50% to 100% jitter. Set `WithMaxRetries(0)` to turn retries off. ## Timeouts `WithTimeout` (30 s) applies only when `ctx` has no deadline, and one deadline covers the whole call, retries and backoff waits included. See [Timeouts](/en/sdks/go/client#timeouts) for the calls with a 2-minute floor and the calls with no default deadline. A deadline that passes returns `TIMEOUT` with status `0`, is never retried, and unwraps to `context.DeadlineExceeded`. ## Rate limits Every account has a limit of requests per 60 seconds, set by its plan ([values](/en/api-reference/limitations-and-restrictions)), and some routes have their own: * **429 `RATE_LIMITED`**: the account or API key went over its request budget and is blocked for about 30 minutes, or an IP that keeps sending invalid keys is blocked for a short period. Also the limit of the network endpoints and `Account.Snapshots`. * **429 `KEEP_CALM`**: too many calls to one route in a short time. The SDK never retries a 429. Slow down, and wait before trying again. ## Next steps Every error code, with its meaning and fix. The request limits of each plan. # Go SDK: manage applications Source: https://docs.squarecloud.app/en/sdks/go/managing_application Fetch, inspect and control your applications with the Go SDK: details, status, start, stop, restart, logs, metrics, domains, load balancers and deletion. Every method on this page lives on `c.Apps` and takes `ctx` first, then the app id. An `appID` can also be the composite `-` of an app shared through a [workspace](/en/sdks/go/workspaces). Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` To list your apps, use [`c.Account.Me`](/en/sdks/go/client#account): its `Applications` slice has every app the key can see. ## Getting an application ```go theme={"system"} app, err := c.Apps.Get(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(app.ID, app.Name, app.Language, app.RAM, app.Cluster, app.CreatedAt) ``` | Field | Type | Description | | - | - | - | | `ID` (`id`) | `string` | App id | | `Name` (`name`) | `string` | Display name | | `Description` (`desc`) | `string` | Description, `""` when unset | | `Owner` (`owner`) | `string` | Owner's user id | | `Cluster` (`cluster`) | `string` | Cluster the app runs on | | `RAM` (`ram`) | `int` | Allocated RAM in MB | | `Language` (`language`) | `string` | Runtime language | | `Domain` (`domain`) | `*string` | Default `.squareweb.app` host; `nil` for non-web apps | | `Custom` (`custom`) | `*string` | Custom domain; `nil` when none is set | | `CreatedAt` (`created_at`) | `time.Time` | Creation date | ## Status `Status(ctx, appID)` returns the live state with **formatted** values: ```go theme={"system"} status, err := c.Apps.Status(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(status.Status) // e.g. "running", "exited" fmt.Println(status.Running) // true fmt.Println(status.CPU) // "0.5%" fmt.Println(status.RAM) // "120.4MB" (RAM in use) fmt.Println(status.Storage, status.Network.Total, status.Network.Now) if status.Uptime != nil { fmt.Println(*status.Uptime) // Unix ms of the last start; nil when stopped } ``` `StatusRaw(ctx, appID)` returns **numbers** instead (`CPU` in %, `RAM` in MB, `Storage` in bytes, `Network.Total` and `Network.Now` as `[in, out]` byte pairs): ```go theme={"system"} raw, err := c.Apps.StatusRaw(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(raw.CPU, raw.RAM, raw.Network.Total) // 0.5 120.4 [1024 2048] ``` `Uptime` is a **timestamp** (when the app started), not a duration. Use `time.Since(time.UnixMilli(*status.Uptime))` for how long it has been up. ### Status of every application `StatusAll(ctx, workspaceID)` returns one summary per app the key can see, in a single request. Pass `""` for all apps, or a workspace id for the apps of that [workspace](/en/sdks/go/workspaces#acting-on-a-shared-app) only. `CPU` and `RAM` are only set (not `""`) while the app runs. ```go theme={"system"} items, err := c.Apps.StatusAll(ctx, "") if err != nil { log.Fatal(err) } for _, it := range items { if it.Running { fmt.Println(it.ID, it.CPU, it.RAM) } else { fmt.Println(it.ID, "stopped") } } ``` ## Start, stop and restart ```go theme={"system"} if err := c.Apps.Start(ctx, appID); err != nil { log.Fatal(err) } if err := c.Apps.Stop(ctx, appID); err != nil { log.Fatal(err) } if err := c.Apps.Restart(ctx, appID); err != nil { log.Fatal(err) } ``` The server holds these calls open until the container acts, so without a `ctx` deadline they wait at least 2 minutes before timing out. When the platform refuses the action, the call returns an `*APIError` with status **409**, a `Code` and an **empty** `Message`: | Code | Meaning | | - | - | | `CONTAINER_ALREADY_STARTED` | `start` on a running app | | `CONTAINER_ALREADY_STOPPED` | `stop` on a stopped app | | `CONTAINER_TEMPORARILY_SUSPENDED` | The app is suspended | | `CONTAINER_NOT_FOUND` | The container does not exist on the cluster | | `CONTAINER_INSUFFICIENT_DISK_SPACE` | Not enough disk to start | | `CONTAINER_NETWORK_CONFLICT` | Network conflict on the cluster | | `ACTION_FAILED` | The cluster could not perform the action | "Already started" and "already stopped" are errors too. If they mean success for you, handle them: ```go theme={"system"} err := c.Apps.Start(ctx, appID) var apiErr *squarecloud.APIError if err != nil && !(errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeContainerAlreadyStarted) { log.Fatal(err) } ``` ## Logs `Logs(ctx, appID)` returns the latest console output as one string (`""` when there is none). ```go theme={"system"} logs, err := c.Apps.Logs(ctx, appID) if err != nil { log.Fatal(err) } fmt.Println(logs) ``` For a live stream of logs, use [Realtime](/en/sdks/go/realtime). ## Metrics `Metrics(ctx, appID)` returns the last 24 hours, one point every 5 minutes, **newest first**. ```go theme={"system"} points, err := c.Apps.Metrics(ctx, appID) if err != nil { log.Fatal(err) } if len(points) > 0 { latest := points[0] fmt.Println(latest.Date, latest.CPU, latest.RAM, latest.Net) } ``` ## Domains and load balancers `Domains(ctx)` lists the default and custom hostnames of every app. `LoadBalancers(ctx)` lists the domains shared by several apps, with your plan's limit. ```go theme={"system"} domains, err := c.Apps.Domains(ctx) if err != nil { log.Fatal(err) } for _, d := range domains { fmt.Println(d.AppID, d.Hostname, d.Type) // Type: "subdomain" | "custom" } lb, err := c.Apps.LoadBalancers(ctx) if err != nil { log.Fatal(err) } fmt.Println(lb.Limit) for _, balancer := range lb.Balancers { ids := make([]string, 0, len(balancer.Apps)) for _, app := range balancer.Apps { ids = append(ids, app.ID) } fmt.Println(balancer.Hostname, ids) } ``` To set a custom domain, see [Network](/en/sdks/go/network#custom-domain). ## Deleting an application ```go theme={"system"} if err := c.Apps.Delete(ctx, appID); err != nil { log.Fatal(err) } ``` Deletion is permanent. Create a [snapshot](/en/sdks/go/snapshots) first if you may need the files again. ## Next steps Create an app from a zip or send files to one. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: app file manager Source: https://docs.squarecloud.app/en/sdks/go/managing_files List, read, write, move and delete the files of an application with c.Apps.Files. Content travels as base64, so text and binary files round-trip byte for byte. The file manager lives on `c.Apps.Files`. Every method takes `ctx` and the app id first, then a path inside the app. Paths are at most **256 characters**. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` ## Listing a directory `Files.List(ctx, appID, path)` lists a directory (`""` for the app root). ```go theme={"system"} entries, err := c.Apps.Files.List(ctx, appID, "/src") if err != nil { log.Fatal(err) } for _, entry := range entries { fmt.Println(entry.Type, entry.Name, entry.Size) if entry.LastModified != nil { fmt.Println(time.UnixMilli(int64(*entry.LastModified))) } } ``` | Field | Type | Description | | - | - | - | | `Name` (`name`) | `string` | Entry name | | `Type` (`type`) | `string` | `"file"` or `"directory"` | | `Size` (`size`) | `int64` | Size in bytes. `0` on directory entries the API sends without it | | `LastModified` (`lastModified`) | `*float64` | Unix ms (may carry a fraction); `nil` when unreadable | A directory that does not exist is 404 `FILE_NOT_FOUND`. A path the file manager does not expose is 403 `BLOCKED_PATH`. ## Reading a file `Files.Read(ctx, appID, path)` returns the file's bytes as a `[]byte`. Files are limited to **10 MB**: a larger one is 413 `FILE_TOO_LARGE`. ```go theme={"system"} data, err := c.Apps.Files.Read(ctx, appID, "/config.json") if err != nil { log.Fatal(err) } var config map[string]any if err := json.Unmarshal(data, &config); err != nil { log.Fatal(err) } fmt.Println(config) ``` ## Writing a file `Files.Write(ctx, appID, path, content)` creates or overwrites a file. `content` is a `[]byte`: * It is **always sent as base64**, so text and binary content round-trip byte for byte. To write a string, pass `[]byte(s)`. * Empty content (`nil` or an empty slice) creates an empty file. ```go theme={"system"} // Text config, err := json.Marshal(map[string]bool{"debug": false}) if err != nil { log.Fatal(err) } if err := c.Apps.Files.Write(ctx, appID, "/config.json", config); err != nil { log.Fatal(err) } // Binary res, err := http.Get("https://example.com/logo.png") if err != nil { log.Fatal(err) } defer res.Body.Close() image, err := io.ReadAll(res.Body) if err != nil { log.Fatal(err) } if err := c.Apps.Files.Write(ctx, appID, "/assets/logo.png", image); err != nil { log.Fatal(err) } ``` Content over **10 MB** fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Content over **1 MiB** gets no default deadline, like an upload: bound or cancel it with `ctx`. For larger files, use [`Apps.Commit`](/en/sdks/go/commit_and_upload). Writing does not restart the app. Call [`Apps.Restart`](/en/sdks/go/managing_application#start-stop-and-restart) to apply the change. ## Moving or renaming a file ```go theme={"system"} if err := c.Apps.Files.Move(ctx, appID, "/config.json", "/config.old.json"); err != nil { log.Fatal(err) } ``` ## Deleting a file ```go theme={"system"} if err := c.Apps.Files.Delete(ctx, appID, "/config.old.json"); err != nil { log.Fatal(err) } ``` ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | `Write` content over 10 MB (checked locally) | | 400 | `INVALID_PATH` | The path fails validation (traversal, invalid characters, too long), or `Move` to the same path | | 400 | `DELETE_FAILED`, `RENAME_FAILED` | The cluster could not delete or rename the file | | 403 | `BLOCKED_PATH` | The path is not exposed by the file manager | | 403 | `PERMISSION_DENIED` | Your workspace role cannot touch a restricted file (such as `.env`) | | 404 | `FILE_NOT_FOUND` | The file or directory does not exist | | 413 | `FILE_TOO_LARGE` | `Read` of a file over 10 MB | | 429 | `KEEP_CALM` | More than 10 writes in 5 seconds | See [Errors](/en/sdks/go/errors) for the codes every call can return. ## Next steps Read and change the variables of an app. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: migrating from v2 to v3 Source: https://docs.squarecloud.app/en/sdks/go/migrating_to_v3 Upgrade the Square Cloud Go SDK from v2 to v3: one package, a concrete *Client, ctx first, resource groups, one error type and a method-by-method table. v3 is a breaking release. It uses one package, a concrete `*Client`, `ctx` as the first argument everywhere and resource groups, and it fixes every known v2 bug. It covers all 67 operations of the current API. ## At a glance | | v2 | v3 | | - | - | - | | Module | `.../v2` (`rest` + `squarecloud` packages) | `github.com/squarecloudofc/sdk-api-go/v3` (one package) | | Client | `rest.New(rest.NewClient(key, ...))` (interface) | `squarecloud.New(key, ...Option)` (`*Client`) | | Calls | `api.GetApplicationStatus(id, rest.WithContext(ctx))` | `c.Apps.Status(ctx, id)` | | Errors | `*rest.APIError` with `StatusCode`, network errors untyped | `*squarecloud.APIError` with `Status`, `Code`, `Message`, `Method`, `Path` for everything | | Timeouts | `http.Client` with a fixed 30 s `Timeout` on everything | Per call through `ctx`; `WithTimeout`; streams unbounded | | Retries | None | GET network errors and 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY`/`DATABASE_UNAVAILABLE` (`WithMaxRetries`) | | Logging | `WithLogger` (leaked secrets) | None | | Go | 1.24 | 1.22 or newer | | License | AGPL-3.0 | MIT | ## Construction and options ```diff theme={"system"} -import ( - "github.com/squarecloudofc/sdk-api-go/v2/rest" - "github.com/squarecloudofc/sdk-api-go/v2/squarecloud" -) -client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger)) -api := rest.New(client) -defer client.Close() +import "github.com/squarecloudofc/sdk-api-go/v3" + +c := squarecloud.New(token, squarecloud.WithUserAgent(ua)) ``` ```bash theme={"system"} go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0 ``` | v2 | v3 | | - | - | | Packages `rest` + `squarecloud` | One package `squarecloud` (module `.../v3`) | | `rest.NewClient(token, opts...)` + `rest.New(client)` | `squarecloud.New(token, opts...)` | | `rest.Rest` (interface) | `*squarecloud.Client` (concrete struct). To mock it, declare your own small interface or use `httptest` | | `rest.ConfigOpt` | `squarecloud.Option` | | `rest.WithHTTPClient(hc)` | `squarecloud.WithHTTPClient(hc)`. Do not set `hc.Timeout`: it would cut realtime streams and downloads | | `rest.WithURL(u)` | `squarecloud.WithBaseURL(u)` (still includes `/v2`) | | `rest.WithUserAgent(ua)` | `squarecloud.WithUserAgent(ua)` | | `rest.WithLogger(l)` | Removed: the SDK never logs (v2 leaked secrets in debug logs). Wrap `hc.Transport` to trace | | `client.Close()`, `client.HTTPClient()` | Removed: keep your own `*http.Client` and call `CloseIdleConnections` on it | | `rest.APIURL`, `rest.APIVersion`, `rest.Endpoint*` | Removed; `squarecloud.DefaultBaseURL` is a constant | | (none) | `squarecloud.WithMaxRetries(n)` (new; default 2) | | Fixed 30 s `http.Client` timeout | `squarecloud.WithTimeout(d)` (new; default 30 s, `d <= 0` disables every default deadline) | Per-request options: | v2 | v3 | | - | - | | `rest.WithContext(ctx)` | `ctx` is the first argument of every method | | `rest.WithToken(token)` (e.g. validating a key at login) | Build a throwaway client: `squarecloud.New(token).Account.Me(ctx)` (cheap, no connections are held) | | `rest.WithQueryParam("path", dir)` on commit | `c.Apps.Commit(ctx, id, r, dir, "")` | | `rest.WithQueryParam(filter, v)` on analytics | `c.Apps.Network.Analytics(ctx, id, start, end, squarecloud.AnalyticsFilters{...})` with `Country`, `IP`, `Path`, `Status`, `OS`, `Browser`, `Protocol`, `Referer`, `Provider`, `ContentType`, `Bot` | | `rest.WithQueryParam("include_4xx", "true")` | `c.Apps.Network.Errors(ctx, id, start, end, true)` | | `rest.WithQueryParam("workspaceId", ws)` on list status | `c.Apps.StatusAll(ctx, ws)` | | `rest.WithHeader`, `rest.RequestOpt`, `rest.RequestConfig`, `rest.DefaultRequestConfig` | Removed | ## Method by method `api` is the v2 `rest.Rest`, `c` the v3 `*squarecloud.Client`. | v2 | v3 | Notes | | - | - | - | | `api.SelfUser()` | `me, err := c.Account.Me(ctx)`, then `me.User` | Returns `Account` | | `api.GetApplications()` | `c.Account.Me(ctx)`, then `me.Applications` (`[]AppSummary`) | | | `api.GetDatabases()` | `c.Account.Me(ctx)`, then `me.Databases` (`[]DatabaseSummary`) | | | `api.UserSnapshots(scope)` | `c.Account.Snapshots(ctx, scope)` | | | `api.ServiceStatus()` | `c.Service.Status(ctx)` | New model, see [Types](#types) | | `api.PostApplications(r)` → `*ApplicationUploaded` | `c.Apps.Create(ctx, r)` → `AppCreated` (a value) | v2 buffered the zip in memory and named the part `upload.zip`; v3 streams it and names the part after an `*os.File` (its base name), else `app.zip`. `Subdomain` is gone: read `Domain`, the full host (`my-app.squareweb.app`), `""` for non-web apps | | `api.GetApplication(id)` | `c.Apps.Get(ctx, id)` | | | `api.DeleteApplication(id)` | `c.Apps.Delete(ctx, id)` | | | `api.PostApplicationSignal(id, squarecloud.ApplicationSignalStart/Stop/Restart)` | `c.Apps.Start(ctx, id)` / `c.Apps.Stop(ctx, id)` / `c.Apps.Restart(ctx, id)` | | | `api.PostApplicationCommit(id, r, rest.WithQueryParam("path", p))` | `c.Apps.Commit(ctx, id, r, p, filename)` | v2 always named the part `commit.zip`; v3 uses `filename`, else an `*os.File`'s own name, so a single non-zip file now lands under its own name instead of failing as a zip | | `api.GetApplicationStatus(id)` | `c.Apps.Status(ctx, id)` | | | `api.GetApplicationStatusRaw(id)` | `c.Apps.StatusRaw(ctx, id)` | | | `api.GetApplicationListStatus()` | `c.Apps.StatusAll(ctx, "")` | Returns `[]StatusListItem` | | `api.GetApplicationLogs(id)` → `ApplicationLogs` | `c.Apps.Logs(ctx, id)` → `string` | | | `api.GetApplicationMetrics(id)` | `c.Apps.Metrics(ctx, id)` | Points come newest first, as the API sends them | | `api.ApplicationRealtime(id, rest.WithContext(ctx))` | `c.Apps.Realtime(ctx, id)` | Returns `*Realtime`; see [Behavior changes](#behavior-changes) | | `api.GetApplicationDomains()` | `c.Apps.Domains(ctx)` | | | `api.GetLoadBalancers()` | `c.Apps.LoadBalancers(ctx)` | | | `api.GetApplicationEnvs(id)` | `c.Apps.Envs.Get(ctx, id)` | | | `api.SetApplicationEnvs(id, envs)` | `c.Apps.Envs.Set(ctx, id, envs)` | | | `api.ReplaceApplicationEnvs(id, envs)` | `c.Apps.Envs.Replace(ctx, id, envs)` | | | `api.DeleteApplicationEnvs(id, keys)` → `error` | `c.Apps.Envs.Delete(ctx, id, keys...)` → `(EnvVars, error)` (the remaining variables) | | | `api.GetApplicationFiles(id, path)` → `[]FileInfo` | `c.Apps.Files.List(ctx, id, path)` → `[]FileEntry` | A missing directory is now 404 `FILE_NOT_FOUND` (it was an empty list); a protected path is 403 `BLOCKED_PATH` | | `api.ReadApplicationFile(id, path)` → `FileContent` | `c.Apps.Files.Read(ctx, id, path)` → `[]byte` | Requested as base64 and decoded; a file over 10 MB is 413 `FILE_TOO_LARGE` | | `api.PutApplicationFile(id, path, b)` → `(FileWritten, error)` | `c.Apps.Files.Write(ctx, id, path, b)` → `error`. Drop any `written` check: success is a `nil` error | The content is always sent base64-encoded, so binary files are safe; empty content writes an empty file | | `api.MoveApplicationFile(id, from, to)` | `c.Apps.Files.Move(ctx, id, path, to)` | | | `api.DeleteApplicationFile(id, path)` | `c.Apps.Files.Delete(ctx, id, path)` | Works now (always 400 in v2) | | `api.GetApplicationSnapshots(id)` | `c.Apps.Snapshots.List(ctx, id)` | Each `Snapshot` now carries `VersionID` and `URL` (signed download link) from the API | | `api.CreateApplicationSnapshot(id)` | `c.Apps.Snapshots.Create(ctx, id)` | Check `.Pending` (202) before using `.URL` | | `api.RestoreApplicationSnapshot(id, snapID, verID)` | `c.Apps.Snapshots.Restore(ctx, id, snap.Name, snap.VersionID)` | `VersionID` is a field the API sends: nothing needs to be parsed out of `Key` any more. See [Snapshots](/en/sdks/go/snapshots#restoring-a-snapshot) for the errors | | `api.GetApplicationDeployments(id)` | `c.Apps.Deploys.List(ctx, id)` | | | `api.GetApplicationCurrentDeployment(id)` | `c.Apps.Deploys.Current(ctx, id)` | | | `api.PostApplicationDeployWebhook(id, token)` → `GithubWebhook` | `c.Apps.Deploys.SetWebhook(ctx, id, token)` → `string` | | | `api.LinkApplicationGithubApp(id, repo, branch)` → `GithubAppLink` | `c.Apps.Deploys.LinkGithubApp(ctx, id, repo, branch)` → `LinkedRepository` | API keys work now (scope `apps:deploy`); the `repository` wrapper is gone; an account without a connected GitHub is 403 `GITHUB_NOT_CONNECTED` | | `api.UnlinkApplicationGithubApp(id)` | `c.Apps.Deploys.UnlinkGithubApp(ctx, id)` | 400 `GIT_NOT_CONFIGURED` without a link | | `api.GetApplicationDNS(id)` | `c.Apps.Network.DNS(ctx, id)` | | | `api.SetApplicationCustomDomain(id, d)` | `c.Apps.Network.SetDomain(ctx, id, d)` | | | `api.GetApplicationAnalytics(id, s, e, opts...)` | `c.Apps.Network.Analytics(ctx, id, s, e, squarecloud.AnalyticsFilters{...})` | Returns `*NetworkAnalytics`, `nil` for a window with no traffic | | `api.GetApplicationNetworkErrors(id, s, e, opts...)` | `c.Apps.Network.Errors(ctx, id, s, e, include4xx)` | Returns `*NetworkErrors`, `nil` when empty | | `api.GetApplicationNetworkLogs(id, s, e)` | `c.Apps.Network.Logs(ctx, id, s, e)` | | | `api.GetApplicationNetworkPerformance(id, s, e)` | `c.Apps.Network.Performance(ctx, id, s, e)` | Returns `*NetworkPerformance`, `nil` when empty | | `api.PurgeApplicationCache(id)` | `c.Apps.Network.PurgeCache(ctx, id)` | | | `api.CreateDatabase(opts)` | `c.Databases.Create(ctx, squarecloud.DatabaseCreate{...})` | | | `api.GetDatabase(id)` | `c.Databases.Get(ctx, id)` | | | `api.UpdateDatabase(id, opts)` | `c.Databases.Update(ctx, id, squarecloud.DatabaseUpdate{...})` | | | `api.DeleteDatabase(id)` | `c.Databases.Delete(ctx, id)` | | | `api.StartDatabase(id)` / `api.StopDatabase(id)` | `c.Databases.Start(ctx, id)` / `c.Databases.Stop(ctx, id)` | | | `api.GetDatabaseStatus(id)` / `api.GetDatabaseStatusRaw(id)` | `c.Databases.Status(ctx, id)` / `c.Databases.StatusRaw(ctx, id)` | | | `api.GetDatabaseListStatus()` | `c.Databases.StatusAll(ctx)` | Returns `[]StatusListItem` | | `api.GetDatabaseMetrics(id)` | `c.Databases.Metrics(ctx, id)` | | | `api.GetDatabaseCertificate(id)` → `DatabaseCertificate` | `c.Databases.Certificate(ctx, id)` → `string` (base64 PEM) | | | `api.ResetDatabaseCredentials(id, t)` → `DatabasePasswordReset` | `c.Databases.ResetCredentials(ctx, id, t)` → `string` | The new password, `""` for certificate resets | | `api.GetDatabaseSnapshots` / `CreateDatabaseSnapshot` / `RestoreDatabaseSnapshot` | `c.Databases.Snapshots.List` / `Create` / `Restore` | As for apps: restore with `snap.Name` and `snap.VersionID` | | `api.GetWorkspaces()` | `c.Workspaces.List(ctx)` | | | `api.GetWorkspace(id)` | `c.Workspaces.Get(ctx, id)` | | | `api.CreateWorkspace(name)` | `c.Workspaces.Create(ctx, name)` | | | `api.DeleteWorkspace(id)` | `c.Workspaces.Delete(ctx, id)` | | | `api.LeaveWorkspace(id)` | `c.Workspaces.Leave(ctx, id)` | | | `api.AddWorkspaceMember(ws, code, group)` | `c.Workspaces.Members.Add(ctx, ws, code, group)` | | | `api.UpdateWorkspaceMember(ws, member, group)` | `c.Workspaces.Members.Update(ctx, ws, member, group)` | | | `api.RemoveWorkspaceMember(ws, member)` | `c.Workspaces.Members.Remove(ctx, ws, member)` | | | `api.GetWorkspaceInviteCode()` → `WorkspaceInviteCode` | `c.Workspaces.Members.InviteCode(ctx)` → `string` | | | `api.AddWorkspaceApplication(ws, app)` / `RemoveWorkspaceApplication` | `c.Workspaces.Apps.Add(ctx, ws, app)` / `Remove` | | | Downloading a snapshot URL yourself (`http.Get`) | `c.DownloadSnapshot(ctx, url, w)` | Streams into any `io.Writer`; never sends the key | | `rest.IsRateLimit(err)` | `errors.As(err, &apiErr) && apiErr.Status == 429` | Removed | | `rest.ErrorCode(err)` | `errors.As(err, &apiErr)`, then `apiErr.Code` | Removed | | `client.Request(...)`, `client.Stream(...)` (`rest.Client`) | The typed methods above | Removed: every operation has its own method | | `rest.NewApplications(client)`, `rest.NewDatabases(client)`, `rest.NewWorkspaces(client)` | `squarecloud.New(key)`, then the `c.Apps`, `c.Databases`, `c.Workspaces` fields | Removed | | `rest.Applications`, `rest.Databases`, `rest.Workspaces` (interfaces) | `squarecloud.AppsAPI`, `DatabasesAPI`, `WorkspacesAPI` (the types of those fields) | Removed; declare your own interface to mock | | `rest.Config`, `rest.DefaultConfig()`, `(*rest.Config).Apply(opts)` | `squarecloud.New(key, opts...)` with `WithHTTPClient`, `WithBaseURL`, `WithUserAgent` | Removed (use `Option`; there is no logger) | | `(*rest.RequestConfig).Apply(opts)` | Pass `ctx` and typed arguments | Removed | | `(*rest.RealtimeStream).Next()` / `Close()` | `(*squarecloud.Realtime).Next()` / `Close()` | `Next` returns `io.EOF` after `REALTIME_DISCONNECTED` | | (none) | `c.AI.Chat(ctx, squarecloud.ChatRequest{...})` | New | ## Types | v2 (`squarecloud.`) | v3 (`squarecloud.`) | | - | - | | `User` (from `SelfUser`) | `User` (inside `Account`, the result of `Account.Me`) | | `UserPlan`, `UserPlanMemory` | `Plan`, `PlanMemory`. `Plan.Duration` is the expiry in Unix **milliseconds** (`*int64`, `nil` when it never expires): convert it with `time.UnixMilli`, not `time.Unix` | | `UserApplication`, `UserDatabase` (`Type string`) | `AppSummary`, `DatabaseSummary` (`Type DatabaseType`) | | `Application` | `App` | | `ApplicationUploaded` (`CPU int`), `ApplicationLanguage` | `AppCreated` (`CPU float64`), `AppLanguage` | | `ApplicationStatus`, `DatabaseStatus` | `RuntimeStats` (shared) | | `ApplicationStatusRaw`, `DatabaseStatusRaw` | `RuntimeStatsRaw` | | `ApplicationStatusNetwork`, `ApplicationStatusNetworkRaw` | `StatsNetwork`, `StatsNetworkRaw` | | `ApplicationStatusListItem`, `DatabaseStatusListItem` | `StatusListItem` | | `ApplicationLogs` | `string` | | `ApplicationSignal*` | Removed (use `Start`/`Stop`/`Restart`) | | `FileInfo` (`Type FileType`, `LastModified int64`), `FileType*` constants | `FileEntry` (`Type string`, `LastModified *float64`): `"file"`/`"directory"`; the API sends fractional Unix ms, or `null` | | `FileContent`, `ByteArray` | `[]byte` | | `FileWritten` | Removed (undocumented field) | | `Deployment` (`State DeploymentState`) | `DeployEvent` (`State`, `Source`, `Code`, `Message` as `string`). `Source` is new, always `"git"`; an `"error"` event carries `Code`, e.g. `CLONE_FAILED`, and sometimes `Message` | | `DeploymentState*` (`DeploymentStateError` = `"error"`) | `Deploy*` string constants (`DeployPending`, `DeployClone`, `DeployCommit`, `DeployRestarting`, `DeploySuccess`, `DeployError` = `"error"`) | | `DeploymentFiles`, `DeploymentCurrent`, `DeploymentGithubApp` | `DeployFiles`, `DeployCurrent`, `DeployRepository` | | `GithubWebhook` | `string` | | `GithubAppLink`, `GithubAppRepository` | `LinkedRepository` with `ID`, `FullName`, `Branch` (returned directly, no `Repository` wrapper) | | `Snapshot` | `Snapshot` + `VersionID`, `URL`, `Runtime`, `Origin` (all fields the API sends) | | `SnapshotCreated` | `SnapshotCreated` + `Pending` | | `DatabaseType` with `DatabaseTypeMongo`, `DatabaseTypeMySQL`, `DatabaseTypeRedis`, `DatabaseTypePostgres` | `DatabaseType` (unchanged) with `DatabaseMongo`, `DatabaseMySQL`, `DatabaseRedis`, `DatabasePostgres` (constants renamed) | | `DatabaseCreateOptions`, `DatabaseUpdateOptions` | `DatabaseCreate`, `DatabaseUpdate` | | `DatabaseCreated` (`CPU int`, `Certificate string`) | `DatabaseCreated` (`CPU float64`, `Certificate *string`, `nil` when the API sends none) | | `DatabaseResetType`, `DatabaseResetPassword`, `DatabaseResetCertificate` | `DatabaseReset`, `ResetPassword`, `ResetCertificate` | | `DatabaseCertificate`, `DatabasePasswordReset` | `string` | | `WorkspaceMemberGroup`, `WorkspaceGroup*` | Input: `WorkspaceGroup` (`GroupAdmin`, `GroupMaintain`, `GroupManager`, `GroupView`); `WorkspaceMember.Group` is a `string` (may be `"owner"`) | | `WorkspaceMember` (`Name string`) | `WorkspaceMember` (`Name *string`, `nil` when the API sends `null`). Workspace ids are 32 or 40 hex characters | | `WorkspaceInviteCode` | `string` | | `ServiceStatus` (`Status`, `Message`) | `ServiceStatus` (`Status`, `Message`, `CheckedAt`, `Stale`, `Services`, `Dependencies`). `Status` is now e.g. `"online"`; entries are `ServiceEntry` | | `rest.RealtimeStream` | `*squarecloud.Realtime` (`Next`, `Close`) | | `RealtimeEvent` (`Event`, `Data`) | `RealtimeEvent` (`Event`, `Data`, `ID`, `Stream`, `Line`, `Status`) | | Query options on analytics | `AnalyticsFilters` (no `Start`/`End`: they are arguments) | | `NetworkErrorsSummaryClass` (`Class4xx`, `Class5xx`) | `NetworkErrorsSummary.ByClass`, a `map[string]int64` with keys `"4xx"` and `"5xx"` | | `NetworkErrorsByStatus`, `NetworkErrorsTimeseries`, `NetworkErrorsTopPath`, `NetworkErrorsByMethod` | `NetworkErrorsStatus`, `NetworkErrorsBucket`, `NetworkErrorsPath`, `NetworkErrorsMethod` | | `NetworkLatency`, `NetworkPerformance*` | `Percentiles` (`P50`/`P95`/`P99` are `*float64`, `nil` for a window with no requests), `PerformanceSummary`, `PerformanceBucket`, `PerformanceRegion` (countries and colos; `P50`/`P95` `*float64`, `City`/`Country` `*string`), `PerformancePath` (`P95`/`P99` `*float64`) | | `RealtimeStatus` | `RealtimeStatus.CPULimit` is a number of cores (e.g. `1`, `0.5`) | | Analytics provider values | `"NAME (ASN)"` (e.g. `"GOOGLE (15169)"`); `AnalyticsFilters.Provider` takes that exact value | | `AppDomainType*` | `AppDomain.Type` is a `string` | | `APIResponse[T]` | Removed (internal) | | `int` sizes and counters (`FileInfo.Size`, `Snapshot.Size`, analytics `Visits`/`Requests`, network error totals and maps, performance `Requests`) | `int64` | ## Errors `rest.APIError` (`StatusCode`, `Code`, `Message`) becomes `squarecloud.APIError` (`Status`, `Code`, `Message`, `Method`, `Path`): rename `StatusCode` to `Status`. `rest.ErrorCode(err)` and `rest.IsRateLimit(err)` were removed: use `errors.As` and check `Code` or `Status == 429`. ```go theme={"system"} // v2 if rest.IsRateLimit(err) { ... } // v3 var apiErr *squarecloud.APIError if errors.As(err, &apiErr) && apiErr.Status == 429 { fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED } ``` * Network failures are now `*APIError` with `Status` `0`, `Code` `NETWORK_ERROR` or `TIMEOUT` and the cause's text as `Message`, and they unwrap to the cause (`errors.Is(err, context.Canceled)` works). * So are local checks (`Status` `0`: `INVALID_ID`, `FILE_TOO_LARGE`, `INVALID_API_KEY`) and a 2xx body that is not JSON (`UNKNOWN_ERROR`, `Invalid JSON in HTTP response`). * A 2xx body that says `"status": "error"` is an error now (v2 reported it as success). The cluster refusals of app and database start/stop arrive as 409 `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_TEMPORARILY_SUSPENDED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` or `ACTION_FAILED`, with no message. The SDK returns an "already" answer as an error: treat it as success yourself if you need to. * A response without a code has `Code` `UNKNOWN_ERROR`. * An expired API key is 401 `ACCESS_DENIED`, like an unknown one. * There is a `Code*` constant for every code the API documents. The API now sends 429 `RATE_LIMITED` (`CodeRateLimited`) where it sent `RATE_LIMIT` and `RATE_LIMIT_EXCEEDED`; `CodeRateLimit` and `CodeRateLimitExceeded` remain, deprecated. * Every `AI.Chat` error is OpenAI-shaped with a lowercase code (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...), which `Code` carries verbatim. * `Error()` renders `squarecloud: : HTTP : ` (v2: `squarecloud: (, HTTP )`). Match on fields, not on the text. See [Errors](/en/sdks/go/errors) for the full reference. ## Behavior changes * **Empty API key:** `New("")` (or a whitespace-only key) still returns a client (it cannot return an error), but every call except `Service.Status` fails locally with `INVALID_API_KEY`. * **Snapshot 202:** v2 returned an `*APIError` with `StatusCode` 202. v3 returns a `SnapshotCreated` with `Pending: true` and a `nil` error. * **Realtime:** `Next` now returns a `RealtimeEvent`. Switch on `ev.Event` (`system`, `status`, `logs`, `error`, `message`). For logs, print `ev.Line` (the `\u0001`/`\u0002` byte is stripped; `ev.Data` stays the raw frame) and use `ev.Stream` for stdout/stderr. For status, use `ev.Status`: never `nil` on a status event, shallow-merged across frames and reconnections. After `REALTIME_DISCONNECTED`, `Next` returns `io.EOF`. The stream no longer dies after 30 s, reconnections wait at least 5.5 s after the previous open, and the open is bounded by the client timeout until the headers arrive. See [Realtime](/en/sdks/go/realtime). * **Timeouts:** v2 used a fixed 30 s `http.Client` timeout for everything. v3 applies a default deadline only when `ctx` has none: the client timeout (`WithTimeout`, 30 s) for most calls; at least 2 minutes for start/stop/restart, database create, snapshot create/restore and `AI.Chat`; none for uploads, file writes over 1 MiB of content and snapshot downloads. `WithTimeout(0)` disables all of them. * **Empty network windows:** `Analytics`, `Errors` and `Performance` return `nil` pointers when the window has no traffic. * **Headers:** every API request sends `Accept: application/json` (`text/event-stream` for realtime). The default `User-Agent` changed from `Square GO` to `squarecloud-sdk-go/3.0.0` (`WithUserAgent` still overrides it). * **Ids:** every id is now percent-encoded as one path segment (v2 pasted it into the path as is), and an empty, `.` or `..` id fails locally with `INVALID_ID`. * **File writes:** v2 always sent the content as a string, which corrupted binary files, and could not write an empty file. v3 always sends the content base64-encoded, so every byte round-trips, empty content writes an empty file, and content over 10 MB fails locally with `FILE_TOO_LARGE`. The API answers 400 `INVALID_CONTENT` for content it cannot decode. * **File reads:** v3 always requests base64 and decodes it, instead of the JSON byte array v2 read (which the API has deprecated). A file over 10 MB is 413 `FILE_TOO_LARGE`. * **File listing:** listing a directory that does not exist is 404 `FILE_NOT_FOUND`; it used to be an empty list. * **Snapshots:** list entries carry `VersionID` and `URL` from the API; nothing is parsed out of `Key`. * **Retries:** new. GET network errors, 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY` and 503 `DATABASE_UNAVAILABLE` on GET are retried twice by default; `WithMaxRetries(0)` restores the v2 behavior. `DATABASE_UNAVAILABLE` can arrive after a mutation has started, so the SDK never retries it on other methods; retry an idempotent mutation yourself if you want to. See [Retries](/en/sdks/go/errors#retries). * **Go version:** the minimum dropped from Go 1.24 to Go 1.22. ## Next steps Install the SDK and create a client. Error class, retries and rate limits. # Go SDK: analytics, DNS and domains Source: https://docs.squarecloud.app/en/sdks/go/network Read edge analytics, errors, request logs and performance of a web application, check DNS, set a custom domain and purge the cache with c.Apps.Network. `c.Apps.Network` works on **web apps only**. Every method takes `ctx` and the app id first. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "time" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" end = time.Now() start = end.Add(-24 * time.Hour) // the last 24 hours ) func main() { // Paste one snippet here, then run goimports. } ``` ## Time windows `Analytics`, `Errors`, `Logs` and `Performance` take a `start` and an `end`, each a `time.Time` (sent as RFC 3339 in UTC). The program above sets them to the last 24 hours. A window is at most **7 days**, and `start` is clamped to the app's creation date. An invalid window is 400 `INVALID_TIME_RANGE`. Results are cached in 5-minute buckets. Cache misses of these four methods share a limit of 20 requests per 60 seconds per account: going over it is 429 `RATE_LIMITED`. ## Analytics `Network.Analytics(ctx, appID, start, end, filters)` returns traffic totals and breakdowns as a `*NetworkAnalytics`. It returns `nil` (and a `nil` error) for a window with no traffic. Pass an empty `squarecloud.AnalyticsFilters{}` for no filters. ```go theme={"system"} analytics, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{}) if err != nil { log.Fatal(err) } if analytics != nil { fmt.Println(analytics.Visits) // []AnalyticsTimeBucket: Date, Visits, Requests, Bytes fmt.Println(analytics.Countries) // []AnalyticsBucket: Type ("BR"), Visits, Requests, Bytes } ``` The breakdowns are `Countries`, `Devices`, `OS`, `Browsers`, `Protocols`, `Methods`, `Paths`, `Referers`, `Providers`, `IPs`, `StatusCodes`, `Bots` and `ContentTypes` (JSON `countries`, ..., `status_codes`, `bots`, `content_types`). Each bucket has `Type`, `Visits`, `Requests` and `Bytes` (`int64`). ### Filters Filters narrow every breakdown. Each takes the exact `Type` value of its breakdown. An empty field is not sent: ```go theme={"system"} brazil, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{ Country: "BR", Path: "/api", Provider: "GOOGLE (15169)", }) if err != nil { log.Fatal(err) } if brazil != nil { fmt.Println(brazil.Paths) } ``` | Filter | Example | | - | - | | `Country` | `"BR"` (2-letter code) | | `IP` | `"203.0.113.7"` | | `Path` | `"/api"` (path prefix) | | `Status` | `"404"` | | `OS`, `Browser`, `Protocol`, `Bot` | The breakdown's `Type` | | `Referer` | `"Direct"` means no referer | | `Provider` | `"NAME (ASN)"`, e.g. `"GOOGLE (15169)"` | | `ContentType` | The breakdown's `Type` | An invalid filter is 400 `INVALID_FILTER`. ## Errors `Network.Errors(ctx, appID, start, end, include4xx)` returns the 5xx responses of the window, plus 4xx when `include4xx` is `true`. It returns `nil` for an empty window. ```go theme={"system"} errs, err := c.Apps.Network.Errors(ctx, appID, start, end, true) if err != nil { log.Fatal(err) } if errs != nil { fmt.Println(errs.Summary.Total, errs.Summary.ByClass) // ByClass: map[string]int64 with "4xx", "5xx" fmt.Println(errs.TopPaths) } ``` ## Request logs `Network.Logs(ctx, appID, start, end)` returns individual requests with client, request and response details. Available on Pro and Enterprise plans (403 `UPGRADE_REQUIRED` otherwise). ```go theme={"system"} logs, err := c.Apps.Network.Logs(ctx, appID, start, end) if err != nil { log.Fatal(err) } for _, l := range logs { fmt.Println(l.Timestamp, l.Request.Method, l.Request.Path, l.Response.Status) } ``` Fields the API may send as `null` are pointers (`Client.IP`, `Client.Country`, `Request.Query`, `Request.Referer`, `Response.Cache`, ...). ## Performance `Network.Performance(ctx, appID, start, end)` returns latency percentiles (`P50`, `P95`, `P99`, in ms) at the edge and at the origin, by country, by location and for the slowest paths. It returns `nil` for an empty window. Available on Pro and Enterprise plans. Each percentile is a `*float64`, `nil` when there were no requests to measure: ```go theme={"system"} performance, err := c.Apps.Network.Performance(ctx, appID, start, end) if err != nil { log.Fatal(err) } if performance != nil { if p95 := performance.Summary.Edge.P95; p95 != nil { fmt.Println("edge p95", *p95) } if p95 := performance.Summary.Origin.P95; p95 != nil { fmt.Println("origin p95", *p95) } } ``` ## DNS `Network.DNS(ctx, appID)` returns the DNS records your custom domain needs, with their status. Without a custom domain it is 400 `NO_CUSTOM_DOMAIN`. ```go theme={"system"} records, err := c.Apps.Network.DNS(ctx, appID) if err != nil { log.Fatal(err) } for _, r := range records { fmt.Println(r.Type, r.Name, r.Value, r.Status) // Type: "txt" | "cname" } ``` ## Custom domain `Network.SetDomain(ctx, appID, domain)` attaches a custom domain (Standard plan and up). Pass `"@"` to remove it. ```go theme={"system"} if err := c.Apps.Network.SetDomain(ctx, appID, "www.example.com"); err != nil { log.Fatal(err) } // Remove it if err := c.Apps.Network.SetDomain(ctx, appID, "@"); err != nil { log.Fatal(err) } ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_DOMAIN` | Not a valid domain name | | 400 | `RESERVED_DOMAIN` | A Square Cloud domain | | 403 | `UPGRADE_REQUIRED` | The plan has no custom domains | | 403 | `LOAD_BALANCER_LIMIT_REACHED` | The plan's limit of apps on this domain was reached | | 409 | `DOMAIN_ALREADY_EXISTS` | The domain belongs to an app of another account | | 502 | `DNS_FAILED` | The edge provider refused the domain | ## Purging the cache `Network.PurgeCache(ctx, appID)` clears the app's edge cache. It is limited to one purge every 60 seconds (429 `KEEP_CALM`). ```go theme={"system"} if err := c.Apps.Network.PurgeCache(ctx, appID); err != nil { log.Fatal(err) } ``` ## Errors of the analytics methods | Status | Code | When | | - | - | - | | 400 | `INVALID_TIME_RANGE` | `start`/`end` missing, malformed or inverted | | 400 | `INVALID_FILTER` | A filter does not match its format (`Analytics`) | | 403 | `UPGRADE_REQUIRED` | `Logs` and `Performance` outside Pro and Enterprise | | 429 | `RATE_LIMITED` | Shared limit of cache misses reached | | 500 | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | The edge provider failed | | 503 | `ANALYTICS_BUSY` | Edge analytics are busy: retried automatically | ## Next steps Stream live logs and status. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: live logs and status Source: https://docs.squarecloud.app/en/sdks/go/realtime Stream an application's live logs, status and system events with c.Apps.Realtime, an iterator that merges status frames and reconnects on its own. `c.Apps.Realtime(ctx, appID)` opens a live stream of an app's logs, status and system events and returns a `*squarecloud.Realtime`. It is an **iterator**: call `Next` in a loop until it returns an error, and always `Close` it. ```go theme={"system"} package main import ( "context" "errors" "fmt" "io" "log" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) func main() { ctx, cancel := context.WithCancel(context.Background()) defer cancel() c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID := "abc123def456abc123def456" r, err := c.Apps.Realtime(ctx, appID) if err != nil { log.Fatal(err) } defer r.Close() for { ev, err := r.Next() if err != nil { if errors.Is(err, io.EOF) || ctx.Err() != nil { break // the stream ended, or ctx was canceled } log.Fatal(err) } switch ev.Event { case "logs": fmt.Println(ev.Stream, ev.Line) // "stdout" | "stderr" case "status": fmt.Println(ev.Status.CPU, ev.Status.RAM) // never nil: always the full, merged state default: fmt.Println(ev.Event, ev.Data) // "system", "error" or "message" } } } ``` The `ctx` passed to `Realtime` governs the whole stream: `Next` takes no arguments. To stop a loop blocked in `Next` from another goroutine, cancel that `ctx`. ## Events Every `RealtimeEvent` has `Event`, `Data` (the raw frame text) and `ID` (the last event id, `""` if none). | `Event` | Extra fields | Description | | - | - | - | | `logs` | `Stream`, `Line` | One log line. The first character of `Data` tells the stream (`\u0001` stdout, `\u0002` stderr); the SDK strips it into `Line` and sets `Stream` to `"stdout"` or `"stderr"` | | `status` | `Status` | Live container metrics. The first frame is complete and the next ones only carry what changed: the SDK merges them, so `Status` (a `*RealtimeStatus`, never `nil` on this event) is always the full state | | `system` | | Connection events such as `REALTIME_CONNECTING \| `, `REALTIME_TIMEOUT` or `REALTIME_DISCONNECTED` | | `error` | | An error code such as `CONTAINER_NOT_FOUND` | | `message` | | A frame without an `event` name | ### The `Status` struct | Field | Description | | - | - | | `CPU` (`cpu`) | CPU usage (%) | | `CPULimit` (`cpuLimit`) | Number of CPU cores allocated (e.g. `1` or `0.5`) | | `RAM` (`ram`) | `[usedMB, limitMB]` as a `[2]float64` | | `Status` (`status`) | Container state, e.g. `running` | | `NetIO` (`netIO`) | Network `In`/`Out` totals (`i`, `o`), with `New` for the latest interval, in bytes per second | | `BlockIO` (`bIO`) | Disk `In`/`Out` totals (`i`, `o`) | | `Uptime` (`uptime`) | Unix ms of the container start | ## Ending the stream `Next` returns `io.EOF` when: * the server closes the connection cleanly (each connection lasts up to **10 minutes**); * the server sent `REALTIME_DISCONNECTED` (the event is delivered first, then `io.EOF`); * you called `Close`. When the `ctx` passed to `Realtime` is canceled or its deadline passes, `Next` returns the bare `ctx.Err()` (`context.Canceled` or `context.DeadlineExceeded`), not an `*APIError`. To leave the loop yourself, just `break`: the deferred `Close` releases the connection. To keep watching past 10 minutes, call `Realtime` again when the loop ends. ## Reconnection A dropped connection, or the server handing reconnection to the client (`REALTIME_RECONNECT`), reopens the stream on its own: * up to **3 times in a row**; any `logs` or `status` event resets the count; * each reopen at least **5.5 s** after the previous open, to stay under the API's pace of one open per 5 seconds per app. The merged `Status` survives reconnections. Past 3 failed reconnections, `Next` returns an `*APIError` with `NETWORK_ERROR` (status `0`). ## Limits and errors * **5** concurrent connections per account and **30** per app, across all users. Going over is 429 `REALTIME_MAX_CONNECTIONS` or `REALTIME_MAX_CONNECTIONS_APP`. * The HTTP status is checked before streaming, so these errors (and 404 for an unknown app) are returned by `Realtime` itself, before the first `Next`. * When `ctx` has no deadline, the `WithTimeout` deadline only covers the open, until the response headers arrive (`TIMEOUT` if they don't). The stream itself has no deadline besides `ctx`. ## Next steps Back up and restore apps and databases. The REST endpoint behind this stream. The same stream from the terminal. # Go SDK: snapshots and backups Source: https://docs.squarecloud.app/en/sdks/go/snapshots List, create and restore snapshots of applications and databases, list every snapshot of the account, and download a snapshot file with c.DownloadSnapshot. Snapshots are backups of an app's or database's storage. Apps and databases share the same three methods: * `c.Apps.Snapshots`: `List(ctx, appID)`, `Create(ctx, appID)`, `Restore(ctx, appID, name, versionID)` * `c.Databases.Snapshots`: `List(ctx, databaseID)`, `Create(ctx, databaseID)`, `Restore(ctx, databaseID, name, versionID)` How many snapshots you can create per day depends on your plan (see [Limits](#limits)). Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) appID = "abc123def456abc123def456" ) func main() { // Paste one snippet here, then run goimports. } ``` ## Listing snapshots ```go theme={"system"} snapshots, err := c.Apps.Snapshots.List(ctx, appID) if err != nil { log.Fatal(err) } for _, s := range snapshots { fmt.Println(s.Name, s.VersionID, s.Size, s.Modified) } ``` | Field | Description | | - | - | | `Name` (`name`) | The snapshot id that `Restore` takes | | `VersionID` (`version_id`) | The version that `Restore` takes | | `Size` (`size`) | Size in bytes (`int64`) | | `Modified` (`modified`) | When it was taken (`time.Time`) | | `URL` (`url`) | Signed download URL, **valid for 30 days** | | `Key` (`key`) | Signed query string of the URL | | `Runtime` (`runtime`) | Database engine or app language (`*string`, `nil` on old snapshots) | | `Origin` (`origin`) | `"automatic"`, `"manual"` or `nil` (`*string`) | ## Creating a snapshot `Create` waits for the snapshot (without a `ctx` deadline, at least 2 minutes before timing out). A large snapshot may not finish in time: the API then answers 202 and the SDK returns a `SnapshotCreated` with `Pending` set to `true` and a `nil` error. The snapshot keeps generating and shows up in `List` on its own, usually within 2 minutes. ```go theme={"system"} result, err := c.Apps.Snapshots.Create(ctx, appID) if err != nil { log.Fatal(err) } if result.Pending { // Poll List later. Do not call Create again: that starts a new snapshot. } else { fmt.Println(result.URL) // signed download URL, valid 30 days } ``` Never call `Create` again to check on a pending snapshot: it starts a new one and counts against the plan's daily snapshot quota. Poll `List` instead. ## Restoring a snapshot `Restore(ctx, id, name, versionID)` takes the `Name` and `VersionID` of a listed snapshot. ```go theme={"system"} snapshots, err := c.Apps.Snapshots.List(ctx, appID) if err != nil { log.Fatal(err) } if len(snapshots) == 0 { log.Fatal("no snapshots") } latest := snapshots[0] if err := c.Apps.Snapshots.Restore(ctx, appID, latest.Name, latest.VersionID); err != nil { log.Fatal(err) } ``` | Status | Code | When | | - | - | - | | 400 | `MISSING_PARAMETERS` | `name` or `versionID` is missing | | 400 | `INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID` | Not a `Name`/`VersionID` from the listing | | 400 | `SNAPSHOT_DATABASE_MISMATCH` | The snapshot's engine does not match the database's type (databases only) | | 404 | `SNAPSHOT_NOT_FOUND` | No snapshot with that name and version | | 404 | `SNAPSHOT_RESTORE_FAILED` | The restore could not be dispatched (the usual failure) | | 413 | `PAYLOAD_TOO_LARGE` | The snapshot is too large to restore | ## Downloading a snapshot `c.DownloadSnapshot(ctx, url, w)` streams a snapshot file from its signed `url` (from `List` or `Create`) into any `io.Writer`. It does **not** call the API: the API key is never sent to the storage host, and the URL never appears in the returned error. Nothing is buffered in memory, and there is no default deadline (bound or cancel it with `ctx`). A network error before the response is retried like any `GET`. ```go theme={"system"} snapshots, err := c.Apps.Snapshots.List(ctx, appID) if err != nil { log.Fatal(err) } if len(snapshots) == 0 { log.Fatal("no snapshots") } out, err := os.Create("backup.zip") if err != nil { log.Fatal(err) } defer out.Close() if err := c.DownloadSnapshot(ctx, snapshots[0].URL, out); err != nil { log.Fatal(err) } ``` An expired or invalid URL returns an `*APIError` with the storage host's HTTP status and `UNKNOWN_ERROR`. A URL that cannot be parsed, and an error of your `io.Writer`, are returned as plain errors. ## Account snapshots `c.Account.Snapshots(ctx, scope)` lists every snapshot of the account. Pass `""` for all of them, or `squarecloud.SnapshotScopeApplications` or `squarecloud.SnapshotScopeDatabases`. It needs an active plan and shares the network endpoints' rate limit (429 `RATE_LIMITED`). ```go theme={"system"} all, err := c.Account.Snapshots(ctx, "") if err != nil { log.Fatal(err) } databases, err := c.Account.Snapshots(ctx, squarecloud.SnapshotScopeDatabases) if err != nil { log.Fatal(err) } fmt.Println(len(all), "snapshots,", len(databases), "of databases") ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_SCOPE` | `scope` is not `applications` or `databases` | | 402 | `UPGRADE_REQUIRED` | The account has no active plan | | 429 | `RATE_LIMITED` | Rate limit reached | ## Limits * `Create` is limited to one call per 180 seconds and to a daily quota that depends on the plan: going over the quota is 429 `DAILY_SNAPSHOTS_LIMIT_REACHED`. * While a restore runs, deleting the app or starting the database is 403 `RESTORE_IN_PROGRESS`. ## Next steps Create and manage databases. The REST endpoints behind these methods. The same actions from the terminal. # Go SDK: workspaces and members Source: https://docs.squarecloud.app/en/sdks/go/workspaces Create and manage workspaces, invite members, set their roles and share applications with c.Workspaces. Act on a shared app with its composite id. A workspace shares apps with other Square Cloud users, each with a role. `c.Workspaces` manages workspaces, `c.Workspaces.Members` their members and `c.Workspaces.Apps` the shared apps. Creating workspaces needs a Standard, Pro or Enterprise plan. Each snippet below runs on its own inside this program: paste one at a time into `main` and run `goimports` (see [Running the examples](/en/sdks/go/client#running-the-examples)). ```go theme={"system"} package main import ( "context" "os" "github.com/squarecloudofc/sdk-api-go/v3" ) var ( ctx = context.Background() c = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) workspaceID = "0123456789abcdef0123456789abcdef" appID = "abc123def456abc123def456" memberID = "1234567890" // a member's ID, from c.Workspaces.Get ) func main() { // Paste one snippet here, then run goimports. } ``` ## Workspaces ```go theme={"system"} created, err := c.Workspaces.Create(ctx, "My team") if err != nil { log.Fatal(err) } workspace, err := c.Workspaces.Get(ctx, created.ID) if err != nil { log.Fatal(err) } fmt.Println(workspace.Name, workspace.Owner, workspace.CreatedAt) for _, member := range workspace.Members { name := "(unknown)" if member.Name != nil { name = *member.Name } fmt.Println(member.ID, name, member.Group, member.JoinedAt) } for _, app := range workspace.Applications { fmt.Println(app.ID, app.Name, app.Lang, app.RAM) } ``` `Workspaces.List(ctx)` returns every workspace you own or belong to, with the same fields: ```go theme={"system"} workspaces, err := c.Workspaces.List(ctx) if err != nil { log.Fatal(err) } for _, w := range workspaces { fmt.Println(w.ID, w.Name, len(w.Members)) } ``` To leave a workspace as a member, or delete it as the owner: ```go theme={"system"} if err := c.Workspaces.Leave(ctx, workspaceID); err != nil { // as a member log.Fatal(err) } if err := c.Workspaces.Delete(ctx, workspaceID); err != nil { // as the owner log.Fatal(err) } ``` | Field | Description | | - | - | | `ID` (`id`) | 32 hex characters (older workspaces keep a 40-character id) | | `Name` (`name`) | Workspace name (1 to 32 characters) | | `Owner` (`owner`) | Owner's user id | | `Members` (`members`) | `ID`, `Name`, `Group`, `JoinedAt` (`joinedAt`). `Name` is a `*string`, `nil` when it cannot be resolved (a deleted account) | | `Applications` (`applications`) | `ID`, `Name`, `Description` (`desc`), `RAM`, `Lang`, `Domain`, `Custom`. `Description`, `Domain` and `Custom` are `*string` | | `CreatedAt` (`createdAt`) | Creation date (`time.Time`) | The owner cannot leave (400 `CANNOT_LEAVE_OWNER`): delete the workspace instead. ## Members Adding a member takes an **invite code** that the member generates with `Members.InviteCode(ctx)`. The code is valid for **5 minutes**. ```go theme={"system"} // The member runs this and sends you the code code, err := c.Workspaces.Members.InviteCode(ctx) if err != nil { log.Fatal(err) } fmt.Println(code) ``` ```go theme={"system"} // The owner adds them with a role code := "5d8e1f2a3b4c4d6e9f0a1b2c3d4e5f6a" // the code the member sent you if err := c.Workspaces.Members.Add(ctx, workspaceID, code, squarecloud.GroupMaintain); err != nil { log.Fatal(err) } ``` To change a member's role or remove them, pass their `ID` from `Workspaces.Get`: ```go theme={"system"} if err := c.Workspaces.Members.Update(ctx, workspaceID, memberID, squarecloud.GroupView); err != nil { log.Fatal(err) } if err := c.Workspaces.Members.Remove(ctx, workspaceID, memberID); err != nil { log.Fatal(err) } ``` Roles (`WorkspaceGroup`): `GroupView` (`view`), `GroupManager` (`manager`), `GroupMaintain` (`maintain`) and `GroupAdmin` (`admin`). A member's `Group` is a plain `string`, since it can also be `"owner"`. Calling a method that your role does not allow is 403 `PERMISSION_DENIED`. ## Shared applications ```go theme={"system"} if err := c.Workspaces.Apps.Add(ctx, workspaceID, appID); err != nil { log.Fatal(err) } if err := c.Workspaces.Apps.Remove(ctx, workspaceID, appID); err != nil { log.Fatal(err) } ``` A workspace can hold up to 100 apps (400 `APPLICATIONS_LIMIT_REACHED`). ### Acting on a shared app To act on an app shared with you, pass the composite id `-` to any `c.Apps` method. `Workspaces.Get` and `Workspaces.List` return raw ids, so build it yourself: ```go theme={"system"} workspace, err := c.Workspaces.Get(ctx, workspaceID) if err != nil { log.Fatal(err) } for _, app := range workspace.Applications { status, err := c.Apps.Status(ctx, app.ID+"-"+workspace.ID) if err != nil { log.Fatal(err) } fmt.Println(app.Name, status.Running) } // Status of every app of the workspace in one request statuses, err := c.Apps.StatusAll(ctx, workspaceID) if err != nil { log.Fatal(err) } for _, s := range statuses { fmt.Println(s.ID, s.Running) } ``` ## Errors Workspace routes other than `Get` send the ids in the request body, so an empty id there is 400 `INVALID_ID` from the server (not a local error). `Get` sends the id in the path, so an empty id fails locally with `INVALID_ID` (status `0`). | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `WORKSPACE_LIMIT_REACHED`, `MEMBERS_LIMIT_REACHED`, `APPLICATIONS_LIMIT_REACHED` | A plan or workspace limit was reached | | 400 | `INVALID_CODE` | The invite code is missing, malformed or expired | | 400 | `INVALID_GROUP` | The role is not `view`, `manager`, `maintain` or `admin` | | 400 | `CANNOT_INVITE_OWNER`, `CANNOT_EDIT_OWNER`, `CANNOT_LEAVE_OWNER` | The action does not apply to the owner | | 400 | `MEMBER_ALREADY_ADDED`, `APP_ALREADY_IN_WORKSPACE` | Already in the workspace | | 403 | `UPGRADE_REQUIRED` | The plan cannot create workspaces | | 403 | `PERMISSION_DENIED` | Your role does not allow the action | | 404 | `WORKSPACE_NOT_FOUND`, `MEMBER_NOT_FOUND`, `APP_NOT_FOUND` | Not found | ## Next steps Chat completions through the AI Gateway. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: AI Gateway chat Source: https://docs.squarecloud.app/en/sdks/js/ai Call the Square Cloud AI Gateway from @squarecloud/api with api.ai.chat(): OpenAI-compatible chat completions, without streaming. `api.ai.chat(request)` calls the [AI Gateway](/en/api-reference/ai-gateway), an **OpenAI-compatible** chat completions endpoint. It needs the `ai:chat` scope and a Standard plan or above. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). ```typescript theme={"system"} const completion = await api.ai.chat({ model: "cubic", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "What is Square Cloud?" }, ], max_tokens: 512, }); console.log(completion.choices[0].message.content); console.log(completion.usage.total_tokens); ``` ## Request | Field | Description | | - | - | | `model` | `cubic`. Accepted for compatibility: there is no other model | | `messages` | `{ role, content?, tool_call_id?, tool_calls? }`, with `role` `system`, `user`, `assistant` or `tool` | | `tools` / `tool_choice` | OpenAI function calling | | `max_tokens` | Maximum tokens of the answer | | `temperature` | Sampling temperature | The response has the OpenAI shape: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) and `usage`. ## No streaming `ai.chat()` does not stream: it returns the whole completion. `stream: true` is 400 `stream_not_supported`. ## Timeout The gateway gives each request **90 seconds** in total, then answers 503 `server_overloaded`. The SDK waits at least 120 s before timing out, so you get the gateway's answer. ## Errors AI errors use the OpenAI format, so their codes are **lowercase**. They still throw a [`SquareCloudAPIError`](/en/sdks/js/errors), with `code` set to the OpenAI code (or its `type` when there is no code): ```typescript theme={"system"} import { SquareCloudAPIError } from "@squarecloud/api"; try { await api.ai.chat({ messages: [{ role: "user", content: "Hi" }] }); } catch (error) { if (error instanceof SquareCloudAPIError && error.code === "server_overloaded") { // safe to retry yourself } } ``` | Status | Code | When | | - | - | - | | 400 | `stream_not_supported` | `stream: true` was sent | | 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | A malformed field | | 400 | `context_length_exceeded` | The conversation exceeds the plan's context window | | 401 | `access_denied` | Invalid API key | | 403 | `upgrade_required` | The plan has no AI Gateway access | | 429 | `rate_limit_exceeded`, `concurrent_limit_reached` | Too fast, or a request already in flight | | 429 | `daily_limit_reached`, `weekly_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached` | A daily or weekly limit is used up (daily limits reset at 00:00 UTC, weekly ones on Monday at 00:00 UTC) | | 503 | `server_overloaded` | Capacity is full or the 90 s deadline passed: safe to retry | | 503 | `daily_capacity_reached` | The platform's daily capacity is used up | The SDK **never retries** AI errors: the request is a non-idempotent `POST`. See the [AI Gateway reference](/en/api-reference/ai-gateway) for plan limits. ## Next steps Error class, retries and rate limits. Models, plan limits and the OpenAI-compatible endpoint. # JavaScript SDK: managed databases Source: https://docs.squarecloud.app/en/sdks/js/databases Create, inspect, update, start, stop and delete managed databases, read their status and metrics, and manage their credentials with api.databases. `api.databases` manages Square Cloud's managed databases (MongoDB, MySQL, PostgreSQL and Redis). Every method except `create` and `statusAll` takes the database id first. To list your databases, use [`api.account.me()`](/en/sdks/js/client#account): its `databases` array has every database the key can see. Database hosting needs a Standard, Pro or Enterprise plan. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `databaseId` is the id of one of your databases: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Creating a database ```typescript theme={"system"} const db = await api.databases.create({ name: "my-db", type: "postgres", // "mongo" | "mysql" | "redis" | "postgres" version: "17", // a full version or a prefix memory: 1024, // MB, a whole number }); console.log(db.id, db.connection_url, db.cluster); console.log(db.password); // shown only here: save it console.log(db.certificate); // base64 PEM (private key, then certificate), or null ``` | Field | Description | | - | - | | `name` | 1 to 32 characters | | `type` | `mongo`, `mysql`, `redis` or `postgres` | | `version` | A full version or a prefix such as `"8"` | | `memory` | MB, a whole number. At least 512 for Redis and 1024 for the others | The `password` and `certificate` are only returned by `create()` (and by [`resetCredentials()`](#credentials)). The call waits at least 120 s before timing out. | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `INVALID_DATABASE_TYPE`, `INVALID_DATABASE_VERSION` | Unknown type or unsupported version | | 400 | `INVALID_MEMORY` | `memory` is not a whole number (a fraction or a string) | | 400 | `INSUFFICIENT_MEMORY` | `memory` is below the engine's minimum or exceeds the available memory | | 400 | `CLUSTER_SELECTION_FAILED` | No cluster had enough capacity | | 400 / 500 | `DATABASE_CREATION_FAILED` | Provisioning failed | | 403 | `UPGRADE_REQUIRED` | The plan has no database hosting | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance | ## Getting a database ```typescript theme={"system"} const db = await api.databases.get(databaseId); console.log(db.id, db.name, db.type, db.ram, db.port, db.cluster, db.created_at); ``` ## Updating a database `update(databaseId, { name, ram })` renames or resizes a database. Pass at least one field (400 `NO_UPDATE_DATA` otherwise). ```typescript theme={"system"} await api.databases.update(databaseId, { name: "orders", ram: 2048 }); ``` ## Start and stop ```typescript theme={"system"} await api.databases.start(databaseId); await api.databases.stop(databaseId); ``` Like app lifecycle calls, they wait at least 120 s, and a refusal is **409** with a code and an empty message: `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` or `ACTION_FAILED`. While a snapshot restore runs, they are 403 `RESTORE_IN_PROGRESS`. ## Status and metrics `status(databaseId)` returns formatted values; `{ raw: true }` returns numbers. `statusAll()` returns one summary per database. `metrics(databaseId)` returns the last 24 hours, one point every 5 minutes, newest first. ```typescript theme={"system"} const status = await api.databases.status(databaseId); console.log(status.running, status.cpu, status.ram); // true "0.5%" "120.4MB" const raw = await api.databases.status(databaseId, { raw: true }); console.log(raw.cpu, raw.ram); // 0.5 120.4 for (const { id, running, cpu, ram } of await api.databases.statusAll()) { console.log(id, running, cpu, ram); // cpu and ram only while running } const [latest] = await api.databases.metrics(databaseId); console.log(latest.date, latest.cpu, latest.ram); ``` The status fields are the same as [app status](/en/sdks/js/managing_application#status). ## Credentials `certificate(databaseId)` returns the TLS certificate as base64-encoded PEM. `resetCredentials(databaseId, type)` rotates the password (and returns the new one) or the certificate (and returns `""`). The database must be running (400 `DATABASE_NOT_RUNNING`). ```typescript theme={"system"} const certificate = await api.databases.certificate(databaseId); const pem = atob(certificate); const password = await api.databases.resetCredentials(databaseId, "password"); await api.databases.resetCredentials(databaseId, "certificate"); // "" ``` ## Deleting a database ```typescript theme={"system"} await api.databases.delete(databaseId); ``` Deletion is permanent. Take a [snapshot](/en/sdks/js/snapshots) first if you may need the data again. ## Snapshots `api.databases.snapshots` has the same `list`, `create` and `restore` as apps. See [Snapshots](/en/sdks/js/snapshots). ## Next steps Share apps with your team. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: GitHub deploys Source: https://docs.squarecloud.app/en/sdks/js/deploys Deploy from GitHub with api.apps.deploys: set a webhook, link a repository through the Square Cloud GitHub App, and read the deploy history. `api.apps.deploys` connects an app to GitHub so a push deploys it. There are two ways to do it: a **webhook** that you add to the repository, or the **Square Cloud GitHub App**. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Webhook `deploys.setWebhook(appId, accessToken)` configures GitHub webhook deploys with a GitHub access token (`ghp_...` or `github_pat_...`) and returns the webhook URL to add to your repository. ```typescript theme={"system"} const url = await api.apps.deploys.setWebhook(appId, process.env.GITHUB_TOKEN!); console.log(url); // add it as a webhook in the repository settings ``` Pass `"@"` as the token to remove the webhook. The method then returns `""`. ```typescript theme={"system"} await api.apps.deploys.setWebhook(appId, "@"); ``` An invalid token is 400 `INVALID_ACCESS_TOKEN`. ## GitHub App `deploys.linkGithubApp(appId, repository, branch)` links a repository installed through the Square Cloud GitHub App. It needs the `apps:deploy` scope. ```typescript theme={"system"} const repo = await api.apps.deploys.linkGithubApp(appId, "octocat/hello-world", "main"); console.log(repo.id, repo.full_name, repo.branch); ``` `deploys.unlinkGithubApp(appId)` removes the link. To link another repository or branch, unlink first. ```typescript theme={"system"} await api.apps.deploys.unlinkGithubApp(appId); ``` Link and unlink share a limit of **3 calls per 60 seconds**. | Status | Code | When | | - | - | - | | 400 | `GIT_ALREADY_CONFIGURED` | The app already has a linked repository: unlink it first | | 400 | `GIT_NOT_CONFIGURED` | `unlinkGithubApp` with nothing linked | | 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | The branch does not exist, or its name is over 256 characters | | 403 | `GITHUB_NOT_CONNECTED` | Your account has no GitHub App installation | | 403 | `REPOSITORY_NOT_AVAILABLE` | The GitHub App is not installed on the repository through your GitHub account | | 403 | `REPOSITORY_PERMISSION_REQUIRED` | Your GitHub account has no write access to the repository | | 404 | `REPOSITORY_NOT_FOUND` | The repository does not exist or is not visible | | 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | Another app, of any account, already links this repository and branch. Its id is in `message` only when that app is yours | | 502 | `FAILED_TO_FETCH` | GitHub did not confirm the branch: safe to retry | ## Current configuration `deploys.current(appId)` returns what is configured: `app` for the GitHub App link, `webhook` for the webhook URL. It returns `{}` when nothing is set. ```typescript theme={"system"} const { app, webhook } = await api.apps.deploys.current(appId); if (app) console.log(app.name, app.branch); // e.g. "octocat/hello-world" "main" if (webhook) console.log(webhook); ``` ## Deploy history `deploys.list(appId)` returns one **timeline per deploy**, each an array of events, oldest event first. Only Git deploys (webhook and GitHub App pushes) are recorded. ```typescript theme={"system"} for (const timeline of await api.apps.deploys.list(appId)) { const last = timeline.at(-1); console.log(last?.id, last?.state, last?.date); if (last?.state === "error") console.log(last.code, last.message); } ``` | Field | Description | | - | - | | `id` | The commit SHA | | `state` | `pending`, `clone`, `commit`, `restarting`, `success` or `error` | | `date` | When the event happened | | `source` | Always `"git"` | | `branch` | On `clone` events | | `files` | On `commit` events: `{ added, removed, modified }` | | `code` / `message` | On `error` events: why the deploy failed (for example `CLONE_FAILED`) | ## Next steps Analytics, DNS, custom domains and cache. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: errors and retries Source: https://docs.squarecloud.app/en/sdks/js/errors Handle SquareCloudAPIError in @squarecloud/api: status, code and message, the SDK's own error codes, retries, timeouts and rate limits. Every API, network and local failure throws one class: `SquareCloudAPIError`. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ```typescript theme={"system"} import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api"; try { await api.apps.start(appId); } catch (error) { if (error instanceof SquareCloudAPIError) { console.error(error.status, error.code, error.message); console.error(error.method, error.path); // "POST" "/v2/apps//start" } } ``` ## `SquareCloudAPIError` `SquareCloudAPIError` extends `Error` (it is **not** a `TypeError`). | Property | Type | Description | | - | - | - | | `status` | `number` | HTTP status. `0` when no response arrived (network error, timeout, local check) | | `code` | `ErrorCode` | The API's error code, e.g. `APP_NOT_FOUND`, or one of the SDK's codes | | `message` | `string` | The server's explanation. When the server sent only a code, the code itself | | `method` | `string` | HTTP method of the failed call | | `path` | `string` | URL path of the failed call, without the query string | | `cause` | `unknown` | The original error, for `NETWORK_ERROR` and invalid JSON | Two failures are not wrapped: * An aborted call rejects with the signal's `reason`. An aborted `realtime()` loop just ends. * An upload path that cannot be opened throws the file system error. ## SDK codes | Status | Code | When | | - | - | - | | 0 | `NETWORK_ERROR` | No response (DNS, connection reset, body cut off). The original error is in `cause` | | 0 | `TIMEOUT` | No response within the [timeout](/en/sdks/js/client#timeouts) | | 0 | `FILE_TOO_LARGE` | Local check: an upload over 100 MB or a `files.write` over 10 MB. Nothing was sent | | 0 | `INVALID_ID` | Local check: an id that is empty, `.` or `..`. Nothing was sent | | any | `UNKNOWN_ERROR` | A response without a code (such as a proxy error page), with the real `status` and the message `HTTP `. A 2xx body that is not JSON has the message `Invalid JSON in HTTP response` | ## The `ErrorCode` type `ErrorCode` is a **type only** (no runtime object). It lists every public API code, the deprecated ones and the SDK's, plus `string & {}`, so your editor autocompletes known codes and new codes still type-check. `RATE_LIMIT` and `RATE_LIMIT_EXCEEDED` are still in the type, marked deprecated: the API now answers `RATE_LIMITED` for both. The list of API codes grows. **Handle an unknown code by its HTTP status**: ```typescript theme={"system"} async function start(appId: string) { try { await api.apps.start(appId); } catch (error) { if (!(error instanceof SquareCloudAPIError)) throw error; switch (error.code) { case "APP_NOT_FOUND": return null; case "CONTAINER_ALREADY_STARTED": return; // fine default: if (error.status === 429) return retryLater(); if (error.status >= 500) return reportOutage(error); throw error; } } } ``` ## API error codes Every other code comes from the API. The [API error reference](/en/api-reference/errors) lists each one with its HTTP status, meaning and fix, and each SDK page lists the codes its methods return most often. Any call can also answer 401 `ACCESS_DENIED` (a bad key), 403 `MISSING_SCOPE` or `RESOURCE_NOT_ALLOWED` (the [limits of the key](/en/sdks/js/client#api-key-and-scopes)), 429 (see [Rate limits](#rate-limits)) or 503 `DATABASE_UNAVAILABLE`. `ai.chat()` errors use lowercase OpenAI codes instead (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...). See [AI](/en/sdks/js/ai#errors). ## Retries The SDK only retries what is safe to repeat, up to `maxRetries` times (default `2`, so up to 3 attempts): | Retried | Methods | | - | - | | `NETWORK_ERROR` | `GET` only | | 503 `UPLOAD_BUSY` | Any method | | 503 `ANALYTICS_BUSY` | Any method | | 503 `DATABASE_UNAVAILABLE` | `GET` only | It **never** retries: * `TIMEOUT`; * any **429**: `RATE_LIMITED` can be a block of about 30 minutes, and `KEEP_CALM` is not retried either; * other 5xx; * AI errors. 503 `DATABASE_UNAVAILABLE` can arrive after a mutation was already applied, so the SDK does not retry it outside `GET`. Retry your own idempotent mutations if you need to. The wait before retry `n` (starting at 0) is `min(8 s, 500 ms · 2^n) · U(0.5, 1)`: exponential backoff with 50% to 100% jitter. Set `maxRetries: 0` to turn retries off. ## Timeouts `timeoutMs` (30 s) applies per attempt and covers the whole response. See [Timeouts](/en/sdks/js/client#timeouts) for the calls with a 120 s floor and the calls with no timeout. A timeout throws `TIMEOUT` with status `0` and is never retried. ## Rate limits Every account has a limit of requests per 60 seconds, set by its plan ([values](/en/api-reference/limitations-and-restrictions)), and some routes have their own: * **429 `RATE_LIMITED`**: the account or API key went over its request budget and is blocked for about 30 minutes, or an IP that keeps sending invalid keys is blocked for a short period. Also the limit of the network endpoints and `account.snapshots`. * **429 `KEEP_CALM`**: too many calls to one route in a short time. The SDK never retries a 429. Slow down, and wait before trying again. ## Next steps Every error code, with its meaning and fix. The request limits of each plan. # JavaScript SDK: migrating from v4 to v5 Source: https://docs.squarecloud.app/en/sdks/js/migrating_to_v5 Upgrade @squarecloud/api from v4 to v5: client.users and backups removed, a new apps.create() result and dns() shape, with the smallest patches needed. ## Requirements Unchanged from v4: **Node.js 20.0.0** or newer, both ESM and CJS. ## Breaking changes summary | v4.x | v5.x | | - | - | | `client.users.*` (deprecated proxy) | Removed. Use `client.user.*` | | `app.backup` / `app.backups` | Removed. Use `app.snapshots` | | `Backup` export | Removed. Use `Snapshot` / `DatabaseSnapshot` | | `api.applications.create(file)` returns `{ id, name, lang, ram }` | Returns `{ id, name, ram, cpu, language, description?, subdomain? }` | | `app.network.dns()` returns `{ ownership, ssl }` | Returns an array of DNS records | ## `client.users` removed Unlike the v3 to v4 migration, there is no deprecated proxy this time. `client.users` no longer exists, calling it throws. ```typescript theme={"system"} // v4 await api.users.get(); // v5 await api.user.get(); ``` ## Backups removed `app.backup` and `app.backups` are gone, along with the `Backup` export. Snapshots are the only supported path for both applications and databases. ```typescript theme={"system"} // v4 await app.backups.create(); await app.backup.list(); // v5 await app.snapshots.create(); await app.snapshots.list(); ``` Use the `Snapshot` class for application snapshots and `DatabaseSnapshot` for database snapshots. ## `api.applications.create(file)` return shape The created application now returns richer language and resource data instead of the flat `lang`/`ram` pair. ```typescript theme={"system"} // v4 const { id, name, lang, ram } = await api.applications.create(file); // v5 const { id, name, ram, cpu, language, description, subdomain } = await api.applications.create(file); // language is now an object, e.g. { name: "javascript", version: "22" } // cpu is the allocated CPU shares (number) // description and subdomain are only present when set in squarecloud.config ``` ## `app.network.dns()` shape `dns()` now returns an array of DNS records instead of a single `{ ownership, ssl }` object. ```typescript theme={"system"} // v4 const { ownership, ssl } = await app.network.dns(); // v5 const records = await app.network.dns(); // [{ type: "txt", name, value, status }, { type: "cname", name, value: "cname.squareweb.app", status }] ``` `txt` records cover both ownership and SSL validation; the `cname` record is the traffic record. `status` reflects the validation state (`pending`, `pending_validation`, `active`, and so on). ## Other changes * `ApplicationLanguage` now includes `ruby`, alongside javascript, typescript, python, java, elixir, go, rust, php, dotnet and static. * Error codes were standardized. New names are exported through `APIErrorCode`; the old names remain available as deprecated type aliases. See [Errors](/en/sdks/js/errors) for the current codes. ## Next steps Install the SDK and create a client. Error class, retries and rate limits. # JavaScript SDK: migrating from v5 to v6 Source: https://docs.squarecloud.app/en/sdks/js/migrating_to_v6 Upgrade @squarecloud/api from v5 to v6: plain data instead of classes, ids as the first argument, one error class, timeouts, retries and a method table. v6 is a rewrite: one flat client, plain data instead of classes, ids as the first argument, and one error class. Most changes are mechanical. ## At a glance | v5 | v6 | | - | - | | Classes with methods (`app.start()`) | Plain data; methods on the client (`api.apps.start(appId)`) | | `Collection` | `Array` | | Class fields in camelCase with `Date`s (`createdAt`, `modifiedAt`, `uptime`) | The API's own fields and values (`created_at` and `modified` as ISO strings, `uptime` in ms) | | `Buffer` | `Uint8Array` (a `Buffer` is still accepted as input) | | Mutations return `Promise` (always `true`) | `Promise`, or the data the API returns (`envs.*` → `EnvVars`, `deploys.setWebhook` → URL, `deploys.linkGithubApp` → `LinkedRepository`, `resetCredentials` → the password) | | `SquareCloudAPIError extends TypeError` with `code` only | `extends Error` with `status`, `code`, `message` (the server's), `method`, `path`, `cause` | | Events (`userUpdate`, `statusUpdate`, `logsUpdate`, `snapshotsUpdate`) and `api.cache`/`app.cache` | Removed: keep your own state | | `api.api.request()` (the raw `APIService`) | Removed: every operation has a method | | No timeout, no retries | 30 s timeout per attempt, retries for safe failures only (see [Behavior changes](#behavior-changes)) | | Node.js >= 20 | Node.js >= 22, Deno, Bun, edge | | `@squarecloud/api-types` | Types ship with the SDK (`import type { App } from "@squarecloud/api"`) | ## Construction and options | v5 | v6 | Notes | | - | - | - | | `new SquareCloudAPI(key)` | `new SquareCloudAPI(key, { baseUrl?, timeoutMs?, maxRetries?, userAgent?, fetch? })` | An empty or whitespace-only key throws a `TypeError`. | | `SquareCloudAPI.apiInfo` | `BASE_URL` and `{ baseUrl }` | `BASE_URL` = `https://api.squarecloud.app/v2`. | | (none) | `timeoutMs` (30000) | Per attempt; held calls and `ai.chat` wait at least 120 s. `<= 0`, `Infinity` or `>= 2^31` disables every timeout, floors included. | | (none) | `maxRetries` (2) | Network errors on GET and the listed 503 codes only; never 429. | | (none) | `userAgent` | Replaces the whole header (default `squarecloud-sdk-js/`). | | (none) | `fetch` | Custom `fetch` (proxies, tracing, tests). | ## Method by method | v5 | v6 | Notes | | - | - | - | | `api.user.get()` → `User` | `api.account.me()` | Returns `{ user, applications, databases }`. | | `user.plan.expiresIn` | `new Date(user.plan.duration)` | A timestamp; `null` never expires. | | `api.user.snapshots(scope)` | `api.account.snapshots({ scope })` | | | `api.service.status()` | `api.service.status()` | New shape: `status`, `message`, `services`, `dependencies`... | | `api.applications.get()` | `(await api.account.me()).applications` | | | `api.applications.get(id)` / `fetch(id)` / `app.fetch()` | `api.apps.get(id)` | Also finds workspace-shared apps. | | `app.isWebsite()` | `Boolean((await api.apps.get(id)).domain)` | | | `api.applications.create(file)` | `api.apps.create(file, { signal })` | A path, `Blob`/`File` or `Uint8Array`; no timeout. | | `api.applications.statusAll()` | `api.apps.statusAll({ workspaceId? })` | Plain `{ id, running, cpu?, ram? }` objects (v5 nested `cpu`/`ram` under `usage`). | | `statusAll()[i].fetch()` (`SimpleApplicationStatus`, `SimpleDatabaseStatus`) | `api.apps.status(id)` / `api.databases.status(id)` | | | `api.applications.domains()` / `loadBalancers()` | `api.apps.domains()` / `api.apps.loadBalancers()` | | | `app.getStatus()` | `api.apps.status(id, { raw? })` | `cpu`, `ram`, `storage` and `network` are top-level (v5 nested them under `usage`); `uptime` is the start timestamp in ms (`null` when stopped), not a `Date`. | | `app.getLogs()` | `api.apps.logs(id)` | | | `app.getMetrics()` | `api.apps.metrics(id)` | Newest point first. | | `app.realtime()` → raw `Response` | `api.apps.realtime(id, { signal })` | An async iterable of parsed events. | | `app.start()` / `stop()` / `restart()` / `delete()` | `api.apps.start(id)` / `stop(id)` / `restart(id)` / `delete(id)` | | | `app.commit(file, fileName)` | `api.apps.commit(id, file, { path?, filename?, signal? })` | | | `app.files.list(path)` | `api.apps.files.list(id, path?)` | A missing directory throws 404 `FILE_NOT_FOUND` (it used to be an empty list). | | `app.files.read(path)` → `Buffer \| undefined` | `api.apps.files.read(id, path)` → `Uint8Array` | Requested as base64 and decoded (v5 read a byte array). Empty bytes, never `undefined`, when the API sends no content. | | `app.files.create(file, fileName, dir)` | ``api.apps.files.write(id, `${dir}/${fileName}`, content)`` | A string is the **content** (sent as plain text); v5 read it as a local path. Bytes are sent as base64. Empty content creates an empty file. | | `app.files.edit(file, path)` | `api.apps.files.write(id, path, content)` | Same wire format as `write`: text for strings, base64 for bytes. | | `app.files.move(path, newPath)` / `delete(path)` | `api.apps.files.move(id, path, to)` / `delete(id, path)` | | | `app.envs.list()` | `api.apps.envs.get(id)` | | | `app.envs.set(envs)` / `replace(envs)` / `delete(keys)` | `api.apps.envs.set(id, envs)` / `replace(id, envs)` / `delete(id, keys)` | Each returns the resulting variables. | | `app.snapshots.list()` | `api.apps.snapshots.list(id)` | Items gain `name`, `runtime`, `origin`, `version_id` and a signed download `url`, all as the API sends them. | | `app.snapshots.create()` | `api.apps.snapshots.create(id)` | `{ pending: true }` on 202 (v5 threw), else `{ pending: false, url, key }`. | | `app.snapshots.download()` → `Buffer` | `const s = await api.apps.snapshots.create(id)`, then `if (!s.pending) await api.downloadSnapshot(s.url)` | A `ReadableStream`, nothing buffered. A pending (202) snapshot has no URL yet: v5 threw. | | `snapshot.url` / `snapshot.download()` | `snapshot.url` / `api.downloadSnapshot(snapshot.url)` | The API's own signed URL (v5 built a wrong one from the caller's id). | | `app.snapshots.restore({ snapshotId, versionId })` | `api.apps.snapshots.restore(id, name, versionId)` | Pass `name` and `version_id` of a listed snapshot. See [Snapshots](/en/sdks/js/snapshots#restoring-a-snapshot) for the errors. | | `app.deploys.integrateGithubWebhook(token)` | `api.apps.deploys.setWebhook(id, token)` | Returns the webhook URL (`""` when removed with `"@"`). | | `app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` | `api.apps.deploys.linkGithubApp(id, repository, branch)` | Positional. Returns `{ id, full_name, branch }`. API keys are now accepted (scope `apps:deploy`); v5 needed a session JWT. | | `app.deploys.unlinkGithubApp()` → `boolean` | `api.apps.deploys.unlinkGithubApp(id)` | Resolves to `void` (was `boolean`). `400 GIT_NOT_CONFIGURED` when nothing is linked. | | `app.deploys.list()` → `Deployment[][]` | `api.apps.deploys.list(id)` → `DeployEvent[][]` | A failed deploy ends in `state: "error"` with `code` (and `message` when there are details); `source` is always `"git"`. | | `app.deploys.current()` | `api.apps.deploys.current(id)` → `DeployCurrent` | `{}` when nothing is configured. | | `app.deploys.webhookURL()` | `(await api.apps.deploys.current(id)).webhook` | | | `app.network` (only on `WebsiteApplication`) | `api.apps.network` | Any app id; the API rejects non-web apps. | | `network.setCustomDomain(domain)` | `api.apps.network.setDomain(id, domain)` | | | `network.analytics({ start, end, contentType, ... })` | `api.apps.network.analytics(id, start, end, { content_type, ... })` | `null` for an empty window. | | `network.errors({ start, end, include4xx })` | `api.apps.network.errors(id, start, end, { include_4xx })` | `null` for an empty window. | | `network.logs({ start, end })` / `performance({ start, end })` | `api.apps.network.logs(id, start, end)` / `performance(id, start, end)` | | | `network.dns()` / `purgeCache()` | `api.apps.network.dns(id)` / `purgeCache(id)` | | | `api.databases.fetch(id)` / `db.fetch()` | `api.databases.get(id)` | | | `api.databases.create(options)` / `statusAll()` | unchanged | `statusAll()` returns plain `{ id, running, cpu?, ram? }` objects. | | `db.getStatus()` / `getMetrics()` | `api.databases.status(id, { raw? })` / `metrics(id)` | `ram` is RAM in use, e.g. `"120.4MB"` (a number with `raw`). Metrics come newest first. | | `db.start()` / `stop()` / `update(changes)` / `delete()` | `api.databases.start(id)` / `stop(id)` / `update(id, changes)` / `delete(id)` | | | `db.credentials.certificate()` | `api.databases.certificate(id)` | | | `db.credentials.reset(type)` | `api.databases.resetCredentials(id, type)` | The new password (`""` for `"certificate"`). | | `db.snapshots.list()` / `create()` / `download()` | `api.databases.snapshots.list(id)` / `create(id)` / `api.downloadSnapshot(url)` | `download()` as for apps: `create(id)`, then `downloadSnapshot(s.url)` when not pending. | | `db.snapshots.restore(snapshotId, versionId)` | `api.databases.snapshots.restore(id, name, versionId)` | Pass `name` and `version_id` of a listed snapshot. | | `api.workspaces.list()` / `fetch(id)` / `workspace.fetch()` | `api.workspaces.list()` / `get(id)` | | | `api.workspaces.create({ name })` | `api.workspaces.create(name)` | Returns `WorkspaceCreated` (`{ id, name }`). | | `api.workspaces.delete(id)` / `workspace.delete()` | `api.workspaces.delete(id)` | | | `api.workspaces.leave(id)` / `workspace.leave()` | `api.workspaces.leave(id)` | | | `api.workspaces.generateInviteCode()` | `api.workspaces.members.inviteCode()` | | | `workspace.members.add(code, group)` | `api.workspaces.members.add(workspaceId, code, group)` | | | `workspace.members.update(memberId, group)` / `remove(memberId)` | `api.workspaces.members.update(workspaceId, memberId, group)` / `remove(workspaceId, memberId)` | | | `workspace.applications.add(appId)` / `remove(appId)` | `api.workspaces.apps.add(workspaceId, appId)` / `remove(workspaceId, appId)` | | | (none) | `api.ai.chat(request)`, `api.downloadSnapshot(url)`, `BASE_URL` | New. | ## Types Types ship with the SDK and mirror the API's field names. The main renames from `@squarecloud/api-types` and the v5 classes: | v5 | v6 | | - | - | | `Application`, `WebsiteApplication`, `BaseApplication` | `App` (`api.apps.get()`), `AppSummary` (`account.me()`), `AppCreated` | | `ApplicationStatus`, `SimpleApplicationStatus`, `SimpleDatabaseStatus` | `RuntimeStats` (`RuntimeStats` with `{ raw: true }`), `StatusListItem` | | `User` | `Account` (`{ user, applications, databases }`), `User`, `Plan` | | `Snapshot`, `DatabaseSnapshot` | `Snapshot`, `SnapshotCreated` | | `Deployment`, `DeploymentState` | `DeployEvent`, `DeployCurrent` (with `DeployRepository`), `LinkedRepository` | | Network query objects | `AnalyticsFilters` (the optional filters; `start` and `end` are arguments) | | `Workspace` | `Workspace`, `WorkspaceCreated`, `WorkspaceGroup` | | `APIErrorCode` (runtime object) | `ErrorCode` (type only, no runtime cost; every code of the API's contract) | | `APIEndpoint`, `APIEndpoints`, `APIMethod`, `APIRequestArgs`, `APIRequestOptions`, `APIResponse`, `QueryOrBody`, `ClientEvents`, `TypedEventEmitter`, `CollectionConstructor` | Removed (request plumbing, events and `Collection`) | ## Errors ```ts theme={"system"} // v5 catch (e) { if (e.code === "RATE_LIMIT_EXCEEDED") ... } // v6 catch (e) { if (e instanceof SquareCloudAPIError && e.status === 429) { console.log(e.code, e.message); // KEEP_CALM "Please wait 5 seconds..." or RATE_LIMITED } } ``` * Synthetic codes are gone (`RATE_LIMIT_EXCEEDED`, `PAYLOAD_TOO_LARGE`, `SERVER_UNAVAILABLE`, `UNKNOWN_ERROR_`): the API's real code surfaces (`RATE_LIMITED`, `KEEP_CALM`, `DAILY_SNAPSHOTS_LIMIT_REACHED`, `FILE_TOO_LARGE`...). * No response: `status: 0` with `NETWORK_ERROR` (the cause in `cause`) or `TIMEOUT`. A body without a code is `UNKNOWN_ERROR` with the real `status` and the message `HTTP `. * `instanceof TypeError` is no longer true for API errors. * An expired key is 401 `ACCESS_DENIED`, like an unknown one. * `ai.chat()` errors, auth and rate limits included, carry the lowercase OpenAI code (`access_denied`, `rate_limit_exceeded`, ...). * A refused `start`/`stop`/`restart` is 409 with a code only: `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_TEMPORARILY_SUSPENDED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` or `ACTION_FAILED`. ## Behavior changes * Calls time out: 30 s per attempt by default (v5 had no timeout), at least 120 s for calls the server holds open. Set `timeoutMs: 0` for none. * `files.write()` treats a string as the content and sends it as plain text; bytes go as base64, binary-safe, and empty content creates an empty file (same wire format as the Python and Go SDKs). `files.read()` asks for base64 and decodes it. * `files.list()` of a missing directory throws 404 `FILE_NOT_FOUND` instead of returning `[]`. * `snapshots.create()` returns `{ pending: true }` on 202 instead of throwing. * String results are never `undefined`: `setWebhook` and `resetCredentials("certificate")` return `""` when the API sends none; `deploys.current()` returns `{}`. * `realtime()` reconnects on dropped connections and on `REALTIME_RECONNECT` (up to 3 times in a row, at most one open per 5.5 s). * Retries: network errors on GET and 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY` (plus `DATABASE_UNAVAILABLE` on GET), with backoff. 429 is never retried. `DATABASE_UNAVAILABLE` can come after a mutation was applied: retry your idempotent mutations yourself. * Empty, `.` and `..` ids fail locally with `INVALID_ID`. * Query values that are `undefined`, `""` or `false` are not sent. ## Next steps Install the SDK and create a client. Error class, retries and rate limits. # JavaScript SDK: analytics, DNS and domains Source: https://docs.squarecloud.app/en/sdks/js/network Read edge analytics, errors, request logs and performance of a web application, check DNS, set a custom domain and purge the cache with api.apps.network. `api.apps.network` works on **web apps only**. Every method takes the app id first. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Time windows `analytics`, `errors`, `logs` and `performance` take a `start` and an `end`, each an ISO 8601 string or a `Date`. A window is at most **7 days**, and `start` is clamped to the app's creation date. An invalid window is 400 `INVALID_TIME_RANGE`. ```typescript theme={"system"} const end = new Date(); const start = new Date(end.getTime() - 24 * 60 * 60 * 1000); // last 24 h ``` Results are cached in 5-minute buckets. Cache misses of these four methods share a limit of 20 requests per 60 seconds per account: going over it is 429 `RATE_LIMITED`. ## Analytics `network.analytics(appId, start, end, filters?)` returns traffic totals and breakdowns. It returns `null` for a window with no traffic. ```typescript theme={"system"} const analytics = await api.apps.network.analytics(appId, start, end); if (analytics) { console.log(analytics.visits); // [{ visits, requests, bytes, date }] console.log(analytics.countries); // [{ type: "BR", visits, requests, bytes }] } ``` The breakdowns are `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` and `content_types`. Each bucket has `type`, `visits`, `requests` and `bytes`. ### Filters Filters narrow every breakdown. Each takes the exact `type` value of its breakdown: ```typescript theme={"system"} const brazil = await api.apps.network.analytics(appId, start, end, { country: "BR", path: "/api", provider: "GOOGLE (15169)", }); ``` | Filter | Example | | - | - | | `country` | `"BR"` (2-letter code) | | `ip` | `"203.0.113.7"` | | `path` | `"/api"` (path prefix) | | `status` | `"404"` | | `os`, `browser`, `protocol`, `bot` | The breakdown's `type` | | `referer` | `"Direct"` means no referer | | `provider` | `"NAME (ASN)"`, e.g. `"GOOGLE (15169)"` | | `content_type` | The breakdown's `type` | An invalid filter is 400 `INVALID_FILTER`. ## Errors `network.errors(appId, start, end, { include_4xx })` returns the 5xx responses of the window, plus 4xx with `include_4xx: true`. It returns `null` for an empty window. ```typescript theme={"system"} const errors = await api.apps.network.errors(appId, start, end, { include_4xx: true }); if (errors) { console.log(errors.summary.total, errors.summary.by_class); console.log(errors.top_paths); } ``` ## Request logs `network.logs(appId, start, end)` returns individual requests with client, request and response details. Available on Pro and Enterprise plans (403 `UPGRADE_REQUIRED` otherwise). ```typescript theme={"system"} for (const log of await api.apps.network.logs(appId, start, end)) { console.log(log.timestamp, log.request.method, log.request.path, log.response.status); } ``` ## Performance `network.performance(appId, start, end)` returns latency percentiles (`p50`, `p95`, `p99`, in ms) at the edge and at the origin, by country, by location and for the slowest paths. It returns `null` for an empty window. Available on Pro and Enterprise plans. ```typescript theme={"system"} const performance = await api.apps.network.performance(appId, start, end); if (performance) { console.log(performance.summary.edge.p95, performance.summary.origin.p95); } ``` ## DNS `network.dns(appId)` returns the DNS records your custom domain needs, with their status. Without a custom domain it is 400 `NO_CUSTOM_DOMAIN`. ```typescript theme={"system"} for (const { type, name, value, status } of await api.apps.network.dns(appId)) { console.log(type, name, value, status); // type: "txt" | "cname" } ``` ## Custom domain `network.setDomain(appId, domain)` attaches a custom domain (Standard plan and up). Pass `"@"` to remove it. ```typescript theme={"system"} await api.apps.network.setDomain(appId, "www.example.com"); // Remove it await api.apps.network.setDomain(appId, "@"); ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_DOMAIN` | Not a valid domain name | | 400 | `RESERVED_DOMAIN` | A Square Cloud domain | | 403 | `UPGRADE_REQUIRED` | The plan has no custom domains | | 403 | `LOAD_BALANCER_LIMIT_REACHED` | The plan's limit of apps on this domain was reached | | 409 | `DOMAIN_ALREADY_EXISTS` | The domain belongs to an app of another account | | 502 | `DNS_FAILED` | The edge provider refused the domain | ## Purging the cache `network.purgeCache(appId)` clears the app's edge cache. It is limited to one purge every 60 seconds (429 `KEEP_CALM`). ```typescript theme={"system"} await api.apps.network.purgeCache(appId); ``` ## Errors of the analytics methods | Status | Code | When | | - | - | - | | 400 | `INVALID_TIME_RANGE` | `start`/`end` missing, malformed or inverted | | 400 | `INVALID_FILTER` | A filter does not match its format (`analytics`) | | 403 | `UPGRADE_REQUIRED` | `logs` and `performance` outside Pro and Enterprise | | 429 | `RATE_LIMITED` | Shared limit of cache misses reached | | 500 | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | The edge provider failed | | 503 | `ANALYTICS_BUSY` | Edge analytics are busy: retried automatically | ## Next steps Stream live logs and status. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: live logs and status Source: https://docs.squarecloud.app/en/sdks/js/realtime Stream an application's live logs, status and system events with api.apps.realtime(), an async iterable that merges status frames and reconnects on its own. `api.apps.realtime(appId, { signal })` opens a live stream of an app's logs, status and system events. It is an **async iterable**: consume it with `for await`. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ```typescript theme={"system"} const controller = new AbortController(); for await (const event of api.apps.realtime(appId, { signal: controller.signal })) { if (event.event === "logs") { console.log(event.stream, event.line); // "stdout" | "stderr" } else if (event.event === "status") { console.log(event.status.cpu, event.status.ram); // always the full, merged state } else { console.log(event.event, event.data); // "system" or "error" } } ``` ## Events Every event has `event`, `data` (the raw frame text) and `id`. | `event` | Extra fields | Description | | - | - | - | | `logs` | `stream`, `line` | One log line. The first character of `data` tells the stream (`\u0001` stdout, `\u0002` stderr); the SDK strips it into `line` and sets `stream` to `"stdout"` or `"stderr"` | | `status` | `status` | Live container metrics. The first frame is complete and the next ones only carry what changed: the SDK merges them, so `status` is always the full state | | `system` | | Connection events such as `REALTIME_CONNECTING \| `, `REALTIME_TIMEOUT` or `REALTIME_DISCONNECTED` | | `error` | | An error code such as `CONTAINER_NOT_FOUND` | | `message` | | A frame without an `event` name | ### The `status` object | Field | Description | | - | - | | `cpu` | CPU usage (%) | | `cpuLimit` | Number of CPU cores allocated | | `ram` | `[usedMB, limitMB]` | | `status` | Container state, e.g. `running` | | `netIO` | Network `{ i, o }` totals, with `new` for the latest interval | | `bIO` | Disk `{ i, o }` totals | | `uptime` | Unix ms of the container start | ## Ending the stream The loop ends on its own when: * the server closes the connection cleanly (each connection lasts up to **10 minutes**); * the server sends `REALTIME_DISCONNECTED`; * you `break` out of the loop; * you call `controller.abort()` (the loop just ends, it does not throw). To keep watching past 10 minutes, open a new stream when the loop ends. ## Reconnection A dropped connection, or the server handing reconnection to the client (`REALTIME_RECONNECT`), reopens the stream on its own: * up to **3 times in a row**; any `logs` or `status` event resets the count; * each reopen at least **5.5 s** after the previous open, to stay under the API's pace of one open per 5 seconds per app. Past 3 failed reconnections, the loop throws a `SquareCloudAPIError` with `NETWORK_ERROR`. ## Limits and errors * **5** concurrent connections per account and **30** per app, across all users. Going over is 429 `REALTIME_MAX_CONNECTIONS` or `REALTIME_MAX_CONNECTIONS_APP`. * The HTTP status is checked before streaming, so these errors (and 404 for an unknown app) throw on the first iteration. * The timeout only covers the open, until the response headers arrive. The stream itself has no timeout. ## Next steps Back up and restore apps and databases. The REST endpoint behind this stream. The same stream from the terminal. # JavaScript SDK: snapshots and backups Source: https://docs.squarecloud.app/en/sdks/js/snapshots List, create and restore snapshots of applications and databases, list every snapshot of the account, and download a snapshot file with api.downloadSnapshot(). Snapshots are backups of an app's or database's storage. Apps and databases share the same three methods: * `api.apps.snapshots`: `list(appId)`, `create(appId)`, `restore(appId, name, versionId)` * `api.databases.snapshots`: `list(databaseId)`, `create(databaseId)`, `restore(databaseId, name, versionId)` How many snapshots you can create per day depends on your plan (see [Limits](#limits)). Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `appId` is the id of one of your apps: [`api.account.me()`](/en/sdks/js/client#account) lists them. ## Listing snapshots ```typescript theme={"system"} for (const snapshot of await api.apps.snapshots.list(appId)) { console.log(snapshot.name, snapshot.version_id, snapshot.size, snapshot.modified); } ``` | Field | Description | | - | - | | `name` | The snapshot id that `restore` takes | | `version_id` | The version that `restore` takes | | `size` | Size in bytes | | `modified` | When it was taken | | `url` | Signed download URL, **valid for 30 days** | | `key` | Signed query string of the URL | | `runtime` | Database engine or app language (`null` on old snapshots) | | `origin` | `"automatic"`, `"manual"` or `null` | ## Creating a snapshot `create()` waits for the snapshot (at least 120 s before timing out). A large snapshot may not finish in time: the API then answers 202 and the SDK returns `{ pending: true }`. The snapshot keeps generating and shows up in `list()` on its own, usually within 2 minutes. ```typescript theme={"system"} const result = await api.apps.snapshots.create(appId); if (result.pending) { // Poll list() later. Do not call create() again: that starts a new snapshot. } else { console.log(result.url); // signed download URL, valid 30 days } ``` Never call `create()` again to check on a pending snapshot: it starts a new one and counts against the plan's daily snapshot quota. Poll `list()` instead. ## Restoring a snapshot `restore(id, name, versionId)` takes the `name` and `version_id` of a listed snapshot. ```typescript theme={"system"} const [latest] = await api.apps.snapshots.list(appId); await api.apps.snapshots.restore(appId, latest.name, latest.version_id); ``` | Status | Code | When | | - | - | - | | 400 | `MISSING_PARAMETERS` | `name` or `versionId` is missing | | 400 | `INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID` | Not a `name`/`version_id` from the listing | | 400 | `SNAPSHOT_DATABASE_MISMATCH` | The snapshot's engine does not match the database's type (databases only) | | 404 | `SNAPSHOT_NOT_FOUND` | No snapshot with that name and version | | 404 | `SNAPSHOT_RESTORE_FAILED` | The restore could not be dispatched (the usual failure) | | 413 | `PAYLOAD_TOO_LARGE` | The snapshot is too large to restore | ## Downloading a snapshot `api.downloadSnapshot(url, { signal })` streams a snapshot file from its signed `url` (from `list()` or `create()`). It does **not** call the API: the API key is never sent to the storage host. It returns a `ReadableStream`, with nothing buffered in memory, and has no timeout (pass a `signal`). ```typescript theme={"system"} import { createWriteStream } from "node:fs"; import { Writable } from "node:stream"; const [latest] = await api.apps.snapshots.list(appId); const stream = await api.downloadSnapshot(latest.url); await stream.pipeTo(Writable.toWeb(createWriteStream("backup.zip"))); ``` An expired or invalid URL throws a `SquareCloudAPIError` with the storage host's HTTP status and `UNKNOWN_ERROR`. ## Account snapshots `api.account.snapshots({ scope })` lists every snapshot of the account, optionally only `"applications"` or `"databases"`. It needs an active plan and shares the network endpoints' rate limit (429 `RATE_LIMITED`). ```typescript theme={"system"} const all = await api.account.snapshots(); const databases = await api.account.snapshots({ scope: "databases" }); ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_SCOPE` | `scope` is not `applications` or `databases` | | 402 | `UPGRADE_REQUIRED` | The account has no active plan | | 429 | `RATE_LIMITED` | Rate limit reached | ## Limits * `create()` is limited to one call per 180 seconds and to a daily quota that depends on the plan: going over the quota is 429 `DAILY_SNAPSHOTS_LIMIT_REACHED`. * While a restore runs, deleting the app or starting the database is 403 `RESTORE_IN_PROGRESS`. ## Next steps Create and manage databases. The REST endpoints behind these methods. The same actions from the terminal. # JavaScript SDK: workspaces and members Source: https://docs.squarecloud.app/en/sdks/js/workspaces Create and manage workspaces, invite members, set their roles and share applications with api.workspaces. Act on a shared app with its composite id. A workspace shares apps with other Square Cloud users, each with a role. `api.workspaces` manages workspaces, `api.workspaces.members` their members and `api.workspaces.apps` the shared apps. Creating workspaces needs a Standard, Pro or Enterprise plan. Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `workspaceId` is the id of a workspace (`workspaces.list()` lists them), `appId` the id of one of your apps and `memberId` the `id` of a member. ## Workspaces ```typescript theme={"system"} const { id, name } = await api.workspaces.create("My team"); const workspaces = await api.workspaces.list(); const workspace = await api.workspaces.get(id); console.log(workspace.name, workspace.owner, workspace.createdAt); for (const member of workspace.members) { console.log(member.id, member.name, member.group, member.joinedAt); } for (const app of workspace.applications) { console.log(app.id, app.name, app.lang, app.ram); } await api.workspaces.leave(id); // as a member await api.workspaces.delete(id); // as the owner ``` | Field | Description | | - | - | | `id` | 32 hex characters (older workspaces keep a 40-character id) | | `name` | Workspace name (1 to 32 characters) | | `owner` | Owner's user id | | `members` | `{ id, name, group, joinedAt }`. `name` is `null` when it cannot be resolved (a deleted account) | | `applications` | `{ id, name, desc, ram, lang, domain?, custom? }` | | `createdAt` | Creation date | The owner cannot leave (400 `CANNOT_LEAVE_OWNER`): delete the workspace instead. ## Members Adding a member takes an **invite code** that the member generates with `members.inviteCode()`. The code is valid for **5 minutes**. ```typescript theme={"system"} // The member runs this and sends you the code const code = await api.workspaces.members.inviteCode(); // The owner adds them with a role await api.workspaces.members.add(workspaceId, code, "maintain"); await api.workspaces.members.update(workspaceId, memberId, "view"); await api.workspaces.members.remove(workspaceId, memberId); ``` Roles (`group`): `view`, `manager`, `maintain` and `admin`. Calling a method that your role does not allow is 403 `PERMISSION_DENIED`. ## Shared applications ```typescript theme={"system"} await api.workspaces.apps.add(workspaceId, appId); await api.workspaces.apps.remove(workspaceId, appId); ``` A workspace can hold up to 100 apps (400 `APPLICATIONS_LIMIT_REACHED`). ### Acting on a shared app To act on an app shared with you, pass the composite id `-` to any `api.apps` method. `workspaces.get()` and `workspaces.list()` return raw ids, so build it yourself: ```typescript theme={"system"} const workspace = await api.workspaces.get(workspaceId); for (const app of workspace.applications) { const status = await api.apps.status(`${app.id}-${workspace.id}`); console.log(app.name, status.running); } // Status of every app of the workspace in one request const statuses = await api.apps.statusAll({ workspaceId }); ``` ## Errors Except `workspaces.get()`, workspace routes send the ids in the request body, so an empty id there is 400 `INVALID_ID` from the server, not a local error. | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `WORKSPACE_LIMIT_REACHED`, `MEMBERS_LIMIT_REACHED`, `APPLICATIONS_LIMIT_REACHED` | A plan or workspace limit was reached | | 400 | `INVALID_CODE` | The invite code is missing, malformed or expired | | 400 | `INVALID_GROUP` | The role is not `view`, `manager`, `maintain` or `admin` | | 400 | `CANNOT_INVITE_OWNER`, `CANNOT_EDIT_OWNER`, `CANNOT_LEAVE_OWNER` | The action does not apply to the owner | | 400 | `MEMBER_ALREADY_ADDED`, `APP_ALREADY_IN_WORKSPACE` | Already in the workspace | | 403 | `UPGRADE_REQUIRED` | The plan cannot create workspaces | | 403 | `PERMISSION_DENIED` | Your role does not allow the action | | 404 | `WORKSPACE_NOT_FOUND`, `MEMBER_NOT_FOUND`, `APP_NOT_FOUND` | Not found | ## Next steps Chat completions through the AI Gateway. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: AI Gateway chat Source: https://docs.squarecloud.app/en/sdks/py/ai Call the Square Cloud AI Gateway from squarecloud-api with client.ai.chat(): OpenAI-compatible chat completions, without streaming. `client.ai.chat(request)` calls the [AI Gateway](/en/api-reference/ai-gateway), an **OpenAI-compatible** chat completions endpoint. It needs the `ai:chat` scope and a Standard plan or above. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). ```python theme={"system"} completion = client.ai.chat({ "model": "cubic", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is Square Cloud?"}, ], "max_tokens": 512, }) print(completion["choices"][0]["message"]["content"]) print(completion["usage"]["total_tokens"]) ``` ## Request `request` is a dict sent as the body, as is, so any other OpenAI parameter passes through. It is typed as `squarecloud.types.ChatRequest`. | Field | Description | | - | - | | `model` | `cubic`. Accepted for compatibility: there is no other model | | `messages` | `{ role, content?, tool_call_id?, tool_calls? }`, with `role` `system`, `user`, `assistant` or `tool` | | `tools` / `tool_choice` | OpenAI function calling | | `max_tokens` | Maximum tokens of the answer | | `temperature` | Sampling temperature | The response has the OpenAI shape: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) and `usage`. ## No streaming `ai.chat()` does not stream: it returns the whole completion. `"stream": True` is 400 `stream_not_supported`. ## Timeout The gateway gives each request **90 seconds** in total, then answers 503 `server_overloaded`. The SDK waits at least 120 s before timing out, so you get the gateway's answer. ## Errors AI errors use the OpenAI format, so their codes are **lowercase**. They still raise a [`SquareCloudAPIError`](/en/sdks/py/errors), with `code` set to the OpenAI code (or its `type` when there is no code): ```python theme={"system"} from squarecloud import SquareCloudAPIError try: client.ai.chat({"messages": [{"role": "user", "content": "Hi"}]}) except SquareCloudAPIError as error: if error.code == "server_overloaded": ... # safe to retry yourself else: raise ``` | Status | Code | When | | - | - | - | | 400 | `stream_not_supported` | `stream: true` was sent | | 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | A malformed field | | 400 | `context_length_exceeded` | The conversation exceeds the plan's context window | | 401 | `access_denied` | Invalid API key | | 403 | `upgrade_required` | The plan has no AI Gateway access | | 429 | `rate_limit_exceeded`, `concurrent_limit_reached` | Too fast, or a request already in flight | | 429 | `daily_limit_reached`, `weekly_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached` | A daily or weekly limit is used up (daily limits reset at 00:00 UTC, weekly ones on Monday at 00:00 UTC) | | 503 | `server_overloaded` | Capacity is full or the 90 s deadline passed: safe to retry | | 503 | `daily_capacity_reached` | The platform's daily capacity is used up | The SDK **never retries** AI errors: the request is a non-idempotent `POST`. See the [AI Gateway reference](/en/api-reference/ai-gateway) for plan limits. ## Next steps Error class, retries and rate limits. Models, plan limits and the OpenAI-compatible endpoint. # Python SDK: quickstart and client Source: https://docs.squarecloud.app/en/sdks/py/client Install the Square Cloud Python SDK (squarecloud-api 5), create a sync or async client with your API key and follow its conventions: ids, dates and timeouts. This page documents **`squarecloud-api` 5.0**, a rewrite of the SDK. Coming from v4? Read the [v4 → v5 migration guide](/en/sdks/py/migrating_to_v5). ## Requirements * **Python 3.11** or newer. * An API key (see [API key and scopes](#api-key-and-scopes)). The package has **no runtime dependencies** (only the standard library: `http.client`, `json`, `ssl`) and is fully typed (`py.typed`): responses are `TypedDict`s your editor and type checker understand. ## Installation ```bash theme={"system"} pip install squarecloud-api ``` ```bash theme={"system"} uv add squarecloud-api ``` ```bash theme={"system"} poetry add squarecloud-api ``` The package installs as `squarecloud-api` and is imported as `squarecloud`. The installed version is `squarecloud.__version__`. ## API key and scopes Create a key at [squarecloud.app/account/security](https://squarecloud.app/en/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 raises a [`SquareCloudAPIError`](/en/sdks/py/errors) with 403 `MISSING_SCOPE` or `RESOURCE_NOT_ALLOWED`. * List methods (`account.me()`, `apps.status_all()`, ...) only return the resources the key can see. * An unknown, revoked or expired key is 401 `ACCESS_DENIED`. Keep the key out of your source code: read it from the environment (`os.environ["SQUARECLOUD_API_KEY"]`) or a secret manager. The examples read the key from the `SQUARECLOUD_API_KEY` environment variable. Set it in the terminal where you run them: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` ```powershell theme={"system"} $env:SQUARECLOUD_API_KEY = "your-api-key" ``` ## Creating the client The SDK has two clients with the same groups and methods: * **`SquareCloud`** is synchronous and **thread-safe**: share one instance between threads. Each thread reuses its own keep-alive connection. * **`AsyncSquareCloud`** is the same API with `await`. Each call runs the synchronous client in `asyncio.to_thread`, so the event loop is never blocked. ```python theme={"system"} import os from squarecloud import SquareCloud with SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client: me = client.account.me() print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps") ``` ```python theme={"system"} import asyncio import os from squarecloud import AsyncSquareCloud async def main() -> None: async with AsyncSquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client: me = await client.account.me() print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps") asyncio.run(main()) ``` Both print your account name and the number of apps the key can see: ```text theme={"system"} Hi Jane, you have 3 apps ``` Leaving the `with` / `async with` block closes the pooled connections. Without a block, call `client.close()` when you are done. `close()` is a regular (synchronous) method on both clients. An empty or whitespace-only key raises a `ValueError` in the constructor, before any request. ### The async client `AsyncSquareCloud` differs from `SquareCloud` in only three places: * Every method returns a coroutine: `await client.apps.status(app_id)`. * `close()` is synchronous: call it without `await`. * `apps.realtime(app_id)` is **not** awaited: it returns an `AsyncRealtime` that you consume with `async for` (see [Realtime](/en/sdks/py/realtime)). Since each call runs in a worker thread, you can run calls concurrently with `asyncio.gather`: ```python theme={"system"} apps, databases = await asyncio.gather( client.apps.status_all(), client.databases.status_all(), ) ``` Cancelling an awaiting task does not stop the request already running in its worker thread: the call still completes (or times out) in the background. ### Options ```python theme={"system"} import os from squarecloud import BASE_URL, SquareCloud client = SquareCloud( os.environ["SQUARECLOUD_API_KEY"], base_url=BASE_URL, # "https://api.squarecloud.app/v2" (default) timeout=30.0, max_retries=2, user_agent="my-bot/1.0", transport=None, # a custom transport (proxy, tracing, tests) ) ``` The options are keyword-only, and `AsyncSquareCloud` takes the same ones. | Option | Default | Description | | - | - | - | | `base_url` | `https://api.squarecloud.app/v2` | API base URL. A trailing `/` is stripped. Also exported as `BASE_URL`. | | `timeout` | `30.0` | Seconds **per socket operation** (the connect and each read or write), not for the whole request. See [Timeouts](#timeouts). | | `max_retries` | `2` | Retries of safe failures only (up to 3 attempts). A negative value counts as `0`. See [Retries](/en/sdks/py/errors#retries). | | `user_agent` | `squarecloud-sdk-py/` | Replaces the whole `User-Agent` header. | | `transport` | `HTTPTransport(timeout)` | A custom transport for proxies, tracing or tests. See [Advanced](#advanced). | The client keeps the key only in its private request headers: there is no `client.api_key` attribute, and the SDK's logger never writes it. ## Modules | Attribute | Covers | Page | | - | - | - | | `client.account` | `me()`, `snapshots(scope=)` | [Account](#account) and [Snapshots](/en/sdks/py/snapshots) | | `client.service` | `status()` | [Platform status](#platform-status) | | `client.apps` | Get, delete, status, lifecycle, logs, metrics, domains, load balancers | [Managing applications](/en/sdks/py/managing_application) | | `client.apps.create` / `commit` | Uploads | [Commit and upload](/en/sdks/py/commit_and_upload) | | `client.apps.files` | File manager | [Managing files](/en/sdks/py/managing_files) | | `client.apps.envs` | Environment variables | [Environment variables](/en/sdks/py/environment_variables) | | `client.apps.deploys` | Webhook and GitHub App deploys | [Deploys](/en/sdks/py/deploys) | | `client.apps.network` | Analytics, logs, DNS, custom domain, cache | [Network](/en/sdks/py/network) | | `client.apps.realtime` | Live logs and status | [Realtime](/en/sdks/py/realtime) | | `client.apps.snapshots` / `client.databases.snapshots` / `client.download_snapshot` | Backups | [Snapshots](/en/sdks/py/snapshots) | | `client.databases` | Managed databases | [Databases](/en/sdks/py/databases) | | `client.workspaces` | Workspaces, members and shared apps | [Workspaces](/en/sdks/py/workspaces) | | `client.ai` | `chat()` | [AI](/en/sdks/py/ai) | The package exports `SquareCloud`, `AsyncSquareCloud`, `SquareCloudAPIError`, `BASE_URL`, `HTTPTransport`, the `Transport` and `Response` protocols, `Realtime`, `AsyncRealtime` and `__version__`. The response types (`App`, `RuntimeStats`, `Snapshot`, ...) live in `squarecloud.types`: ```python theme={"system"} from squarecloud.types import App, Snapshot ``` ## Conventions ### Ids first, plain data back Every method takes the resource id as its first argument and returns **plain data**: each response is a `TypedDict`, which is a regular `dict` at runtime (no classes, no cache), so fields the API adds later are kept. Field names are the API's own (`created_at`, `version_id`, `lastModified`, `joinedAt`, `netIO`, ...), so the [API reference](/en/api-reference/authentication) applies as-is. * Mutations return `None`, unless the API returns data (`envs.*`, `deploys.set_webhook`, `deploys.link_github_app`, `databases.reset_credentials` and the `create` methods). * A string result is never `None`: it is `''` when the API sends none. * Lists come complete in one call: there is no pagination. * Optional modifiers are **keyword-only** (`status(app_id, raw=True)`, `commit(app_id, file, path="/src")`). The one exception is the optional `path` of `files.list`, which can also be passed by position. Methods are regular bound methods, so you can keep a reference to them: ```python theme={"system"} restart = client.apps.restart logs = client.apps.logs restart(app_id) print(logs(app_id)) ``` ### Workspace apps Every `app_id` also accepts the composite form `-` to act on an app shared with you through a [workspace](/en/sdks/py/workspaces). `workspaces.get()` and `workspaces.list()` return raw ids; you build the composite id yourself: ```python theme={"system"} client.apps.restart(f"{app_id}-{workspace_id}") ``` ### 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](/en/sdks/py/network)) take an ISO 8601 string (sent as is) or a `datetime` (sent in UTC). A **naive** `datetime` is treated as local time and converted to UTC, so prefer aware ones (`datetime.now(UTC)`). Dates in responses stay as the API sends them (ISO strings, or Unix milliseconds where the API uses them). ## Timeouts `timeout` bounds **each socket operation**: the connect and every read or write. A response that keeps sending data can take longer than `timeout` in total. | Call | Timeout | | - | - | | Every other call | `timeout` (30 s) per socket operation | | 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 `timeout` wins) | | Uploads (`apps.create`, `apps.commit`) and `files.write` above 1 MiB | None once connected (the connect is still bounded by `timeout`) | | `download_snapshot` | `timeout` per read, not for the whole download | | `apps.realtime` | Only until the response headers arrive | A `timeout` of `0` or less disables **every** timeout, the 120 s floors included. Calls cannot be cancelled once sent: the only stream you can stop midway is [`apps.realtime()`](/en/sdks/py/realtime), with `close()` from any thread. For a long upload, keep the default timeout so a dead connection is detected on connect, and run it in a thread or with `AsyncSquareCloud` if the rest of your program must keep going. ## Account `client.account.me()` returns the authenticated user plus the apps and databases the key can see. ```python theme={"system"} from datetime import datetime me = client.account.me() user = me["user"] print(user["id"], user["name"], user["email"], user["plan"]["name"]) print(user["plan"]["memory"]) # {'limit', 'available', 'used'} in MB duration = user["plan"]["duration"] print(datetime.fromtimestamp(duration / 1000) if duration else "never expires") ``` | Field | Description | | - | - | | `user` | `id`, `name`, `email`, `locale`, `created_at` and `plan` (`name`, `memory`, `duration`: the Unix ms at which the plan **expires**, `None` if it never does) | | `applications` | List of `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }` | | `databases` | List of `{ id, name, ram, type, cluster, created_at }` | `client.account.snapshots(scope=...)` lists every snapshot of the account: see [Snapshots](/en/sdks/py/snapshots#account-snapshots). ## Platform status `client.service.status()` returns the public platform status. The route needs no valid key, but the client still requires a non-empty one. ```python theme={"system"} status = client.service.status() print(status["status"]) # "online" | "degraded" | "unknown" print(status["message"]) for name, service in status.get("services", {}).items(): print(name, service["status"]) # "operational" | "degraded" | "outage" | "maintenance" | "unknown" ``` `unknown` means the check itself could not run: it is not evidence of an outage. ## Advanced ### Custom transport `transport=` replaces the HTTP layer. Use it for proxies, tracing or tests. A transport is any callable with this signature: ```python theme={"system"} transport(method, url, headers, body, timeout, stream) -> Response ``` | Argument | Description | | - | - | | `method`, `url`, `headers` | The request. `headers` already carries `Authorization` (never sent to the snapshot download host), `User-Agent` and, for uploads, `Content-Length` | | `body` | `bytes`, an iterable of `bytes` chunks (uploads, streamed) or `None` | | `timeout` | The per-socket-operation timeout in seconds, already raised for held calls. `None` for uploads, `files.write` above 1 MiB and the realtime stream: bound their connect yourself | | `stream` | `True` when the caller reads the body incrementally (realtime, snapshot downloads) and may call `close()` from another thread to abort it | The returned object needs `status`, `read()`, `readline()` and `close()`: an `http.client.HTTPResponse` qualifies. Retries, error mapping and the `{status, response}` unwrapping stay in the client, so a transport only moves bytes. `HTTPTransport(timeout=30.0)` is the default transport: one keep-alive connection per thread and host, gzip-compressed responses (except for streams), and `timeout` as the connect bound of the calls without their own timeout. You can wrap it: ```python theme={"system"} import os import time from squarecloud import HTTPTransport, SquareCloud default = HTTPTransport() def timed(method, url, headers, body, timeout, stream): started = time.perf_counter() response = default(method, url, headers, body, timeout, stream) print(method, url, response.status, f"{time.perf_counter() - started:.3f}s") return response client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"], transport=timed) ``` `client.close()` closes the connections of the default transport. A custom transport that has a `close()` method is closed too. ### Logging The SDK logs each request at `DEBUG` on the `squarecloud` logger: method, path and status, **never** bodies or keys. It only attaches a `NullHandler`, so nothing is printed until you configure logging: ```python theme={"system"} import logging logging.basicConfig() logging.getLogger("squarecloud").setLevel(logging.DEBUG) ``` ## Next steps Status, lifecycle, logs and metrics. Error class, retries and rate limits. Base URL, authentication and a first request. Deploy and manage apps from the terminal. # Python SDK: upload and commit files Source: https://docs.squarecloud.app/en/sdks/py/commit_and_upload Create applications from a zip with apps.create() and send files to an existing application with apps.commit(), from a path, bytes or a binary file object. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Accepted inputs `apps.create()` and `apps.commit()` take: | Input | Notes | | - | - | | A file path (`str` or `os.PathLike`) | Streamed from disk, never read into memory. The file's name is used as the filename | | `bytes` (or `bytearray`, `memoryview`) | Sent from memory | | A binary file object (`open(path, "rb")`, `io.BytesIO`, ...) | A seekable file is streamed from its current position; its `name`, if any, is used as the filename. A non-seekable one (a pipe) is read into memory first | Uploads are **limited to 100 MB**. A larger file fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Uploads are streamed and have **no timeout** once connected (see [Timeouts](/en/sdks/py/client#timeouts)). ## Creating an application `apps.create(file)` deploys a `.zip` that contains a [`squarecloud.app`](/en/getting-started/config-file) configuration file at its root. `bytes` and unnamed file objects are sent as `app.zip`. ```python theme={"system"} app = client.apps.create("./bot.zip") print(app["id"], app["name"], app["ram"], app["cpu"], app["language"]["name"], app["language"]["version"]) print(app.get("domain")) # ".squareweb.app" for web apps, absent otherwise print(app.get("cluster")) # the cluster the app was placed on ``` | Field | Description | | - | - | | `id` | The new app's id | | `name` | Name from the config file | | `description` | Present only when set | | `domain` | Full `.squareweb.app` host; absent for non-web apps | | `cluster` | Cluster the app was placed on | | `ram` / `cpu` | Allocated resources | | `language` | `{ name, version }` | ## Committing to an application `apps.commit(app_id, file, path=None, filename=None)` uploads a file into an existing app. `path` and `filename` are keyword-only. * A `.zip` is **unpacked** at `path` (the app root by default). * Any other file lands at `path/`. The filename is `filename`, else the file's own name (path or file object), else `commit.zip`. ```python theme={"system"} # Unpack a zip at the root client.apps.commit(app_id, "./build.zip") # Unpack a zip into /src client.apps.commit(app_id, "./patch.zip", path="/src") # A single file from memory: /src/index.js client.apps.commit(app_id, code.encode(), path="/src", filename="index.js") ``` A commit does not restart the app. Call [`apps.restart()`](/en/sdks/py/managing_application#start-stop-and-restart) to apply it. ## Cancelling an upload Python uploads cannot be cancelled once sent: `apps.create()` and `apps.commit()` have no `signal` or cancel argument, and no timeout once connected. The connect itself is bounded by `timeout`. To keep the rest of your program responsive during a long upload, run it with `AsyncSquareCloud` (it runs in a worker thread) or in your own thread: ```python theme={"system"} async with AsyncSquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client: app = await client.apps.create("./bot.zip") ``` ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | The file is over 100 MB (checked locally) | | 400 | `INVALID_FILE`, `INVALID_FILENAME` | No file, or a file name with path separators, `..` or control characters | | 400 | `INVALID_PATH` | `path` contains traversal or shell metacharacters (commit) | | 400 | `INSUFFICIENT_MEMORY` | Less than 256 MB of available memory on the plan (create) | | 400 | `COMMIT_FAILED` | The commit could not be applied (commit) | | 400 | `UPLOAD_FAILED`, `STORAGE_UPLOAD_FAILED`, `CLUSTER_SELECTION_FAILED` | The upload could not be processed (create) | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance (create) | | 503 | `UPLOAD_BUSY` | Too many uploads in progress: retried automatically | A local path that cannot be opened (or a file that becomes unreadable mid-upload) raises an `OSError`, not a `SquareCloudAPIError`. A missing path fails before anything is sent. See [Errors](/en/sdks/py/errors) for the full list. ## Next steps List, read, write, move and delete app files. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: managed databases Source: https://docs.squarecloud.app/en/sdks/py/databases Create, inspect, update, start, stop and delete managed databases, read their status and metrics, and manage their credentials with client.databases. `client.databases` manages Square Cloud's managed databases (MongoDB, MySQL, PostgreSQL and Redis). Every method except `create` and `status_all` takes the database id first. To list your databases, use [`client.account.me()`](/en/sdks/py/client#account): its `databases` list has every database the key can see. Database hosting needs a Standard, Pro or Enterprise plan. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `database_id` is the id of one of your databases: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Creating a database `databases.create(name, type=, version=, memory=)` takes the name by position and the other fields as **keyword-only** arguments. ```python theme={"system"} db = client.databases.create( "my-db", type="postgres", # "mongo" | "mysql" | "redis" | "postgres" version="17", # a full version or a prefix memory=1024, # MB, an int ) print(db["id"], db["connection_url"], db["cluster"]) print(db["password"]) # shown only here: save it print(db.get("certificate")) # base64 PEM (private key, then certificate), or None ``` | Field | Description | | - | - | | `name` | 1 to 32 characters | | `type` | `mongo`, `mysql`, `redis` or `postgres` | | `version` | A full version or a prefix such as `"8"` | | `memory` | MB, an `int`. At least 512 for Redis and 1024 for the others | The `password` and `certificate` are only returned by `create()` (and by [`reset_credentials()`](#credentials)). The call waits at least 120 s before timing out. | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `INVALID_DATABASE_TYPE`, `INVALID_DATABASE_VERSION` | Unknown type or unsupported version | | 400 | `INVALID_MEMORY` | `memory` is not an `int` (a `float` or a string) | | 400 | `INSUFFICIENT_MEMORY` | `memory` is below the minimum or exceeds the available memory | | 400 | `CLUSTER_SELECTION_FAILED` | No cluster had enough capacity | | 400 / 500 | `DATABASE_CREATION_FAILED` | Provisioning failed | | 403 | `UPGRADE_REQUIRED` | The plan has no database hosting | | 503 | `CLUSTER_MAINTENANCE_TRY_LATER` | Provisioning is paused for maintenance | ## Getting a database ```python theme={"system"} db = client.databases.get(database_id) print(db["id"], db["name"], db["type"], db["ram"], db["port"], db["cluster"], db["created_at"]) ``` ## Updating a database `update(database_id, name=None, ram=None)` renames or resizes a database. Both arguments are keyword-only, and those left as `None` are not sent. Pass at least one (400 `NO_UPDATE_DATA` otherwise). ```python theme={"system"} client.databases.update(database_id, name="orders", ram=2048) ``` ## Start and stop ```python theme={"system"} client.databases.start(database_id) client.databases.stop(database_id) ``` Like app lifecycle calls, they wait at least 120 s, and a refusal is **409** with a code and an empty message: `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` or `ACTION_FAILED`. While a snapshot restore runs, they are 403 `RESTORE_IN_PROGRESS`. ## Status and metrics `status(database_id)` returns formatted values; `raw=True` (keyword-only) returns numbers. `status_all()` returns one summary per database. `metrics(database_id)` returns the last 24 hours, one point every 5 minutes, newest first. ```python theme={"system"} status = client.databases.status(database_id) print(status["running"], status["cpu"], status["ram"]) # True "0.5%" "120.4MB" raw = client.databases.status(database_id, raw=True) print(raw["cpu"], raw["ram"]) # 0.5 120.4 for item in client.databases.status_all(): print(item["id"], item["running"], item.get("cpu"), item.get("ram")) # cpu and ram only while running latest = client.databases.metrics(database_id)[0] print(latest["date"], latest["cpu"], latest["ram"]) ``` The status fields are the same as [app status](/en/sdks/py/managing_application#status). ## Credentials `certificate(database_id)` returns the TLS certificate as base64-encoded PEM. `reset_credentials(database_id, type)` rotates the password (and returns the new one) or the certificate (and returns `''`). The database must be running (400 `DATABASE_NOT_RUNNING`). ```python theme={"system"} import base64 certificate = client.databases.certificate(database_id) pem = base64.b64decode(certificate).decode() password = client.databases.reset_credentials(database_id, "password") client.databases.reset_credentials(database_id, "certificate") # '' ``` ## Deleting a database ```python theme={"system"} client.databases.delete(database_id) ``` Deletion is permanent. Take a [snapshot](/en/sdks/py/snapshots) first if you may need the data again. ## Snapshots `client.databases.snapshots` has the same `list`, `create` and `restore` as apps. See [Snapshots](/en/sdks/py/snapshots). ## Next steps Share apps with your team. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: GitHub deploys Source: https://docs.squarecloud.app/en/sdks/py/deploys Deploy from GitHub with client.apps.deploys: set a webhook, link a repository through the Square Cloud GitHub App, and read the deploy history. `client.apps.deploys` connects an app to GitHub so a push deploys it. There are two ways to do it: a **webhook** that you add to the repository, or the **Square Cloud GitHub App**. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Webhook `deploys.set_webhook(app_id, access_token)` configures GitHub webhook deploys with a GitHub access token (`ghp_...` or `github_pat_...`) and returns the webhook URL to add to your repository. ```python theme={"system"} url = client.apps.deploys.set_webhook(app_id, os.environ["GITHUB_TOKEN"]) print(url) # add it as a webhook in the repository settings ``` Pass `"@"` as the token to remove the webhook. The method then returns `''`. ```python theme={"system"} client.apps.deploys.set_webhook(app_id, "@") ``` An invalid token is 400 `INVALID_ACCESS_TOKEN`. ## GitHub App `deploys.link_github_app(app_id, repository, branch)` links a repository installed through the Square Cloud GitHub App. It needs the `apps:deploy` scope. ```python theme={"system"} repo = client.apps.deploys.link_github_app(app_id, "octocat/hello-world", "main") print(repo["id"], repo["full_name"], repo["branch"]) ``` `deploys.unlink_github_app(app_id)` removes the link. To link another repository or branch, unlink first. ```python theme={"system"} client.apps.deploys.unlink_github_app(app_id) ``` Link and unlink share a limit of **3 calls per 60 seconds**. | Status | Code | When | | - | - | - | | 400 | `GIT_ALREADY_CONFIGURED` | The app already has a linked repository: unlink it first | | 400 | `GIT_NOT_CONFIGURED` | `unlink_github_app` with nothing linked | | 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | The branch does not exist, or its name is over 256 characters | | 403 | `GITHUB_NOT_CONNECTED` | Your account has no GitHub App installation | | 403 | `REPOSITORY_NOT_AVAILABLE` | The GitHub App is not installed on the repository through your GitHub account | | 403 | `REPOSITORY_PERMISSION_REQUIRED` | Your GitHub account has no write access to the repository | | 404 | `REPOSITORY_NOT_FOUND` | The repository does not exist or is not visible | | 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | Another app, of any account, already links this repository and branch. Its id is in `message` only when that app is yours | | 502 | `FAILED_TO_FETCH` | GitHub did not confirm the branch: safe to retry | ## Current configuration `deploys.current(app_id)` returns what is configured: `app` for the GitHub App link, `webhook` for the webhook URL. It returns `{}` when nothing is set. ```python theme={"system"} current = client.apps.deploys.current(app_id) if "app" in current: print(current["app"]["name"], current["app"]["branch"]) # e.g. "octocat/hello-world" "main" if "webhook" in current: print(current["webhook"]) ``` ## Deploy history `deploys.list(app_id)` returns one **timeline per deploy**, each a list of events, oldest event first. Only Git deploys (webhook and GitHub App pushes) are recorded. ```python theme={"system"} for timeline in client.apps.deploys.list(app_id): last = timeline[-1] if timeline else None if last is None: continue print(last["id"], last["state"], last["date"]) if last["state"] == "error": print(last.get("code"), last.get("message")) ``` | Field | Description | | - | - | | `id` | The commit SHA | | `state` | `pending`, `clone`, `commit`, `restarting`, `success` or `error` | | `date` | When the event happened | | `source` | Always `"git"` | | `branch` | On `clone` events | | `files` | On `commit` events: `{ added, removed, modified }` | | `code` / `message` | On `error` events: why the deploy failed (for example `CLONE_FAILED`) | ## Next steps Analytics, DNS, custom domains and cache. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: environment variables Source: https://docs.squarecloud.app/en/sdks/py/environment_variables Read, add, replace and remove the environment variables of a Square Cloud application with client.apps.envs in the Python SDK (squarecloud-api). Environment variables live on `client.apps.envs`. Every method takes the app id first and returns the app's variables as a plain `dict[str, str]`. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. Static apps have no environment variables: every method answers 400 `STATIC_APP_ENV_NOT_SUPPORTED`. A change takes effect on the next [restart](/en/sdks/py/managing_application#start-stop-and-restart). ## Reading the variables ```python theme={"system"} envs = client.apps.envs.get(app_id) print(envs.get("NODE_ENV")) ``` ## Adding or updating variables `envs.set(app_id, envs)` adds the given keys and overwrites the ones that already exist. Other variables are kept. It returns every variable after the change. ```python theme={"system"} envs = client.apps.envs.set(app_id, { "NODE_ENV": "production", "LOG_LEVEL": "info", }) ``` ## Replacing every variable `envs.replace(app_id, envs)` replaces **all** variables with the given set. Keys not in the dict are removed. `{}` clears them all. ```python theme={"system"} client.apps.envs.replace(app_id, {"NODE_ENV": "production"}) ``` ## Removing variables `envs.delete(app_id, keys)` removes the given keys and returns the remaining variables. `keys` is a list (any iterable of strings) or a single key. ```python theme={"system"} remaining = client.apps.envs.delete(app_id, ["LOG_LEVEL"]) # A single key also works remaining = client.apps.envs.delete(app_id, "LOG_LEVEL") ``` ## Limits and errors | Status | Code | When | | - | - | - | | 400 | `STATIC_APP_ENV_NOT_SUPPORTED` | The app is static | | 400 | `INVALID_ENV_CONTENT` | The variables are not a valid object (or, for `delete`, an empty list) | | 400 | `TOO_MANY_ENV_VARS` | The result would have more than 256 variables | | 400 | `ENV_NAME_TOO_LONG` | A key is over 1024 characters | | 400 | `ENV_CONTENT_TOO_LONG` | A value is over 4096 characters | | 400 | `READ_FAILED` | The cluster could not read the variables | ## Next steps Deploy on every push, with a webhook or the GitHub App. The REST endpoints behind these methods. The same actions from the terminal. Set variables from the dashboard, CLI or API and read them at runtime. # Python SDK: errors and retries Source: https://docs.squarecloud.app/en/sdks/py/errors Handle SquareCloudAPIError in squarecloud-api: status, code and message, the SDK's own error codes, retries, timeouts and rate limits. Every API and network failure raises one exception: `SquareCloudAPIError`. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ```python theme={"system"} from squarecloud import SquareCloudAPIError try: client.apps.start(app_id) except SquareCloudAPIError as error: print(error.status, error.code, error.message) print(error.method, error.path) # "POST" "/v2/apps//start" print(error) # POST /v2/apps//start: HTTP 404 APP_NOT_FOUND ``` ## `SquareCloudAPIError` `SquareCloudAPIError` is a subclass of `Exception`. | Attribute | Type | Description | | - | - | - | | `status` | `int` | HTTP status. `0` when no response arrived (network error, timeout, local check) | | `code` | `str` | The API's error code, e.g. `APP_NOT_FOUND`, or one of the SDK's codes | | `message` | `str` | The server's explanation. `''` when the server sent only a code | | `method` | `str` | HTTP method of the failed call | | `path` | `str` | URL path of the failed call, without the query string | | `cause` | `BaseException \| None` | The original exception, for `NETWORK_ERROR`, `TIMEOUT` and invalid JSON (the same as `__cause__`) | `str(error)` is ` : HTTP : `, without `HTTP ` when the status is `0` and without `: ` when the message is empty. Two failures are not wrapped: * An empty or whitespace-only API key raises a `ValueError` in the client constructor. * Local file problems raise an `OSError`: an upload path that cannot be opened, a file that becomes unreadable mid-upload, or a `download_snapshot` destination that cannot be written. ## SDK codes | Status | Code | When | | - | - | - | | 0 | `NETWORK_ERROR` | No response (DNS, connection reset, body cut off). The original exception is in `cause` | | 0 | `TIMEOUT` | A socket operation exceeded the [timeout](/en/sdks/py/client#timeouts) | | 0 | `FILE_TOO_LARGE` | Local check: an upload over 100 MB or a `files.write` over 10 MB. Nothing was sent | | 0 | `INVALID_ID` | Local check: an id that is empty, `.` or `..`. Nothing was sent | | any | `UNKNOWN_ERROR` | A response without a code (such as a proxy error page), with the real `status` and the server's message, or `HTTP ` when there is none. A 2xx body that is not JSON has the message `Invalid JSON in HTTP response` | ## Codes are strings `code` is a plain `str`: the SDK has no enum of codes. The docstring of `SquareCloudAPIError` lists every known API code. `RATE_LIMIT` and `RATE_LIMIT_EXCEEDED` are still listed there, marked deprecated: the API now answers `RATE_LIMITED` for both. The list of API codes grows. **Handle an unknown code by its HTTP status**: ```python theme={"system"} def start(app_id: str): try: client.apps.start(app_id) except SquareCloudAPIError as error: match error.code: case "APP_NOT_FOUND": return None case "CONTAINER_ALREADY_STARTED": return # fine case _: if error.status == 429: return retry_later() if error.status >= 500: return report_outage(error) raise ``` ## API error codes Every other code comes from the API. The [API error reference](/en/api-reference/errors) lists each one with its HTTP status, meaning and fix, and each SDK page lists the codes its methods return most often. Any call can also answer 401 `ACCESS_DENIED` (a bad key), 403 `MISSING_SCOPE` or `RESOURCE_NOT_ALLOWED` (the [limits of the key](/en/sdks/py/client#api-key-and-scopes)), 429 (see [Rate limits](#rate-limits)) or 503 `DATABASE_UNAVAILABLE`. `ai.chat()` errors use lowercase OpenAI codes instead (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...). See [AI](/en/sdks/py/ai#errors). ## Retries The SDK only retries what is safe to repeat, up to `max_retries` times (default `2`, so up to 3 attempts): | Retried | Methods | | - | - | | `NETWORK_ERROR` | `GET` only | | 503 `UPLOAD_BUSY` | Any method | | 503 `ANALYTICS_BUSY` | Any method | | 503 `DATABASE_UNAVAILABLE` | `GET` only | It **never** retries: * `TIMEOUT`; * any **429**: `RATE_LIMITED` can be a block of about 30 minutes, and `KEEP_CALM` is not retried either; * other 5xx; * AI errors. 503 `DATABASE_UNAVAILABLE` can arrive after a mutation was already applied, so the SDK does not retry it outside `GET`. Retry your own idempotent mutations if you need to. The wait before retry `n` (starting at 0) is `min(8 s, 500 ms · 2^n) · U(0.5, 1)`: exponential backoff with 50% to 100% jitter. Set `max_retries=0` to turn retries off. ## Timeouts `timeout` (30 s) applies **per socket operation** (the connect and each read or write), not to the whole request. See [Timeouts](/en/sdks/py/client#timeouts) for the calls with a 120 s floor and the calls with no timeout. A timeout raises `TIMEOUT` with status `0` and is never retried. ## Rate limits Every account has a limit of requests per 60 seconds, set by its plan ([values](/en/api-reference/limitations-and-restrictions)), and some routes have their own: * **429 `RATE_LIMITED`**: the account or API key went over its request budget and is blocked for about 30 minutes, or an IP that keeps sending invalid keys is blocked for a short period. Also the limit of the network endpoints and `account.snapshots`. * **429 `KEEP_CALM`**: too many calls to one route in a short time. The SDK never retries a 429. Slow down, and wait before trying again. ## Next steps Every error code, with its meaning and fix. The request limits of each plan. # Python SDK: manage applications Source: https://docs.squarecloud.app/en/sdks/py/managing_application Fetch, inspect and control your applications with squarecloud-api: details, status, start, stop, restart, logs, metrics, domains, load balancers and deletion. Every method on this page lives on `client.apps` and takes the app id first. An `app_id` can also be the composite `-` of an app shared through a [workspace](/en/sdks/py/workspaces). ```python theme={"system"} import os from squarecloud import SquareCloud client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) app_id = "abc123def456abc123def456" ``` With `AsyncSquareCloud`, every call below is the same with `await` in front. To list your apps, use [`client.account.me()`](/en/sdks/py/client#account): its `applications` list has every app the key can see. ## Getting an application ```python theme={"system"} app = client.apps.get(app_id) print(app["id"], app["name"], app["language"], app["ram"], app["cluster"], app["created_at"]) ``` | Field | Type | Description | | - | - | - | | `id` | `str` | App id | | `name` | `str` | Display name | | `desc` | `str`, optional | Description | | `owner` | `str` | Owner's user id | | `cluster` | `str` | Cluster the app runs on | | `ram` | `int` | Allocated RAM in MB | | `language` | `str` | Runtime language | | `domain` | `str \| None`, optional | Default `.squareweb.app` host; absent or `None` for non-web apps | | `custom` | `str \| None`, optional | Custom domain; absent or `None` when none is set | | `created_at` | `str` | Creation date (ISO 8601) | Optional fields may be missing from the dict: read them with `app.get("domain")`. ## Status `status(app_id)` returns the live state with **formatted** values: ```python theme={"system"} status = client.apps.status(app_id) print(status["status"]) # e.g. "running", "exited" print(status["running"]) # True print(status["cpu"]) # "0.5%" print(status["ram"]) # "120.4MB" (RAM in use) print(status["storage"], status["network"]["total"], status["network"]["now"]) print(status["uptime"]) # Unix ms of the last start, None when stopped ``` Pass `raw=True` to get **numbers** instead (`cpu` in %, `ram` in MB, `network["total"]` and `network["now"]` as `[in, out]` byte pairs): ```python theme={"system"} raw = client.apps.status(app_id, raw=True) print(raw["cpu"], raw["ram"], raw["network"]["total"]) # 0.5 120.4 [1024, 2048] ``` `uptime` is a **timestamp** (when the app started), not a duration. Use `time.time() * 1000 - status["uptime"]` for how long it has been up, in ms. ### Status of every application `status_all()` returns one summary per app the key can see, in a single request. `cpu` and `ram` are only present while the app runs. ```python theme={"system"} for item in client.apps.status_all(): print(item["id"], f"{item['cpu']} {item['ram']}" if item["running"] else "stopped") # Only the apps of one workspace shared = client.apps.status_all(workspace_id=workspace_id) ``` ## Start, stop and restart ```python theme={"system"} client.apps.start(app_id) client.apps.stop(app_id) client.apps.restart(app_id) ``` The server holds these calls open until the container acts, so they wait at least 120 s before timing out. When the platform refuses the action, the call raises a `SquareCloudAPIError` with status **409**, a `code` and an **empty** message (`''`): | Code | Meaning | | - | - | | `CONTAINER_ALREADY_STARTED` | `start` on a running app | | `CONTAINER_ALREADY_STOPPED` | `stop` on a stopped app | | `CONTAINER_TEMPORARILY_SUSPENDED` | The app is suspended | | `CONTAINER_NOT_FOUND` | The container does not exist on the cluster | | `CONTAINER_INSUFFICIENT_DISK_SPACE` | Not enough disk to start | | `CONTAINER_NETWORK_CONFLICT` | Network conflict on the cluster | | `ACTION_FAILED` | The cluster could not perform the action | "Already started" and "already stopped" are errors too. If they mean success for you, handle them: ```python theme={"system"} from squarecloud import SquareCloudAPIError try: client.apps.start(app_id) except SquareCloudAPIError as error: if error.code != "CONTAINER_ALREADY_STARTED": raise ``` ## Logs `logs(app_id)` returns the latest console output as one string (`''` when there is none). ```python theme={"system"} print(client.apps.logs(app_id)) ``` For a live stream of logs, use [Realtime](/en/sdks/py/realtime). ## Metrics `metrics(app_id)` returns the last 24 hours, one point every 5 minutes, **newest first**. ```python theme={"system"} latest = client.apps.metrics(app_id)[0] print(latest["date"], latest["cpu"], latest["ram"], latest["net"]) ``` ## Domains and load balancers `domains()` lists the default and custom hostnames of every app. `load_balancers()` lists the domains shared by several apps, with your plan's limit. ```python theme={"system"} for domain in client.apps.domains(): print(domain["app_id"], domain["hostname"], domain["type"]) # type: "subdomain" | "custom" balancers = client.apps.load_balancers() print(balancers["limit"]) for balancer in balancers["balancers"]: print(balancer["hostname"], [app["id"] for app in balancer["apps"]]) ``` To set a custom domain, see [Network](/en/sdks/py/network#custom-domain). ## Deleting an application ```python theme={"system"} client.apps.delete(app_id) ``` Deletion is permanent. Create a [snapshot](/en/sdks/py/snapshots) first if you may need the files again. ## Next steps Create an app from a zip or send files to one. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: app file manager Source: https://docs.squarecloud.app/en/sdks/py/managing_files List, read, write, move and delete the files of an application with client.apps.files. Content travels as base64, so binary files round-trip byte for byte. The file manager lives on `client.apps.files`. Every method takes the app id first, then a path inside the app. Paths are at most **256 characters**. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Listing a directory `files.list(app_id, path=None)` lists a directory (the app root when `path` is omitted). Unlike other optional modifiers, `path` can be passed by position. ```python theme={"system"} for entry in client.apps.files.list(app_id, "/src"): print(entry["type"], entry["name"], entry.get("size"), entry.get("lastModified")) ``` | Field | Type | Description | | - | - | - | | `name` | `str` | Entry name | | `type` | `"file" \| "directory"` | Entry kind | | `size` | `int`, optional | Size in bytes. Absent on some directory entries | | `lastModified` | `float \| None`, optional | Unix ms (may carry a fraction); `None` when unreadable | A directory that does not exist is 404 `FILE_NOT_FOUND`. A path the file manager does not expose is 403 `BLOCKED_PATH`. ## Reading a file `files.read(app_id, path)` returns the file's content as `bytes`. Files are limited to **10 MB**: a larger one is 413 `FILE_TOO_LARGE`. ```python theme={"system"} import json data = client.apps.files.read(app_id, "/config.json") text = data.decode() print(json.loads(text)) ``` ## Writing a file `files.write(app_id, path, content)` creates or overwrites a file. * A `str` is sent as plain text. * `bytes` are sent as base64, so any binary content round-trips. * Empty content (`''` or `b''`) creates an empty file. ```python theme={"system"} import json import urllib.request # Text client.apps.files.write(app_id, "/config.json", json.dumps({"debug": False})) # Binary with urllib.request.urlopen(image_url) as response: image = response.read() client.apps.files.write(app_id, "/assets/logo.png", image) ``` Content over **10 MB** fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Content over **1 MiB** is sent without a timeout once connected, like an upload. For larger files, use [`apps.commit()`](/en/sdks/py/commit_and_upload). Writing does not restart the app. Call [`apps.restart()`](/en/sdks/py/managing_application#start-stop-and-restart) to apply the change. ## Moving or renaming a file ```python theme={"system"} client.apps.files.move(app_id, "/config.json", "/config.old.json") ``` ## Deleting a file ```python theme={"system"} client.apps.files.delete(app_id, "/config.old.json") ``` ## Errors | Status | Code | When | | - | - | - | | 0 | `FILE_TOO_LARGE` | `write` content over 10 MB (checked locally) | | 400 | `INVALID_PATH` | The path fails validation (traversal, invalid characters, too long), or `move` to the same path | | 400 | `DELETE_FAILED`, `RENAME_FAILED` | The cluster could not delete or rename the file | | 403 | `BLOCKED_PATH` | The path is not exposed by the file manager | | 403 | `PERMISSION_DENIED` | Your workspace role cannot touch a restricted file (such as `.env`) | | 404 | `FILE_NOT_FOUND` | The file or directory does not exist | | 413 | `FILE_TOO_LARGE` | `read` of a file over 10 MB | | 429 | `KEEP_CALM` | More than 10 writes in 5 seconds | See [Errors](/en/sdks/py/errors) for the codes every call can return. ## Next steps Read and change the variables of an app. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: migrating from v4 to v5 Source: https://docs.squarecloud.app/en/sdks/py/migrating_to_v5 Upgrade squarecloud-api from v4 to v5: a sync client with an async variant, plain dicts, methods grouped by resource, one exception class and a method table. v5 is a rewrite. The SDK is now synchronous by default (with an `await` facade), has zero dependencies, groups methods by resource, returns plain dicts (`TypedDict`) and raises a single exception type. It covers all 67 operations of the Square Cloud API. ## At a glance | v4 | v5 | | - | - | | `await client.x(...)`, async only | `client.group.x(...)`, or `await async_client.group.x(...)` | | Frozen dataclasses (`status.ram`) | `TypedDict`, a plain dict (`status['ram']`); unknown fields are kept instead of raising `TypeError` | | `Application` objects (`app.start()`, `app.cache`) | Plain data plus ids: `client.apps.start(app_id)`. There is no cache | | \~25 exception classes (`NotFoundError`, `TooManyRequests`, `FewMemory`, ...) | `SquareCloudAPIError` with `.status`, `.code`, `.message`, `.method`, `.path` (`'/v2/...'`), `.cause` | | `squarecloud.File(path)` | Pass a path, `bytes` or a binary file object directly | | Optional arguments by position | Optional modifiers are keyword-only (`status(id, raw=True)`, `commit(id, file, path=...)`, `databases.create(name, type=, version=, memory=)`) | | Request listeners (`@client.on_request`), capture listeners, `avoid_listener`, `update_cache` | Removed. Use the `squarecloud` [logger](/en/sdks/py/client#logging) (DEBUG) or a custom [`transport=`](/en/sdks/py/client#custom-transport) | | `aiohttp` and `typing-extensions` dependencies | None | | Python `>=3.13,<3.15` | Python `>=3.11`, no upper bound | ## Construction and options | v4 | v5 | | - | - | | `squarecloud.Client(api_key, log_level=...)` | `SquareCloud(api_key, *, base_url=BASE_URL, timeout=30.0, max_retries=2, transport=None, user_agent=...)`, or `AsyncSquareCloud(...)` with the same arguments | | `log_level=` and a colored handler attached on import | `logging.getLogger('squarecloud')` with a `NullHandler`; configure it yourself | | `aiohttp` defaults (5 min per request; 90 s between realtime reads) | `timeout` in seconds per socket operation, with a 120 s floor for held and AI calls; `timeout <= 0` disables every timeout | | No retries | `max_retries` (2) for the safe failures only; 429 is never retried | | Hardcoded `User-Agent` | `user_agent=` replaces the header (default `squarecloud-sdk-py/`) | | A new session per request | `close()` or `with` / `async with` closes the pooled keep-alive connections | ## Method by method | old (v4 `Client`) | new (v5 `SquareCloud`) | notes | | - | - | - | | `user()` | `account.me()['user']` | `me()` also returns `applications` and `databases` | | `all_apps()` | `account.me()['applications']` | | | `app(app_id)` | `apps.get(app_id)` | Now `GET /apps/{id}`: works for workspace ids `'-'` | | `user_snapshots(scope)` | `account.snapshots(*, scope=None)` | `scope` is keyword-only. Items carry the API's `version_id` and signed `url` | | `service_status()` | `service.status()` | | | `upload_app(File(path))` | `apps.create(path)` | Streams from disk; returns `AppCreated` (`domain` is a website's full host; there is no `subdomain`) | | `delete_app(id)` | `apps.delete(id)` | Returns `None` | | `all_apps_status()` | `apps.status_all(*, workspace_id=None)` | Stopped apps are no longer dropped | | `app_status(id)` | `apps.status(id, *, raw=False)` | `raw=True` (keyword-only) returns numbers | | `start_app` / `stop_app` / `restart_app` | `apps.start` / `apps.stop` / `apps.restart` | Return `None` | | `get_logs(id)` | `apps.logs(id)` | Returns the `str` | | `app_metrics(id)` | `apps.metrics(id)` | | | `realtime(id)` (async generator of each `data:` line, JSON-decoded when possible) | `apps.realtime(id)` | Iterator of `{'event', 'data', 'id'}` with the raw `data` text, plus `stream`/`line` on logs and the merged `status` on status events. Reconnects on its own (see Behavior changes); the stream has no read timeout (v4 gave up after 90 s without data), so stop it with `close()` | | `all_domains()` | `apps.domains()` | | | `load_balancers()` | `apps.load_balancers()` | | | `commit(id, File(path))` | `apps.commit(id, file, *, path=None, filename=None)` | Keyword-only `path` = destination directory; `filename` names a non-zip file (`bytes` default to `commit.zip`) | | `github_integration(id, access_token)` | `apps.deploys.set_webhook(id, access_token)` | | | `last_deploys(id)` | `apps.deploys.list(id)` | Events include `source`, `branch`, `files`; a failed deploy ends with `state='error'` plus `code` and `message` | | `current_app_integration(id)` | `apps.deploys.current(id)` | Returns `{'app'?, 'webhook'?}` instead of the webhook string | | `get_app_envs` / `set_app_envs` / `overwrite_app_envs` / `delete_app_envs` | `apps.envs.get` / `set` / `replace` / `delete` | | | `clear_app_envs(id)` | `apps.envs.replace(id, {})` | | | `app_files_list(id, path)` | `apps.files.list(id, path=None)` | Entries are the API's `FileEntry` (no computed `path`/`app_id`). A missing directory raises 404 `FILE_NOT_FOUND` instead of returning `[]`; a blocked one is 403 `BLOCKED_PATH` | | `read_app_file(id, path)` → `BytesIO` | `apps.files.read(id, path)` → `bytes` | Fetched base64-encoded (`?encoding=base64`) and decoded; over 10 MB is 413 `FILE_TOO_LARGE` | | `create_app_file(id, File(...), path)` | `apps.files.write(id, path, content)` | A `str` is sent as text, `bytes` base64-encoded (binary-safe); path sent verbatim (no extra `/`); empty content (`''` or `b''`) creates an empty file | | `move_app_file(id, origin, dest)` | `apps.files.move(id, path, to)` | | | `delete_app_file(id, path)` | `apps.files.delete(id, path)` | | | `snapshot(id)` → `Snapshot` | `apps.snapshots.create(id)` | `{'pending': True}` on 202 instead of raising; then poll `list`, never re-create | | `all_app_snapshots(id)` | `apps.snapshots.list(id)` | Items carry the API's `version_id` and signed download `url`, passed through as sent | | `restore_snapshot('app', id, snapshot_id, version_id)` | `apps.snapshots.restore(id, name, version_id)` | `name` and `version_id` of a `list` item | | `restore_snapshot('database', id, ...)` | `databases.snapshots.restore(id, name, version_id)` | `name` and `version_id` of a `list` item | | `Snapshot.download(path)` | `client.download_snapshot(url, dest)` | Streams the zip itself (v4 wrapped it in another zip) | | `domain_analytics(id, start=, end=, ...)` | `apps.network.analytics(id, start, end, *, country=, ...)` | `start`/`end` are required by the API; the filters are keyword-only | | `network_errors(id, start, end, include_4xx)` / `network_logs` / `network_performance` | `apps.network.errors(id, start, end, *, include_4xx=False)` / `logs` / `performance` | `analytics`, `errors` and `performance` return `None` for a window without data | | `dns_records(id)` | `apps.network.dns(id)` | | | `set_custom_domain(id, custom_domain)` | `apps.network.set_domain(id, domain)` | v4 never sent the body | | `purge_cache(id)` | `apps.network.purge_cache(id)` | | | `link_github_app(id, repository_name, repository_branch)` | `apps.deploys.link_github_app(id, repository, branch)` | Now works with an API key (scope `apps:deploy`); returns the `LinkedRepository` (`{id, full_name, branch}`) instead of the raw dict; 403 `GITHUB_NOT_CONNECTED` without a GitHub App installation | | `unlink_github_app(id)` | `apps.deploys.unlink_github_app(id)` | Returns `None`; 400 `GIT_NOT_CONFIGURED` when nothing is linked | | `create_database(name, memory, type, version=None)` | `databases.create(name, type=, version=, memory=)` | Keyword-only; `version` is required (a major such as `'8'` works) | | `get_database_info(id)` | `databases.get(id)` | | | `edit_database(id, name, memory)` | `databases.update(id, name=, ram=)` | v4 sent `memory`, which the API ignored | | `delete_database` / `start_database` / `stop_database` | `databases.delete` / `start` / `stop` | | | `get_database_status(id)` | `databases.status(id, *, raw=False)` | | | `all_databases_status()` | `databases.status_all()` | | | `database_metrics(id)` | `databases.metrics(id)` | | | `get_database_certificate(id)` → `Certificate` | `databases.certificate(id)` → base64 `str` | `base64.b64decode(...)` gives the PEM | | `reset_database_password(id)` | `databases.reset_credentials(id, 'password')` | Returns the new password | | `reset_database_certificate(id)` | `databases.reset_credentials(id, 'certificate')` | Returns `''` | | `all_database_snapshots(id)` / `database_snapshot(id)` | `databases.snapshots.list(id)` / `create(id)` | Items carry `version_id` and `url`, as for apps | | `create_workspace(name)` | `workspaces.create(name)` | Returns `{id, name}` in one request | | `all_workspaces()` / `get_workspace(id)` | `workspaces.list()` / `workspaces.get(id)` | v4 rewrote each app `id` to the composite `'-'`; v5 returns the API's raw id, so build it yourself: `f"{app['id']}-{workspace['id']}"` | | `delete_workspace` / `leave_workspace` | `workspaces.delete` / `workspaces.leave` | | | `add_member_to_workspace(ws, invite_code, permissions)` | `workspaces.members.add(ws, code, group)` | | | `modify_member_permissions(ws, user_id, permissions)` | `workspaces.members.update(ws, member_id, group)` | | | `remove_member_from_workspace(ws, user_id)` | `workspaces.members.remove(ws, member_id)` | | | `get_invite_code()` | `workspaces.members.invite_code()` | | | `add_app_to_workspace` / `remove_app_from_workspace` | `workspaces.apps.add` / `workspaces.apps.remove` | | | (none) | `ai.chat(request)` | New; `request` is the OpenAI-style body (`{'messages': [...], 'model': ...}`) | | `client.api_key` | Removed | Keep your own reference to the key | | `on_request(endpoint)`, `Application.capture(endpoint)` | Removed | See the listeners row in [At a glance](#at-a-glance) | | `squarecloud.utils.ConfigFile` | Removed | Write the `squarecloud.app` file yourself (`KEY=value` lines) | `Application` methods map to the same calls with the id: `app.logs()` → `client.apps.logs(app.id)`, `app.files_list(path)` → `client.apps.files.list(app.id, path)`, and so on. ## Types Responses are `TypedDict`s in `squarecloud.types`, named as in the JS and Go SDKs: `Account`, `User`, `Plan`, `AppSummary`, `DatabaseSummary`, `App`, `AppCreated`, `StatusListItem`, `RuntimeStats`, `MetricPoint`, `AppDomain`, `LoadBalancers`, `DeployEvent`, `DeployCurrent`, `DeployRepository`, `LinkedRepository`, `EnvVars`, `FileEntry`, `Snapshot`, `SnapshotCreated`, `SnapshotScope`, `AnalyticsFilters`, `NetworkAnalytics`, `NetworkErrors`, `NetworkLog`, `NetworkPerformance`, `DNSRecord`, `Database`, `DatabaseCreated`, `DatabaseType`, `Workspace`, `WorkspaceCreated`, `WorkspaceGroup`, `ServiceStatus`, `ServiceEntry`, `ChatRequest`, `ChatMessage`, `ChatCompletion`, `RealtimeEvent`, `RealtimeStatus`. They replace the v4 `data/*` dataclasses (`UserData`, `StatusData`, `AppData`, ...). `squarecloud.Response` is now the transport's response protocol (see [Custom transport](/en/sdks/py/client#custom-transport)); the v4 `Response` that mutations returned is gone, and they return `None`. ## Errors | v4 | v5 | | - | - | | `AuthenticationFailure` | `e.status == 401` (`ACCESS_DENIED`, also for an expired key) | | `NotFoundError`, `ApplicationNotFound` | `e.status == 404` (`APP_NOT_FOUND`, `WORKSPACE_NOT_FOUND`, ...) | | `BadRequestError` and the `InvalidConfig` family | `e.status == 400`, check `e.code` | | `TooManyRequests` | `e.status == 429` (`RATE_LIMITED`, `KEEP_CALM`) | | `FewMemory` (never raised: the API sends `INSUFFICIENT_MEMORY`) | `e.code == 'INSUFFICIENT_MEMORY'` | | `InvalidDomain` (`REGEX_VALIDATION`, no longer sent) | `e.code == 'INVALID_DOMAIN'` | | `RequestError` for 403/503 | `e.code` in `MISSING_SCOPE`, `RESOURCE_NOT_ALLOWED`, `BLOCKED_PATH`, `UPLOAD_BUSY`, ... | | `aiohttp` exceptions leaking | `e.status == 0`, `e.code` in `NETWORK_ERROR`, `TIMEOUT` (original exception in `e.cause`) | | (none) | `e.status == 0` with `FILE_TOO_LARGE` or `INVALID_ID`: local checks, nothing was sent | | Proxy HTML or a non-JSON body leaking | `UNKNOWN_ERROR` with the real status and the message `HTTP ` (`Invalid JSON in HTTP response` on a 2xx) | `str(e)` is `' : HTTP : '`, without `HTTP ` when the status is `0` and without `: ` when it is empty. `e.message` is `''` when the server sent only a code. ## Behavior changes * Optional modifiers are keyword-only: `account.snapshots(scope=)`, `apps.status_all(workspace_id=)`, `apps.status(id, raw=)`, `databases.status(id, raw=)`, `apps.commit(id, file, path=, filename=)`, `apps.network.errors(..., include_4xx=)`, `apps.network.analytics(...)` filters, `databases.update(id, name=, ram=)` and `databases.create(name, type=, version=, memory=)`. The optional `path` of `apps.files.list` stays positional. * A 2xx `{"status": "error"}` body raises. App and database start/stop refusals are 409 with only a code (`CONTAINER_ALREADY_STARTED`, `ACTION_FAILED`, ...). A 202 `SNAPSHOT_PROCESSING` returns `{'pending': True}` instead of raising: poll `list`, never call `create` again. * Unset optional query values (and `''`) are omitted instead of being sent. * String results are never `None`: `reset_credentials(id, 'certificate')` and a removed webhook return `''`. * `apps.files.write` sends a `str` as text and `bytes` base64-encoded; empty content creates an empty file; content over 1 MiB is sent without a timeout. `apps.files.read` always asks for base64 and returns the decoded `bytes`. * `apps.files.list` of a missing directory raises 404 `FILE_NOT_FOUND`. * 503 `DATABASE_UNAVAILABLE` is retried on `GET` only, since it can fire after a mutation was applied; retrying an idempotent mutation is up to the caller. * The realtime stream yields `{'event', 'data', 'id', ...}` events, reopens at most 3 times in a row at one open per 5.5 s, and raises when an open fails. ## Async v4 was async only. In v5, `SquareCloud` is synchronous and `AsyncSquareCloud` is the `await` facade: the same groups and methods, each call run in `asyncio.to_thread`, so the event loop is never blocked. The realtime stream becomes `async for` (a reader thread feeds the loop); close it with `async with` or `close()`. v4: ```python theme={"system"} client = squarecloud.Client(key) status = await client.app_status(app_id) print(status.ram) async for data in client.realtime(app_id): print(data) ``` v5: ```python theme={"system"} async with squarecloud.AsyncSquareCloud(key) as client: status = await client.apps.status(app_id) print(status['ram']) async with client.apps.realtime(app_id) as stream: async for event in stream: print(event['data']) ``` ## Next steps Install the SDK and create a client. Error class, retries and rate limits. # Python SDK: analytics, DNS and domains Source: https://docs.squarecloud.app/en/sdks/py/network Read edge analytics, errors, request logs and performance of a web application, check DNS, set a custom domain and purge the cache with client.apps.network. `client.apps.network` works on **web apps only**. Every method takes the app id first. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Time windows `analytics`, `errors`, `logs` and `performance` take a `start` and an `end`, each an ISO 8601 string or a `datetime`. A naive `datetime` is local time, converted to UTC. A window is at most **7 days**, and `start` is clamped to the app's creation date. An invalid window is 400 `INVALID_TIME_RANGE`. ```python theme={"system"} from datetime import UTC, datetime, timedelta end = datetime.now(UTC) start = end - timedelta(hours=24) # last 24 h ``` Results are cached in 5-minute buckets. Cache misses of these four methods share a limit of 20 requests per 60 seconds per account: going over it is 429 `RATE_LIMITED`. ## Analytics `network.analytics(app_id, start, end, **filters)` returns traffic totals and breakdowns. It returns `None` for a window with no traffic. ```python theme={"system"} analytics = client.apps.network.analytics(app_id, start, end) if analytics: print(analytics["visits"]) # [{'visits', 'requests', 'bytes', 'date'}] print(analytics["countries"]) # [{'type': 'BR', 'visits', 'requests', 'bytes'}] ``` The breakdowns are `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` and `content_types`. Each bucket has `type`, `visits`, `requests` and `bytes`. ### Filters Filters are keyword arguments and narrow every breakdown. Each takes the exact `type` value of its breakdown: ```python theme={"system"} brazil = client.apps.network.analytics( app_id, start, end, country="BR", path="/api", provider="GOOGLE (15169)", ) ``` | Filter | Example | | - | - | | `country` | `"BR"` (2-letter code) | | `ip` | `"203.0.113.7"` | | `path` | `"/api"` (path prefix) | | `status` | `"404"` | | `os`, `browser`, `protocol`, `bot` | The breakdown's `type` | | `referer` | `"Direct"` means no referer | | `provider` | `"NAME (ASN)"`, e.g. `"GOOGLE (15169)"` | | `content_type` | The breakdown's `type` | An invalid filter is 400 `INVALID_FILTER`. A filter set to `None` or `''` is not sent. ## Errors `network.errors(app_id, start, end, include_4xx=False)` returns the 5xx responses of the window, plus 4xx with `include_4xx=True` (keyword-only). It returns `None` for an empty window. ```python theme={"system"} errors = client.apps.network.errors(app_id, start, end, include_4xx=True) if errors: print(errors["summary"]["total"], errors["summary"]["by_class"]) print(errors["top_paths"]) ``` ## Request logs `network.logs(app_id, start, end)` returns individual requests with client, request and response details. Available on Pro and Enterprise plans (403 `UPGRADE_REQUIRED` otherwise). ```python theme={"system"} for log in client.apps.network.logs(app_id, start, end): print(log["timestamp"], log["request"]["method"], log["request"]["path"], log["response"]["status"]) ``` ## Performance `network.performance(app_id, start, end)` returns latency percentiles (`p50`, `p95`, `p99`, in ms) at the edge and at the origin, by country, by location and for the slowest paths. It returns `None` for an empty window. Available on Pro and Enterprise plans. ```python theme={"system"} performance = client.apps.network.performance(app_id, start, end) if performance: print(performance["summary"]["edge"]["p95"], performance["summary"]["origin"]["p95"]) ``` ## DNS `network.dns(app_id)` returns the DNS records your custom domain needs, with their status. Without a custom domain it is 400 `NO_CUSTOM_DOMAIN`. ```python theme={"system"} for record in client.apps.network.dns(app_id): print(record["type"], record["name"], record["value"], record["status"]) # type: "txt" | "cname" ``` ## Custom domain `network.set_domain(app_id, domain)` attaches a custom domain (Standard plan and up). Pass `"@"` to remove it. ```python theme={"system"} client.apps.network.set_domain(app_id, "www.example.com") # Remove it client.apps.network.set_domain(app_id, "@") ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_DOMAIN` | Not a valid domain name | | 400 | `RESERVED_DOMAIN` | A Square Cloud domain | | 403 | `UPGRADE_REQUIRED` | The plan has no custom domains | | 403 | `LOAD_BALANCER_LIMIT_REACHED` | The plan's limit of apps on this domain was reached | | 409 | `DOMAIN_ALREADY_EXISTS` | The domain belongs to an app of another account | | 502 | `DNS_FAILED` | The edge provider refused the domain | ## Purging the cache `network.purge_cache(app_id)` clears the app's edge cache. It is limited to one purge every 60 seconds (429 `KEEP_CALM`). ```python theme={"system"} client.apps.network.purge_cache(app_id) ``` ## Errors of the analytics methods | Status | Code | When | | - | - | - | | 400 | `INVALID_TIME_RANGE` | `start`/`end` missing, malformed or inverted | | 400 | `INVALID_FILTER` | A filter does not match its format (`analytics`) | | 403 | `UPGRADE_REQUIRED` | `logs` and `performance` outside Pro and Enterprise | | 429 | `RATE_LIMITED` | Shared limit of cache misses reached | | 500 | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | The edge provider failed | | 503 | `ANALYTICS_BUSY` | Edge analytics are busy: retried automatically | ## Next steps Stream live logs and status. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: live logs and status Source: https://docs.squarecloud.app/en/sdks/py/realtime Stream a Square Cloud app's live logs, status and system events with client.apps.realtime() in the Python SDK, sync or async, with automatic reconnection. `client.apps.realtime(app_id)` opens a live stream of an app's logs, status and system events. With `SquareCloud` it is an **iterator** consumed with `for`; with `AsyncSquareCloud` it is an **async iterator** consumed with `async for`. Use it in a `with` / `async with` block so leaving the block closes the connection. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ```python theme={"system"} with client.apps.realtime(app_id) as stream: for event in stream: if event["event"] == "logs": print(event["stream"], event["line"]) # "stdout" | "stderr" elif event["event"] == "status": print(event["status"].get("cpu"), event["status"].get("ram")) # always the full, merged state else: print(event["event"], event["data"]) # "system" or "error" ``` ```python theme={"system"} async with client.apps.realtime(app_id) as stream: # no await: realtime() is not a coroutine async for event in stream: if event["event"] == "logs": print(event["stream"], event["line"]) # "stdout" | "stderr" elif event["event"] == "status": print(event["status"].get("cpu"), event["status"].get("ram")) # always the full, merged state else: print(event["event"], event["data"]) # "system" or "error" ``` With `AsyncSquareCloud`, `apps.realtime(app_id)` returns an `AsyncRealtime` directly: do **not** `await` it. A background reader thread feeds the events to your event loop, so no executor thread is held while you wait. ## Events Every event is a dict with `event`, `data` (the raw frame text) and `id` (`None` when the frame has none). | `event` | Extra fields | Description | | - | - | - | | `logs` | `stream`, `line` | One log line. The first character of `data` tells the stream (`\u0001` stdout, `\u0002` stderr); the SDK strips it into `line` and sets `stream` to `"stdout"` or `"stderr"` | | `status` | `status` | Live container metrics. The first frame is complete and the next ones only carry what changed: the SDK merges them, so `status` is always the full state | | `system` | | Connection events such as `REALTIME_CONNECTING \| `, `REALTIME_TIMEOUT` or `REALTIME_DISCONNECTED` | | `error` | | An error code such as `CONTAINER_NOT_FOUND` | | `message` | | A frame without an `event` name | ### The `status` object | Field | Description | | - | - | | `cpu` | CPU usage (%) | | `cpuLimit` | Number of CPU cores allocated | | `ram` | `[usedMB, limitMB]` | | `status` | Container state, e.g. `running` | | `netIO` | Network `{ i, o }` totals, with `new` for the latest interval | | `bIO` | Disk `{ i, o }` totals | | `uptime` | Unix ms of the container start | ## Ending the stream The loop ends on its own when: * the server closes the connection cleanly (each connection lasts up to **10 minutes**); * the server sends `REALTIME_DISCONNECTED`; * you `break` out of the loop (then leave the `with` block, which closes the connection); * you call `stream.close()`, from any thread, even while the loop waits for data or for a reconnection (the loop just ends, it does not raise). `close()` is synchronous on both `Realtime` and `AsyncRealtime`. To keep watching past 10 minutes, open a new stream when the loop ends. ```python theme={"system"} import threading stream = client.apps.realtime(app_id) threading.Timer(60, stream.close).start() # stop after one minute for event in stream: print(event["event"], event["data"]) ``` ## Reconnection A dropped connection, or the server handing reconnection to the client (`REALTIME_RECONNECT`), reopens the stream on its own: * up to **3 times in a row**; any `logs` or `status` event resets the count; * each reopen at least **5.5 s** after the previous open, to stay under the API's pace of one open per 5 seconds per app. Past 3 failed reconnections, the loop raises a `SquareCloudAPIError` with `NETWORK_ERROR`. Each open is a `GET`, so a network error while opening is also [retried](/en/sdks/py/errors#retries) up to `max_retries` times; an open that still fails raises. ## Limits and errors * **5** concurrent connections per account and **30** per app, across all users. Going over is 429 `REALTIME_MAX_CONNECTIONS` or `REALTIME_MAX_CONNECTIONS_APP`. * The HTTP status is checked before streaming, so these errors (and 404 for an unknown app) raise on the first iteration. * The timeout only covers the open, until the response headers arrive. The stream itself has no timeout: a half-open connection (a laptop resuming from sleep) waits until you call `close()`. ## Next steps Back up and restore apps and databases. The REST endpoint behind this stream. The same stream from the terminal. # Python SDK: snapshots and backups Source: https://docs.squarecloud.app/en/sdks/py/snapshots List, create and restore app and database snapshots, list every snapshot of the account, and download a snapshot file with client.download_snapshot(). Snapshots are backups of an app's or database's storage. Apps and databases share the same three methods: * `client.apps.snapshots`: `list(app_id)`, `create(app_id)`, `restore(app_id, name, version_id)` * `client.databases.snapshots`: `list(database_id)`, `create(database_id)`, `restore(database_id, name, version_id)` How many snapshots you can create per day depends on your plan (see [Limits](#limits)). Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them. ## Listing snapshots ```python theme={"system"} for snapshot in client.apps.snapshots.list(app_id): print(snapshot["name"], snapshot["version_id"], snapshot["size"], snapshot["modified"]) ``` | Field | Description | | - | - | | `name` | The snapshot id that `restore` takes | | `version_id` | The version that `restore` takes | | `size` | Size in bytes | | `modified` | When it was taken | | `url` | Signed download URL, **valid for 30 days** | | `key` | Signed query string of the URL | | `runtime` | Database engine or app language (`None` on old snapshots) | | `origin` | `"automatic"`, `"manual"` or `None` | ## Creating a snapshot `create()` waits for the snapshot (at least 120 s before timing out). A large snapshot may not finish in time: the API then answers 202 and the SDK returns `{'pending': True}`. The snapshot keeps generating and shows up in `list()` on its own, usually within 2 minutes. Otherwise it returns `{'pending': False, 'url': ..., 'key': ...}`. ```python theme={"system"} result = client.apps.snapshots.create(app_id) if result["pending"]: # Poll list() later. Do not call create() again: that starts a new snapshot. pass else: print(result["url"]) # signed download URL, valid 30 days ``` Never call `create()` again to check on a pending snapshot: it starts a new one and counts against the plan's daily snapshot quota. Poll `list()` instead. ## Restoring a snapshot `restore(id, name, version_id)` takes the `name` and `version_id` of a listed snapshot. ```python theme={"system"} latest = client.apps.snapshots.list(app_id)[0] client.apps.snapshots.restore(app_id, latest["name"], latest["version_id"]) ``` | Status | Code | When | | - | - | - | | 400 | `MISSING_PARAMETERS` | `name` or `version_id` is missing | | 400 | `INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID` | Not a `name`/`version_id` from the listing | | 400 | `SNAPSHOT_DATABASE_MISMATCH` | The snapshot's engine does not match the database's type (databases only) | | 404 | `SNAPSHOT_NOT_FOUND` | No snapshot with that name and version | | 404 | `SNAPSHOT_RESTORE_FAILED` | The restore could not be dispatched (the usual failure) | | 413 | `PAYLOAD_TOO_LARGE` | The snapshot is too large to restore | ## Downloading a snapshot `client.download_snapshot(url, dest)` streams a snapshot file from its signed `url` (from `list()` or `create()`) to disk and returns the path it wrote. It does **not** call the API: the API key is never sent to the storage host. Nothing is buffered in memory. * `dest` is a file path, or a directory to keep the remote file name. A path ending in `/` is created as a directory. * The data goes to a `.part` file that is renamed when complete, so a failed download never overwrites an earlier file. * There is no timeout for the whole download: `timeout` bounds each read. ```python theme={"system"} latest = client.apps.snapshots.list(app_id)[0] path = client.download_snapshot(latest["url"], "backup.zip") print("saved to", path) # Or into a directory, keeping the remote name client.download_snapshot(latest["url"], "backups/") ``` With `AsyncSquareCloud`, it is `await client.download_snapshot(url, dest)`. An expired or invalid URL raises a `SquareCloudAPIError` with the storage host's HTTP status and `UNKNOWN_ERROR`. A destination that cannot be written raises an `OSError`. ## Account snapshots `client.account.snapshots(scope=None)` lists every snapshot of the account, optionally only `"applications"` or `"databases"` (keyword-only). It needs an active plan and shares the network endpoints' rate limit (429 `RATE_LIMITED`). ```python theme={"system"} everything = client.account.snapshots() databases = client.account.snapshots(scope="databases") ``` | Status | Code | When | | - | - | - | | 400 | `INVALID_SCOPE` | `scope` is not `applications` or `databases` | | 402 | `UPGRADE_REQUIRED` | The account has no active plan | | 429 | `RATE_LIMITED` | Rate limit reached | ## Limits * `create()` is limited to one call per 180 seconds and to a daily quota that depends on the plan: going over the quota is 429 `DAILY_SNAPSHOTS_LIMIT_REACHED`. * While a restore runs, deleting the app or starting the database is 403 `RESTORE_IN_PROGRESS`. ## Next steps Create and manage databases. The REST endpoints behind these methods. The same actions from the terminal. # Python SDK: workspaces and members Source: https://docs.squarecloud.app/en/sdks/py/workspaces Create and manage workspaces, invite members, set their roles and share applications with client.workspaces. Act on a shared app with its composite id. A workspace shares apps with other Square Cloud users, each with a role. `client.workspaces` manages workspaces, `client.workspaces.members` their members and `client.workspaces.apps` the shared apps. Creating workspaces needs a Standard, Pro or Enterprise plan. Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `workspace_id` is the id of a workspace (`workspaces.list()` lists them), `app_id` the id of one of your apps and `member_id` the `id` of a member. ## Workspaces ```python theme={"system"} created = client.workspaces.create("My team") workspace_id = created["id"] workspaces = client.workspaces.list() workspace = client.workspaces.get(workspace_id) print(workspace["name"], workspace["owner"], workspace["createdAt"]) for member in workspace["members"]: print(member["id"], member["name"], member["group"], member["joinedAt"]) for app in workspace["applications"]: print(app["id"], app["name"], app["lang"], app["ram"]) client.workspaces.leave(workspace_id) # as a member client.workspaces.delete(workspace_id) # as the owner ``` | Field | Description | | - | - | | `id` | 32 hex characters (older workspaces keep a 40-character id) | | `name` | Workspace name (1 to 32 characters) | | `owner` | Owner's user id | | `members` | `{ id, name, group, joinedAt }`. `name` is `None` when it cannot be resolved (a deleted account) | | `applications` | `{ id, name, desc, ram, lang, domain?, custom? }` | | `createdAt` | Creation date | The owner cannot leave (400 `CANNOT_LEAVE_OWNER`): delete the workspace instead. ## Members Adding a member takes an **invite code** that the member generates with `members.invite_code()`. The code is valid for **5 minutes**. ```python theme={"system"} # The member runs this and sends you the code code = client.workspaces.members.invite_code() # The owner adds them with a role client.workspaces.members.add(workspace_id, code, "maintain") client.workspaces.members.update(workspace_id, member_id, "view") client.workspaces.members.remove(workspace_id, member_id) ``` Roles (`group`): `view`, `manager`, `maintain` and `admin`. Calling a method that your role does not allow is 403 `PERMISSION_DENIED`. ## Shared applications ```python theme={"system"} client.workspaces.apps.add(workspace_id, app_id) client.workspaces.apps.remove(workspace_id, app_id) ``` A workspace can hold up to 100 apps (400 `APPLICATIONS_LIMIT_REACHED`). ### Acting on a shared app To act on an app shared with you, pass the composite id `-` to any `client.apps` method. `workspaces.get()` and `workspaces.list()` return raw ids, so build it yourself: ```python theme={"system"} workspace = client.workspaces.get(workspace_id) for app in workspace["applications"]: status = client.apps.status(f"{app['id']}-{workspace['id']}") print(app["name"], status["running"]) # Status of every app of the workspace in one request statuses = client.apps.status_all(workspace_id=workspace_id) ``` ## Errors Workspace routes send the ids in the request body, so an empty id is 400 `INVALID_ID` from the server (not a local error). The exception is `workspaces.get()`, whose id is in the URL path: an empty id fails locally there. | Status | Code | When | | - | - | - | | 400 | `INVALID_NAME` | The name is not 1 to 32 characters | | 400 | `WORKSPACE_LIMIT_REACHED`, `MEMBERS_LIMIT_REACHED`, `APPLICATIONS_LIMIT_REACHED` | A plan or workspace limit was reached | | 400 | `INVALID_CODE` | The invite code is missing, malformed or expired | | 400 | `INVALID_GROUP` | The role is not `view`, `manager`, `maintain` or `admin` | | 400 | `CANNOT_INVITE_OWNER`, `CANNOT_EDIT_OWNER`, `CANNOT_LEAVE_OWNER` | The action does not apply to the owner | | 400 | `MEMBER_ALREADY_ADDED`, `APP_ALREADY_IN_WORKSPACE` | Already in the workspace | | 403 | `UPGRADE_REQUIRED` | The plan cannot create workspaces | | 403 | `PERMISSION_DENIED` | Your role does not allow the action | | 404 | `WORKSPACE_NOT_FOUND`, `MEMBER_NOT_FOUND`, `APP_NOT_FOUND` | Not found | ## Next steps Chat completions through the AI Gateway. The REST endpoints behind these methods. The same actions from the terminal. # OpenAI-compatible AI Gateway (beta) Source: https://docs.squarecloud.app/en/api-reference/ai-gateway POST https://api.squarecloud.app/v2/ai/chat/completions Use Square Cloud's hosted cubic model in your own products through the OpenAI-compatible POST /v2/ai/chat/completions, with tool calling and web search. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `ai:chat` [scope](/en/api-reference/authentication#scopes). The AI Gateway lets you use Square Cloud's hosted AI model inside your **own** products (chatbots, assistants, automations) through an **OpenAI-compatible** chat completions endpoint. If your code already speaks the OpenAI API, it speaks the AI Gateway too: point the SDK at our base URL, use your account API key, and set the model to `cubic`. The AI Gateway is in **beta with free early access**: during the beta there is no extra charge, and usage counts only against the gateway's own token limits. Limits and plan availability may change when the beta ends. ## How to connect * **Base URL:** `https://api.squarecloud.app/v2/ai` * **API key:** your account API key (the same one used by the Square Cloud API and CLI, from the [account page](https://squarecloud.app/account)). The `Authorization` header is accepted with or without the `Bearer ` prefix. * **Model:** `cubic`, Square Cloud's hosted model, the same one powering the dashboard AI assistant. ## Plans and limits Every request bills its real tokens against the gateway's **own token limits**: a daily limit, reset at 00:00 UTC, and a weekly limit of 4x the daily one, reset on Monday at 00:00 UTC. They are separate from the dashboard AI assistant's limits, so gateway traffic never uses up the assistant's allowance, and vice versa. Standard and Pro also have a daily request ceiling, and every plan has a daily fair-use allowance on the gateway, sized for moderate use (a guard for unattended keys, based on what the requests cost to serve); both reset at 00:00 UTC. | Plan | Tokens per day | Tokens per week | Requests per day | Fair-use allowance | Context window | Max output | Concurrent requests | Pacing between requests | | - | - | - | - | - | - | - | - | - | | Standard | 2.5M | 10M | 1,000 | base | 16,384 tokens | 4,096 | 1 | 5s | | Pro | 5M | 20M | 5,000 | 2x base | 24,576 tokens | 6,144 | 1 | 2s | | Enterprise | 10M to 20M | 40M to 80M | unlimited | 5x base | 32,768 tokens | 8,192 | 2 | none | Every Standard plan size has the same gateway limits, and so does every Pro size. Enterprise token limits grow with the plan: 10M tokens per day on Enterprise 32, 12M on Enterprise 48, 14M on Enterprise 64, 16M on Enterprise 96 and 20M on Enterprise 128 and above, with 4x that per week. Hobby plans (and accounts without a plan) do not have AI Gateway access: upgrading to Standard or above enables it. ## Request contract Accepted for SDK compatibility; the gateway always answers as `cubic`. OpenAI-style messages with roles `system`, `user`, `assistant` and `tool`. Content must be a **string**: this endpoint is text only, so a multi-part array (`image_url`, `input_audio`, `file`) is rejected with `400 multimodal_not_supported`. Up to **100 messages** per request. OpenAI's current name for the answer's token limit, the one the OpenAI SDKs send. It wins over `max_tokens` when both are present. Silently clamped to your plan's output ceiling. The legacy name, still accepted. Silently clamped to your plan's output ceiling. From 0 to 2. Function calling in the standard OpenAI format, up to **32 tool definitions**. Tool calls come back as `finish_reason: "tool_calls"`, and you send results back as `role: "tool"` messages. Standard OpenAI `tool_choice` values. Unknown parameters are ignored, with two deliberate exceptions: `audio` and a `modalities` value other than `["text"]` are **rejected** rather than ignored, so a request for spoken output never comes back as silent text. **Text in, text out.** Images, audio and files are not accepted on any plan, and this is a product decision rather than a temporary gap. Send text and read text back. **Not supported yet:** streaming (`stream: true` returns `400 stream_not_supported`). ### Built-in web search The model decides on its own to search the web when the conversation asks for current or external information. Searches run server-side, and only the final answer is returned, citing result URLs. If you declare your own tool named `web_search`, yours replaces the built-in one. ```javascript JavaScript (OpenAI SDK) theme={"system"} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.squarecloud.app/v2/ai", apiKey: process.env.SQUARECLOUD_API_KEY, }); const completion = await client.chat.completions.create({ model: "cubic", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Explain what Square Cloud is in one sentence." }, ], }); console.log(completion.choices[0].message.content); ``` ```python Python (OpenAI SDK) theme={"system"} from openai import OpenAI client = OpenAI( base_url="https://api.squarecloud.app/v2/ai", api_key="YOUR_API_KEY", ) completion = client.chat.completions.create( model="cubic", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain what Square Cloud is in one sentence."}, ], ) print(completion.choices[0].message.content) ``` ```bash cURL theme={"system"} curl --request POST \ --url https://api.squarecloud.app/v2/ai/chat/completions \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "model": "cubic", "messages": [ { "role": "user", "content": "Explain what Square Cloud is in one sentence." } ] }' ``` ```json theme={"system"} { "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b", "object": "chat.completion", "created": 1754179200, "model": "cubic", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 28, "completion_tokens": 24, "total_tokens": 52 } } ``` ## Errors Every error uses the OpenAI shape `{ "error": { "message", "type", "param", "code" } }`, including authentication, scope, rate-limit, invalid-body, `500` and `503` errors, and the `code` is always lowercase. | Status | Code | What it means / what to do | | - | - | - | | 401 | `access_denied` | The API key is missing, invalid, revoked or expired. | | 403 | `upgrade_required` | The plan has no AI Gateway access (Hobby or no plan). Upgrade to Standard or above. | | 403 | `missing_scope` | The API key lacks the scope this endpoint needs. | | 403 | `resource_not_allowed` | The API key is restricted to resources that don't cover this request. | | 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Malformed request body: fix the flagged field. | | 400 | `stream_not_supported` | Remove `stream: true`; streaming is not available yet. | | 400 | `multimodal_not_supported` | The endpoint is text only. Send each message's `content` as a string, and drop `audio` or any `modalities` beyond `["text"]`. | | 400 | `context_length_exceeded` | Messages plus tool definitions exceed the plan's context window. Shorten the history or upgrade. | | 400 | `invalid_request` | The model backend refused the request: almost always a tool-calling protocol mistake (a `tool` message that does not answer a preceding `tool_calls`, duplicate call ids). | | 413 | `payload_too_large` | The request body is larger than this endpoint accepts. Shorten the history. | | 429 | `concurrent_limit_reached` | A request is already in flight; wait for it to finish (Enterprise allows 2 at once). | | 429 | `rate_limit_exceeded` | Requests sent faster than the plan's pacing; add the delay client-side. | | 429 | `daily_request_limit_reached` | The plan's daily request ceiling is reached (Standard 1,000 / Pro 5,000); it resets at 00:00 UTC. Enterprise has no ceiling. | | 429 | `daily_spend_limit_reached` | The plan's daily fair-use allowance on the gateway is reached; it resets at 00:00 UTC. Pro has 2x and Enterprise 5x the base allowance. | | 429 | `daily_limit_reached` | The gateway's daily token limit is spent; it resets at 00:00 UTC. An upgrade raises it. | | 429 | `weekly_limit_reached` | The gateway's weekly token limit (4x the daily one) is spent; it resets on Monday at 00:00 UTC. An upgrade raises it. | | 429 | `rate_limited` | The request limit of the account or API key was reached; wait and retry. | | 500 | `internal_server_error` | Unexpected failure. Retry. | | 503 | `server_overloaded` | Capacity is momentarily full, or the request passed the 90-second total deadline; retry shortly (OpenAI SDKs retry this automatically). | | 503 | `daily_capacity_reached` | The AI Gateway's shared daily capacity, for the whole platform, is used up. It resets at 00:00 UTC; retrying before that doesn't help. | | 503 | `database_unavailable` | The platform is briefly unavailable. Retry in a few seconds. | Three of these look alike but mean different things: * `429 daily_spend_limit_reached`: the daily limit of **your** key, set by your plan. * `503 daily_capacity_reached`: the daily capacity of the **platform** for the gateway, shared by every customer. * `503 server_overloaded`: a momentary overload, or a request that took longer than 90 seconds in total (provider queue, retries and search rounds included). Retry in a few seconds. ## Retries Most `429` and `503` answers tell your client when to try again, through headers the OpenAI SDKs read: | Code | Headers | What to expect | | - | - | - | | `429 rate_limit_exceeded` | `Retry-After` with the plan's pacing between requests, in seconds (Standard 5, Pro 2) | The OpenAI SDKs wait and retry on their own. | | `429 daily_request_limit_reached`, `daily_spend_limit_reached`, `daily_limit_reached` and `503 daily_capacity_reached` | `Retry-After` with the seconds until 00:00 UTC, and `x-should-retry: false` | The SDK doesn't retry; wait for the reset. | | `429 weekly_limit_reached` | `Retry-After` with the seconds until Monday at 00:00 UTC, and `x-should-retry: false` | The SDK doesn't retry; wait for the reset. | | `503 server_overloaded` | `Retry-After: 2` | The OpenAI SDKs wait and retry on their own. | | `429 concurrent_limit_reached` | No `Retry-After` | Retry when your request in flight finishes, or let the SDK's default retries handle it. | The OpenAI SDKs honor a `Retry-After` of up to 60 seconds. A longer wait falls back to the SDK's own backoff, unless the answer also carries `x-should-retry: false`, which turns its automatic retries off. Without an OpenAI SDK, read `Retry-After` yourself and wait that many seconds before the next request. ## Frequently asked questions No, the API is stateless, exactly like OpenAI's: send the conversation history in `messages` on every request. `cubic`, Square Cloud's hosted model. There is no model list to choose from; the `model` field is accepted for SDK compatibility. Yes, that is the main use case. It is a normal HTTPS API, so it works from anywhere. No. The gateway has its own daily and weekly token limits, separate from the dashboard assistant's, so heavy gateway usage never uses up the assistant's allowance, and vice versa. ## Related * SDKs: [`api.ai.chat()`](/en/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/en/sdks/py/ai) (Python), [`c.AI.Chat()`](/en/sdks/go/ai) (Go) # Get database TLS certificate Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/credentials/get_certificate GET https://api.squarecloud.app/v2/databases/{database_id}/credentials/certificate Get a database's TLS file with GET /v2/databases/{database_id}/credentials/certificate: a base64 PEM with the private key and certificate. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:credentials` [scope](/en/api-reference/authentication#scopes). Returns the TLS file the database uses for encrypted connections, base64-encoded. Once decoded, it is a PEM with the private key followed by the certificate, ready to be written to a `.pem` file. Managed MongoDB, MySQL and PostgreSQL databases each ship with their own certificate; check your driver's TLS options to see whether it needs one. The database must be running when you call this, if it is stopped, [start it](/en/api-reference/endpoint/databases/start) first. To rotate the certificate instead of just reading it, use [Reset Credentials](/en/api-reference/endpoint/databases/credentials/reset) with `reset: "certificate"`, then re-fetch it here. ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The PEM (private key followed by the certificate), encoded in base64. ```json theme={"system"} { "status": "success", "response": { "certificate": "CERTIFICATE_IN_BASE_64_FORMAT" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_NOT_RUNNING` | 400 | The database is stopped; start it before reading the certificate. | | `READ_FAILED` | 400 | The certificate file could not be read from the cluster. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | ## Related * CLI: [`squarecloud db credentials certificate`](/en/cli-reference/databases#squarecloud-db-credentials-certificate) * SDKs: [`api.databases.certificate()`](/en/sdks/js/databases) (JavaScript), [`client.databases.certificate()`](/en/sdks/py/databases) (Python), [`c.Databases.Certificate()`](/en/sdks/go/databases) (Go) # Reset database password or certificate Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/credentials/reset POST https://api.squarecloud.app/v2/databases/{database_id}/credentials/reset Rotate a database's password or TLS certificate with POST /v2/databases/{database_id}/credentials/reset. A new password is shown only once. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:credentials` [scope](/en/api-reference/authentication#scopes). Rotates either the access password or the TLS certificate of a database, without recreating it or changing its connection URL structure. Use this if a credential leaked or as part of a routine rotation policy. The database must be running to reset either credential. Resetting `password` returns the new password once in the response body, it is not shown again, so store it immediately. Resetting `certificate` returns a plain success, fetch the new certificate afterward via [Get Certificate](/en/api-reference/endpoint/databases/credentials/get_certificate). After either reset, existing client connections using the old credential will need to reconnect. Rate limited to 1 reset every 3 seconds per user. ## Parameters The ID of the database. The credential you want to reset, password or certificate. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ### If it's a password reset The contents of the response. The new generated password. ```json theme={"system"} { "status":"success", "response":{ "password":"f3T1hdskMkchMwK6Hxqinoyb" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_RESET_TYPE` | 400 | `reset` was not `"password"` or `"certificate"`. | | `DATABASE_NOT_RUNNING` | 400 | The database is stopped; start it before resetting credentials. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `RESET_FAILED` | 500 | The credential rotation was rejected by the cluster. | ## Related * CLI: [`squarecloud db credentials reset`](/en/cli-reference/databases#squarecloud-db-credentials-reset) * SDKs: [`api.databases.resetCredentials()`](/en/sdks/js/databases) (JavaScript), [`client.databases.reset_credentials()`](/en/sdks/py/databases) (Python), [`c.Databases.ResetCredentials()`](/en/sdks/go/databases) (Go) # Delete database Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/delete DELETE https://api.squarecloud.app/v2/databases/{database_id} Permanently delete a database and release its DNS record with DELETE /v2/databases/{database_id}. There is no confirmation, so take a snapshot first. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `databases:write` [scope](/en/api-reference/authentication#scopes). Permanently removes the database container and releases its public DNS record (`square-cloud-db-.squareweb.app`). This is destructive and immediate: there is no confirmation step, and the connection URL stops resolving as soon as the DNS record is released. If you need the data afterward, take a [Create Snapshot](/en/api-reference/endpoint/databases/snapshots/create) before deleting. The request is rejected while a snapshot restore is in progress on the database. Rate limited to 1 deletion every 3 seconds per user. ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `RESTORE_IN_PROGRESS` | 403 | A snapshot restore is currently running for this database; wait for it to finish. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `DELETE_FAILED` | 404 | The cluster rejected the delete operation. | ## Related * CLI: [`squarecloud db delete`](/en/cli-reference/databases#squarecloud-db-delete) * SDKs: [`api.databases.delete()`](/en/sdks/js/databases) (JavaScript), [`client.databases.delete()`](/en/sdks/py/databases) (Python), [`c.Databases.Delete()`](/en/sdks/go/databases) (Go) # Create a database snapshot Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/snapshots/create POST https://api.squarecloud.app/v2/databases/{database_id}/snapshots Back up a database's data with POST /v2/databases/{database_id}/snapshots. Returns a download URL valid for 30 days, or 202 while it keeps generating. Each account can perform up to (RAM / 256) \* 2 snapshots every 24 hours. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:write` [scope](/en/api-reference/authentication#scopes). Captures a point-in-time backup of the database's data and uploads it to Square Cloud's snapshot storage, returning a signed download URL valid for 30 days. Use it before a risky migration, a manual [Restore Snapshot](/en/api-reference/endpoint/databases/snapshots/restore), or on a schedule for disaster recovery. Once created, snapshots also show up in [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list). ## Parameters The ID of the database. ## Soft deadline behavior This route follows a **soft deadline** model: it no longer always responds synchronously. * If the snapshot finishes within **\~90 seconds**, the route responds with `200 success` and a signed download URL (valid for 30 days), exactly as before. * If the snapshot takes longer than **\~90 seconds** to generate, the route responds **immediately** with `202` and the code `SNAPSHOT_PROCESSING`. **This is not a failure.** The snapshot keeps generating in the background and will appear in the [snapshot listing](/en/api-reference/endpoint/databases/snapshots/list) on its own, typically within \~2 minutes. This is expected behavior for large databases. Do not use this `POST` endpoint as a polling mechanism. To check whether a `SNAPSHOT_PROCESSING` snapshot has completed, use the [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list) (`GET`) endpoint: **not** another `POST`. Re-posting after the snapshot has finished starts a brand-new snapshot from scratch. The client should branch on the response as follows: | Response | Meaning | What to do | | - | - | - | | `status === "success"` | Snapshot is ready. | Use the `url` to download it. | | `status === "error"` and `code === "SNAPSHOT_PROCESSING"` | Snapshot is still generating. | Wait \~2 minutes, then confirm via [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list) (`GET`). Do **not** re-`POST`. | | `status === "error"` with any other `code` | Actual failure. | Handle the error (see below). | ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. Present only when `status` is `success`. The URL to download the snapshot of your application. The key to download the snapshot of your application. Returned when the snapshot exceeds the \~90 second soft deadline. The snapshot is still being generated in the background and will appear in the snapshot listing on its own, typically within \~2 minutes. Not an error: wait and confirm via the `GET` listing endpoint. ## Errors A snapshot request can be rejected with `429 Too Many Requests`. Use the `code` field to tell the two cases apart: Short-term cooldown: you hit the per-user (1 request / 5s) or per-database (1 request / 180s) limit. Back off and retry shortly. Daily quota reached: the account used up its plan's daily snapshot allowance ((RAM / 256) × 2 per 24h). The quota frees up as the rolling 24-hour window advances; for a higher daily allowance, upgrade the plan. ```json 200 Success theme={"system"} { "status":"success", "response":{ "url":"https://snapshots.squarecloud.app/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D", "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D" } } ``` ```json 202 SNAPSHOT_PROCESSING theme={"system"} { "status": "error", "code": "SNAPSHOT_PROCESSING" } ``` ```json 429 KEEP_CALM theme={"system"} { "status": "error", "code": "KEEP_CALM", "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s" } ``` ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={"system"} { "status": "error", "code": "DAILY_SNAPSHOTS_LIMIT_REACHED", "message": "You are being rate limited for daily snapshots. 8r/24h" } ``` ## Related * CLI: [`squarecloud db snapshot create`](/en/cli-reference/snapshots#squarecloud-db-snapshot-create) * SDKs: [`api.databases.snapshots.create()`](/en/sdks/js/databases) (JavaScript), [`client.databases.snapshots.create()`](/en/sdks/py/databases) (Python), [`c.Databases.Snapshots.Create()`](/en/sdks/go/databases) (Go) # List database snapshots Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/snapshots/list GET https://api.squarecloud.app/v2/databases/{database_id}/snapshots List a database's snapshots, newest first, with GET /v2/databases/{database_id}/snapshots: size, date, download URL and the IDs to restore each one. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:read` [scope](/en/api-reference/authentication#scopes). Lists every snapshot stored for a database, most recent first, with size and last-modified date for each. Use it to build a restore picker in a dashboard, or to poll after a [Create Snapshot](/en/api-reference/endpoint/databases/snapshots/create) call returned `202 SNAPSHOT_PROCESSING` and confirm the file has landed. Each item carries a signed download `url`, valid for 30 days, and a `version_id` to pass as `versionId` when restoring. Responses are cached for 30 minutes per user and database, so a snapshot that just finished generating may take a short while to show up here. To restore one of these snapshots, see [Restore Snapshot](/en/api-reference/endpoint/databases/snapshots/restore). ## Parameters The ID of the database. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The snapshot's name: the database ID suffixed with `_` and, on newer snapshots, `_`. Pass it unchanged as `snapshotId` when restoring. Size of the backup in bytes. Date of the last modification of the backup. The signed query string of the download URL. The snapshot's version. Pass it as `versionId` when restoring. A signed URL that downloads the snapshot, valid for 30 days. Runtime the snapshot was taken from: the application's language (`javascript`, `python`, `rust`...) or the database engine (`mongo`, `mysql`, `postgres`, `redis`). `null` on snapshots taken before this field existed. How the snapshot was created: `manual` (requested through the API, dashboard or CLI) or `automatic` (the daily scheduled snapshot). `null` on older snapshots. ```json theme={"system"} { "status":"success", "response":[ { "name":"a14b8d5e1cb7405a851eb4c075506121_mongo_manual", "size":10644463, "modified":"2025-08-13T13:29:11.263Z", "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=VZ03MSxcNw3%2FtPezXv0IhTs0jq4%3D&versionId=45ec0b49-9af6-445e-a55c-abd7ec5278b2", "version_id":"45ec0b49-9af6-445e-a55c-abd7ec5278b2", "url":"https://snapshots.squarecloud.app/databases//.zip?", "runtime":"mongo", "origin":"manual" }, { "name":"a14b8d5e1cb7405a851eb4c075506121_mongo_automatic", "size":2742383, "modified":"2025-08-13T00:01:47.010Z", "key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=7zw5apjyaOd1xPZl3gRgp8Y4yEs%3D&versionId=f65e1378-8717-45c5-8aec-bb233eedb5ce", "version_id":"f65e1378-8717-45c5-8aec-bb233eedb5ce", "url":"https://snapshots.squarecloud.app/databases//.zip?", "runtime":"mongo", "origin":"automatic" } ] } ``` Download a snapshot from its `url`. The link stays valid for 30 days. ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | ## Related * CLI: [`squarecloud db snapshot list`](/en/cli-reference/snapshots#squarecloud-db-snapshot-list) * SDKs: [`api.databases.snapshots.list()`](/en/sdks/js/databases) (JavaScript), [`client.databases.snapshots.list()`](/en/sdks/py/databases) (Python), [`c.Databases.Snapshots.List()`](/en/sdks/go/databases) (Go) # Restore a database snapshot Source: https://docs.squarecloud.app/en/api-reference/endpoint/databases/snapshots/restore POST https://api.squarecloud.app/v2/databases/{database_id}/snapshots/restore Overwrite a database's data with a snapshot using POST /v2/databases/{database_id}/snapshots/restore. The snapshot's engine must match the database. This route has a rate limit of 1 request every 60 seconds. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `snapshots:write` [scope](/en/api-reference/authentication#scopes). Restores a database in-place from a previously taken snapshot, identified by the `snapshotId` and `versionId` returned from [Create Snapshot](/en/api-reference/endpoint/databases/snapshots/create) or [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list). The snapshot's engine must match the target database's `type`, you cannot restore a Redis snapshot onto a MongoDB database, for example. This overwrites the database's current data with the snapshot's contents; there is no undo beyond taking another snapshot first. While the restore is running, [Start](/en/api-reference/endpoint/databases/start), [Stop](/en/api-reference/endpoint/databases/stop) and [Delete Database](/en/api-reference/endpoint/databases/delete) are rejected for that database. Rate limited to 1 restore per 60 seconds per user, and 1 restore per 120 seconds per database. ## Parameters The ID of the database. The snapshot `name` from the listing (the database ID suffixed with `_` and, on newer snapshots, `_`), passed exactly as returned. The snapshot's `version_id`, as [List Snapshots](/en/api-reference/endpoint/databases/snapshots/list) returns it. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status":"success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `MISSING_PARAMETERS` | 400 | `snapshotId` or `versionId` was not provided. | | `INVALID_SNAPSHOT_ID` | 400 | `snapshotId` is not a snapshot name as returned by the listing (an ID, optionally with up to two `_` suffixes). | | `INVALID_VERSION_ID` | 400 | `versionId` does not match the expected format. | | `SNAPSHOT_DATABASE_MISMATCH` | 400 | The snapshot's engine does not match this database's `type`. | | `SNAPSHOT_NOT_FOUND` | 404 | No snapshot exists for the given `snapshotId` and `versionId`. | | `DATABASE_NOT_FOUND` | 404 | The database does not exist or is not owned by the caller. | | `SNAPSHOT_RESTORE_FAILED` | 404 | The restore failed. This is the only failure code; `SNAPSHOT_NOT_FOUND` means the snapshot does not exist. | ## Related * CLI: [`squarecloud db snapshot restore`](/en/cli-reference/snapshots#squarecloud-db-snapshot-restore) * SDKs: [`api.databases.snapshots.restore()`](/en/sdks/js/databases) (JavaScript), [`client.databases.snapshots.restore()`](/en/sdks/py/databases) (Python), [`c.Databases.Snapshots.Restore()`](/en/sdks/go/databases) (Go) # Share an application with a workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/apps/add POST https://api.squarecloud.app/v2/workspaces/applications Share an application you own with a workspace you own via POST /v2/workspaces/applications, so members get access by role without a transfer. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Shares an application owned by the authenticated user into a workspace they also own, giving the workspace's members access to it according to their role instead of transferring ownership. A workspace holds up to 100 shared applications, and the same application cannot be shared into the same workspace twice. This is a workspace-owner-only action: the caller must own both the workspace and the application. Use [Get Application Info](/en/api-reference/endpoint/apps/info) beforehand to confirm the application ID, and [Remove Application](/en/api-reference/endpoint/workspace/apps/remove) to undo the share later. Rate limited to 10 additions per 30 seconds per user. ## Parameters The ID of the workspace. The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `APP_NOT_FOUND` | 400 | `appId` is missing from the request body. | | `APP_NOT_FOUND` | 404 | No application with that ID exists for the caller. | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist or is not owned by the caller. | | `APPLICATIONS_LIMIT_REACHED` | 400 | The workspace already has 100 shared applications. | | `APP_ALREADY_IN_WORKSPACE` | 400 | The application is already shared into this workspace. | ## Related * CLI: [`squarecloud workspace app add`](/en/cli-reference/workspaces#squarecloud-workspace-app-add) * SDKs: [`api.workspaces.apps.add()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.apps.add()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Apps.Add()`](/en/sdks/go/workspaces) (Go) # Remove an application from a workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/apps/remove DELETE https://api.squarecloud.app/v2/workspaces/applications Stop sharing an application with a workspace via DELETE /v2/workspaces/applications. Members lose access; the app keeps running under its owner. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Unshares an application from a workspace, revoking access for every member. Only the workspace owner can call this; it does not affect the application itself, which keeps running and stays owned by whoever uploaded it. Use [Get Workspace](/en/api-reference/endpoint/workspace/get) to check which applications are currently shared before removing one, and [Add Application](/en/api-reference/endpoint/workspace/apps/add) to share it again later. Rate limited to 10 removals per 30 seconds per user. ## Parameters The ID of the workspace. The ID of the application. You can find this in the URL of your application's dashboard. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `APP_NOT_FOUND` | 400 | `appId` is missing, or the application is not currently shared into this workspace. | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist. | ## Related * CLI: [`squarecloud workspace app remove`](/en/cli-reference/workspaces#squarecloud-workspace-app-remove) * SDKs: [`api.workspaces.apps.remove()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.apps.remove()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Apps.Remove()`](/en/sdks/go/workspaces) (Go) # Create workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/create POST https://api.squarecloud.app/v2/workspaces Create a workspace with POST /v2/workspaces to share applications with other Square Cloud accounts by role. Available on Standard, Pro and Enterprise. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Creates a workspace owned by the authenticated user, so applications can be shared with other Square Cloud accounts under a role-based permission model instead of transferring ownership. Workspaces are available on Standard, Pro, and Enterprise plans only; every plan tier in that range caps an account at 5 workspaces. The `name` must be 1-32 characters (letters, numbers, spaces, hyphens, or underscores). After creating a workspace, use [Add Application](/en/api-reference/endpoint/workspace/apps/add) to share applications into it and [Invite Member](/en/api-reference/endpoint/workspace/members/invite) to add collaborators. This endpoint is rate limited to 1 creation every 10 seconds per user. ## Parameters A string representing the name of the workspace. Must adhere to the a to z, A to Z, 0 to 9, spaces and \_ pattern. (1-32 characters) ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the Workspace. The name of the Workspace. ```json theme={"system"} { "status": "success", "response": { "id": "dcedcd13d7e272a7b32a70f6a1d180f23c12d759", "name": "Test" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_NAME` | 400 | `name` is missing or fails the 1-32 character pattern. | | `UPGRADE_REQUIRED` | 403 | The active plan is not Standard, Pro, or Enterprise. | | `WORKSPACE_LIMIT_REACHED` | 400 | The account already has the plan's maximum number of workspaces. | | `WORKSPACE_CREATION_FAILED` | 400 | The workspace could not be created. | ## Related * CLI: [`squarecloud workspace create`](/en/cli-reference/workspaces#squarecloud-workspace-create) * SDKs: [`api.workspaces.create()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.create()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Create()`](/en/sdks/go/workspaces) (Go) # Delete workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/delete DELETE https://api.squarecloud.app/v2/workspaces Delete a workspace and its member list with DELETE /v2/workspaces. Only the owner can do it, and shared applications keep running under their owner. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Permanently deletes a workspace and its member list. Only the workspace owner can call this endpoint; a member who no longer wants access should call [Leave Workspace](/en/api-reference/endpoint/workspace/leave) instead. Deleting a workspace only removes the sharing relationship: the applications that were shared into it keep running under their original owner and are unaffected. To review who has access before deleting, call [Get Workspace](/en/api-reference/endpoint/workspace/get). This endpoint is rate limited to 1 deletion every 10 seconds per user. ## Parameters The ID of the workspace. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `WORKSPACE_NOT_FOUND` | 404 | No workspace with that ID is owned by the caller. | ## Related * CLI: [`squarecloud workspace delete`](/en/cli-reference/workspaces#squarecloud-workspace-delete) * SDKs: [`api.workspaces.delete()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.delete()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Delete()`](/en/sdks/go/workspaces) (Go) # Get workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/get GET https://api.squarecloud.app/v2/workspaces/{workspaceId} Get one workspace with GET /v2/workspaces/{workspaceId}: owner, members and roles, shared applications and creation date. Non-members get a 404. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Returns the full details of a single workspace: its owner, member list with roles, shared applications, and creation date. The authenticated user must be the owner or a current member; anyone else, including someone with just the workspace ID, gets a 404 rather than a permission error, so the endpoint doubles as a lightweight existence check. Use this after [Invite Member](/en/api-reference/endpoint/workspace/members/invite) or [Add Application](/en/api-reference/endpoint/workspace/apps/add) to confirm the change landed, or use [List Workspaces](/en/api-reference/endpoint/workspace/list) to fetch every workspace the caller has access to at once. Rate limited to 30 requests per 60 seconds per user, with a short block once that's exceeded. ## Parameters The ID of the workspace. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the workspace: 32 hexadecimal characters (a UUID v4 without hyphens). Older workspaces have a 40-character hexadecimal ID. The Workspace owner id. The name of the Workspace. The workspace member list. It always includes the owner, with `group: "owner"`. The user's ID. The user's name. Can be `null`, for example when the account was deleted. The member permissions on the workspace applications. The join timestamp in UTC-0. The workspace applications list. The ID of the uploaded application. The name of the uploaded application. The RAM usage of the uploaded application in MB. The programming language of the uploaded application. The creation timestamp in UTC-0. ```json theme={"system"} { "status": "success", "response": { "id": "3f9c2a7e5b1d4e8a9c6f0b2d4e6a8c1f", "name": "Test", "owner": "5354d9742d889d49b20134ba0be09ccc0033be68", "members": [ { "name": "Example", "id": "5354d9742d889d49b20134ba0be09ccc0033be68", "group": "owner", "joinedAt": "2025-06-04T20:44:55.934Z" } ], "applications": [], "createdAt": "2025-06-04T20:44:55.934Z" } } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist, or the caller is neither its owner nor a member. | | `DATABASE_UNAVAILABLE` | 503 | The service is briefly unavailable. Retry in a few seconds. | ## Related * CLI: [`squarecloud workspace info`](/en/cli-reference/workspaces#squarecloud-workspace-info) * SDKs: [`api.workspaces.get()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.get()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Get()`](/en/sdks/go/workspaces) (Go) # Leave workspace Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/leave DELETE https://api.squarecloud.app/v2/workspaces/leave Leave a workspace you are a member of with DELETE /v2/workspaces/leave, losing access to its shared applications at once. Owners delete it instead. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Removes the authenticated user from a workspace's member list. This is the self-service counterpart to [Remove Member](/en/api-reference/endpoint/workspace/members/kick), for a member who wants out without asking the owner to act. The workspace owner cannot leave their own workspace this way; they must call [Delete Workspace](/en/api-reference/endpoint/workspace/delete) instead, which removes it for every member. Leaving revokes access to the workspace's shared applications immediately. Rate limited to 1 request every 5 seconds per user. ## Parameters The ID of the workspace. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `CANNOT_LEAVE_OWNER` | 400 | The caller is the workspace owner and must delete it instead of leaving. | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist or the caller is not a member. | ## Related * CLI: [`squarecloud workspace leave`](/en/cli-reference/workspaces#squarecloud-workspace-leave) * SDKs: [`api.workspaces.leave()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.leave()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Leave()`](/en/sdks/go/workspaces) (Go) # List workspaces Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/list GET https://api.squarecloud.app/v2/workspaces List every workspace you own or belong to with GET /v2/workspaces, each with its members, roles and shared applications. Empty when you have none. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Returns every workspace where the authenticated user is either the owner or a member, each hydrated with its member list (names and roles) and its shared applications (name, RAM, language, domain). This is the entry point for building a workspace switcher or dashboard, since it avoids one [Get Workspace](/en/api-reference/endpoint/workspace/get) call per workspace. The response is an empty array for a user with no workspaces, whether that's because they're on a plan without workspace access or simply haven't created or joined one. To create the first one, see [Create Workspace](/en/api-reference/endpoint/workspace/create). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. The contents of the response. The ID of the workspace: 32 hexadecimal characters (a UUID v4 without hyphens). Older workspaces have a 40-character hexadecimal ID. The Workspace owner id. The name of the Workspace. The workspace member list. It always includes the owner, with `group: "owner"`. The user's ID. The user's name. Can be `null`, for example when the account was deleted. The member permissions on the workspace applications. The join timestamp in UTC-0. The workspace applications list. The ID of the uploaded application. The name of the uploaded application. The RAM usage of the uploaded application in MB. The programming language of the uploaded application. The creation timestamp in UTC-0. ```json theme={"system"} { "status": "success", "response": [ { "id": "3f9c2a7e5b1d4e8a9c6f0b2d4e6a8c1f", "name": "Test", "owner": "5354d9742d889d49b20134ba0be09ccc0033be68", "members": [ { "name": "Example", "id": "5354d9742d889d49b20134ba0be09ccc0033be68", "group": "owner", "joinedAt": "2025-06-04T20:44:55.934Z" } ], "applications": [], "createdAt": "2025-06-04T20:44:55.934Z" } ] } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `DATABASE_UNAVAILABLE` | 503 | The service is briefly unavailable. Retry in a few seconds. | ## Related * CLI: [`squarecloud workspace list`](/en/cli-reference/workspaces#squarecloud-workspace-list) * SDKs: [`api.workspaces.list()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.list()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.List()`](/en/sdks/go/workspaces) (Go) # Get a workspace invite code Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/members/code GET https://api.squarecloud.app/v2/workspaces/members/code Generate a single-use invite code with GET /v2/workspaces/members/code and give it to a workspace owner, who adds you with it. It expires in 5 minutes. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Generates a short-lived invite code tied to the authenticated user's identity, not to any specific workspace. The user who wants to join shares this code out-of-band (chat, email) with a workspace owner, who then submits it via [Invite Member](/en/api-reference/endpoint/workspace/members/invite) along with the role to grant. The code expires 5 minutes after generation and is single-use: it is invalidated as soon as it is redeemed. Request a new one if it expires before the owner adds you. Rate limited to 1 code every 5 minutes per user. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. Your workspace invite code. ```json theme={"system"} { "status": "success", "code": "9c1a499e623d2410226f1ecdc7e6daaec2fc6704" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INTERNAL_SERVER_ERROR` | 500 | The invite code could not be persisted to cache. | ## Related * CLI: [`squarecloud workspace member invite-code`](/en/cli-reference/workspace-members#squarecloud-workspace-member-invite-code) * SDKs: [`api.workspaces.members.inviteCode()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.members.invite_code()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Members.InviteCode()`](/en/sdks/go/workspaces) (Go) # Invite a workspace member Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/members/invite POST https://api.squarecloud.app/v2/workspaces/members Add a member to a workspace with POST /v2/workspaces/members using their invite code, and assign a role: view, manager, maintain or admin. Owner only. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Adds a member to a workspace using a short-lived code from [Get Invite Code](/en/api-reference/endpoint/workspace/members/code): the invited user is identified by the code, and the caller assigns their role with `group`. Only the workspace owner can call this endpoint, and the workspace's member count is capped by the owner's plan tier. The role in `group` decides what the member can do on the workspace's shared applications: see [Roles](#roles). Change a role later with [Change Permissions](/en/api-reference/endpoint/workspace/members/perms). An owner cannot invite themselves. Rate limited to 1 addition every 5 seconds per user. ## Roles The dashboard shows each role by name, and the API takes the value in the `group` column. | Dashboard | `group` | What the member can do on the workspace's shared applications | | - | - | - | | View | `view` | Read only: information, status, logs, metrics, network analytics and deploy history. | | Manager | `manager` | Everything `view` can, plus start, stop and restart, and the current deploy settings. | | Maintain | `maintain` | Everything `view` can, plus start, stop and restart, commits, files, DNS records and cache purge. | | Admin | `admin` | Everything, including environment variables, snapshots, custom domains, the GitHub webhook and restricted files such as `.env`. | The workspace owner shows up in member lists with `group: "owner"` and always has full access. `owner` can't be assigned. ## Parameters The ID of the workspace. A string with the member invite code. The member's role: `view`, `manager`, `maintain` or `admin`. See [Roles](#roles). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `INVALID_CODE` | 400 | The invite code is missing, malformed, or has expired. | | `CANNOT_INVITE_OWNER` | 400 | The invite code belongs to the caller, who already owns the workspace. | | `INVALID_GROUP` | 400 | `group` is not one of `view`, `manager`, `maintain`, `admin`. | | `MEMBERS_LIMIT_REACHED` | 400 | The workspace already has the plan's maximum number of members. | | `MEMBER_ALREADY_ADDED` | 400 | The invited user is already a member of this workspace. | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist. | ## Related * CLI: [`squarecloud workspace member add`](/en/cli-reference/workspace-members#squarecloud-workspace-member-add) * SDKs: [`api.workspaces.members.add()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.members.add()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Members.Add()`](/en/sdks/go/workspaces) (Go) # Remove a workspace member Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/members/kick DELETE https://api.squarecloud.app/v2/workspaces/members Remove a member from a workspace with DELETE /v2/workspaces/members, revoking their access to every shared application at once. Only the owner can. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Removes a member from a workspace, immediately revoking their access to every application shared into it. Only the workspace owner can call this endpoint; a member who wants to remove themselves should use [Leave Workspace](/en/api-reference/endpoint/workspace/leave) instead. Removing a member does not free up their invite code for reuse: generate a fresh one with [Get Invite Code](/en/api-reference/endpoint/workspace/members/code) if they need to rejoin later. Rate limited to 5 removals per 30 seconds per user. ## Parameters The ID of the workspace. The member ID. ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `MEMBER_NOT_FOUND` | 400 | `memberId` is missing. | | `MEMBER_NOT_FOUND` | 404 | The member is no longer in the workspace (already removed). | ## Related * CLI: [`squarecloud workspace member remove`](/en/cli-reference/workspace-members#squarecloud-workspace-member-remove) * SDKs: [`api.workspaces.members.remove()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.members.remove()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Members.Remove()`](/en/sdks/go/workspaces) (Go) # Change a workspace member's role Source: https://docs.squarecloud.app/en/api-reference/endpoint/workspace/members/perms PATCH https://api.squarecloud.app/v2/workspaces/members Change a workspace member's role with PATCH /v2/workspaces/members to view, manager, maintain or admin. It applies at once; only the owner can call it. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Requires an API key with the `workspaces:manage` [scope](/en/api-reference/authentication#scopes). Changes the role of an existing workspace member, taking effect immediately on their access to the workspace's shared applications. The four roles are `view`, `manager`, `maintain` and `admin`: the [roles table](/en/api-reference/endpoint/workspace/members/invite#roles) shows what each one allows and its name in the dashboard. Only the workspace owner can call this endpoint, and the owner cannot change their own role since they always hold full access. To add a new member instead of changing an existing one, see [Invite Member](/en/api-reference/endpoint/workspace/members/invite). Rate limited to 3 edits per 15 seconds per user. ## Parameters The ID of the workspace. The member ID. The new role: `view`, `manager`, `maintain` or `admin`. See [Roles](/en/api-reference/endpoint/workspace/members/invite#roles). ## Response Indicates whether the call was successful: `success` if it was, `error` if not. ```json theme={"system"} { "status": "success" } ``` ## Common errors | Code | HTTP | Meaning | | - | - | - | | `INVALID_ID` | 400 | `workspaceId` is missing. | | `MEMBER_NOT_FOUND` | 400 | `memberId` is missing or does not belong to the workspace. | | `MEMBER_NOT_FOUND` | 404 | The member is no longer in the workspace (already removed). | | `CANNOT_EDIT_OWNER` | 400 | The caller tried to change their own role. | | `INVALID_GROUP` | 400 | `group` is not one of `view`, `manager`, `maintain`, `admin`. | | `WORKSPACE_NOT_FOUND` | 404 | The workspace does not exist. | ## Related * CLI: [`squarecloud workspace member update`](/en/cli-reference/workspace-members#squarecloud-workspace-member-update) * SDKs: [`api.workspaces.members.update()`](/en/sdks/js/workspaces) (JavaScript), [`client.workspaces.members.update()`](/en/sdks/py/workspaces) (Python), [`c.Workspaces.Members.Update()`](/en/sdks/go/workspaces) (Go) # Blob Storage API authentication Source: https://docs.squarecloud.app/en/blob-reference/authentication Authenticate to the Blob Storage API with an API key or a short-lived upload token in the Authorization header, and pick the scopes each route needs. Blob Storage accepts two kinds of credentials in the `Authorization` header: * **API key**: created in your [account settings](https://squarecloud.app/en/account/security). It works on every route, limited by the scopes you give it. * **Upload token** (`squp_...`): a short-lived token your server mints with [Upload Tokens](/en/blob-reference/endpoint/upload-tokens). It only uploads, so it is safe to hand to a browser. ```bash theme={"system"} Authorization: ``` The use of the API is subject to the [Terms of Service](https://squarecloud.app/legal) and the [Acceptable Use Policy](https://squarecloud.app/legal/policy). The [Blob SDK](/en/sdks/blob/client) (`@squarecloud/blob`) sends the credential for you and wraps every route of this reference. ## Scopes An API key carries scopes. Blob Storage reads two of them: | Scope | Routes | | - | - | | `blob:read` | [Object List](/en/blob-reference/endpoint/list), [Object Info](/en/blob-reference/endpoint/info), [Object Download](/en/blob-reference/endpoint/download), [Account Stats](/en/blob-reference/endpoint/stats), [Get Settings](/en/blob-reference/endpoint/settings-get), [List Shares](/en/blob-reference/endpoint/shares-list) | | `blob:write` | [Object Post](/en/blob-reference/endpoint/post), [Object Update](/en/blob-reference/endpoint/update), [Object Copy](/en/blob-reference/endpoint/copy), [Object Delete](/en/blob-reference/endpoint/delete), every [chunked upload](/en/blob-reference/endpoint/chunked-init) route, [Update Settings](/en/blob-reference/endpoint/settings-put), [Upload Tokens](/en/blob-reference/endpoint/upload-tokens), [Create Share](/en/blob-reference/endpoint/shares-create), [Delete Share](/en/blob-reference/endpoint/shares-delete) | | either | [S3 Credentials](/en/blob-reference/endpoint/s3-credentials): the pair it returns can write only when the key has `blob:write` | A key without the scope a route needs gets `403 MISSING_SCOPE`. A key restricted to specific applications has no access to Blob Storage and gets `403 RESOURCE_NOT_ALLOWED`. Give each integration its own key with only the scope it needs. A backend that only serves files needs `blob:read`; a job that only uploads needs `blob:write`. ## Upload tokens An upload token is accepted only on [Object Post](/en/blob-reference/endpoint/post) and the [chunked upload](/en/blob-reference/endpoint/chunked-init) routes. Any other route answers `403 UPLOAD_TOKEN_NOT_ALLOWED`. The token pins the name, prefix, visibility, size and file types chosen when it was minted, and stops working when it expires, when its uses run out, or when the API key that minted it is revoked. ## S3 gateway S3 tools don't send the API key itself. They sign requests (SigV4) with an access key pair derived from it: get it from [S3 Credentials](/en/blob-reference/endpoint/s3-credentials) and read [S3 compatibility](/en/blob-reference/s3-compatibility). ## Errors Error responses follow the shape `{ "status": "error", "code": "SOME_CODE" }`, sometimes with a `message` that explains the case. Branch on `code`, never on `message`. The full list is in [Errors](/en/blob-reference/errors). ```json theme={"system"} { "status": "error", "code": "RATE_LIMITED" } ``` ### Global errors Any Blob route can also return these: | Code | HTTP | Meaning | | - | - | - | | `ACCESS_DENIED` | 401 | The credential is missing or was not recognized (revoked, regenerated or expired). | | `MISSING_SCOPE` | 403 | The API key lacks the scope this route needs. | | `RESOURCE_NOT_ALLOWED` | 403 | The API key is restricted to specific applications and cannot use Blob Storage. | | `UPLOAD_TOKEN_NOT_ALLOWED` | 403 | An upload token was sent to a route that is not an upload route. | | `RATE_LIMITED` | 429 | A limit was reached: this route's own limit, the account-wide API budget of your plan, or this IP sent too many invalid credentials and is blocked for a short period. Wait and retry. | | `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | The requested route does not exist. | | `INTERNAL_SERVER_ERROR` | 500 | Unexpected internal failure. Try again later. | Learn about the limits and restrictions of the Square Cloud API. # Abort a chunked upload Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-abort DELETE https://blob.squarecloud.app/v1/objects/chunked Cancel a chunked upload and discard its parts with DELETE /v1/objects/chunked. It is idempotent and needs no active plan, so you can always clean up. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Chunked Abort cancels an upload opened with [Chunked Init](/en/blob-reference/endpoint/chunked-init) and discards the parts already sent, freeing one of the account's 32 open uploads. It is idempotent: aborting an upload that was already completed, aborted or expired also answers success. No active plan is needed, so you can always clean up. Requires the `blob:write` scope, or the upload token that opened the upload. Uploads idle for 24 hours are aborted automatically. ## Parameters The `upload` token returned by Chunked Init. It can also go in the `upload` query parameter. ## Rate limits 10 requests per 10 seconds (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. ```bash cURL theme={"system"} curl --request DELETE \ --url 'https://blob.squarecloud.app/v1/objects/chunked' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "upload": "UPLOAD_TOKEN" }' ``` ```javascript JavaScript theme={"system"} await fetch('https://blob.squarecloud.app/v1/objects/chunked', { method: 'DELETE', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ upload: uploadToken }), }); ``` ```json theme={"system"} { "status": "success" } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | The `upload` token is missing, malformed or not yours. | | `RATE_LIMITED` | 429 | More than 10 requests in 10 seconds. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # Complete a chunked upload Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-complete PATCH https://blob.squarecloud.app/v1/objects/chunked Seal a chunked upload with PATCH /v1/objects/chunked: the server assembles the parts it received into the final file, which then counts toward your quota. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Chunked Complete assembles the parts sent with [Chunked Part](/en/blob-reference/endpoint/chunked-part) into the final file. The part list is read on the server, so you only send the `upload` token. Once it answers, the file is stored and counts against your quota. Requires the `blob:write` scope, or the upload token that opened the upload, and an active plan. What happens on a refusal depends on the cause: * **The upload is kept open** when the account has no active plan (`PERMISSION_DENIED`), is over its quota (`STORAGE_QUOTA_EXCEEDED`) or storage is unavailable (503). Fix the cause and call Complete again, without re-sending any part. * **The upload is aborted** and its parts are discarded when the file is smaller than 512 bytes (`FILE_TOO_SMALL`) or larger than its limit (`FILE_TOO_LARGE`). * **Nothing changes** when no part was sent yet (`NO_CHUNKS_UPLOADED`) or a part other than the last is under 5 MB (`CHUNK_TOO_SMALL`): re-send that part and complete again. ## Parameters The `upload` token returned by Chunked Init. It can also go in the `upload` query parameter. ## Rate limits 5 requests per 10 seconds, so several parallel uploads can finish together (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The id of the stored file. Whether the file is private. The public URL, or `null` for private files. When the file will be deleted. Present only when it expires. The size of the file, in bytes. How many parts were assembled. ```bash cURL theme={"system"} curl --request PATCH \ --url 'https://blob.squarecloud.app/v1/objects/chunked' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "upload": "UPLOAD_TOKEN" }' ``` ```javascript JavaScript theme={"system"} const response = await fetch('https://blob.squarecloud.app/v1/objects/chunked', { method: 'PATCH', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ upload: uploadToken }), }); ``` ```json theme={"system"} { "status": "success", "response": { "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz", "private": true, "url": null, "size": 2147483648, "parts": 128 } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | The `upload` token is missing, malformed or not yours. | | `NO_CHUNKS_UPLOADED` | 400 | No part was sent yet. | | `CHUNK_TOO_SMALL` | 400 | A part other than the last has less than 5 MB. | | `FILE_TOO_SMALL` | 400 | The file has less than 512 bytes. The upload is aborted. | | `PERMISSION_DENIED` | 401 | The account has no active plan. The upload stays open. | | `STORAGE_QUOTA_EXCEEDED` | 403 | The file would pass the included storage. The upload stays open. | | `UPLOAD_NOT_FOUND` | 404 | The upload was completed, aborted or expired. | | `FILE_TOO_LARGE` | 413 | The file passes its size limit. The upload is aborted. | | `RATE_LIMITED` | 429 | More than 5 requests in 10 seconds. | | `UPLOAD_FAILED` | 500 | The assembly failed. Retry. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | Storage is temporarily unavailable. The upload stays open. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # Start a chunked upload Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-init POST https://blob.squarecloud.app/v1/objects/chunked Open a chunked upload for files of up to 10 GiB with POST /v1/objects/chunked and get the upload token for the next calls. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Chunked Init opens a chunked upload, the flow for files above the 100 MB single-request limit, up to **10 GiB**. It returns an opaque `upload` token that you carry through the next calls: This route. Keep the `upload` token. [Chunked Part](/en/blob-reference/endpoint/chunked-part), in any order, up to 6 at a time. [Chunked Complete](/en/blob-reference/endpoint/chunked-complete) seals the file. Or [Chunked Abort](/en/blob-reference/endpoint/chunked-abort) to cancel. There is no server-side session: the token is the whole upload state, so persist it if the upload may span a page reload. Lost it? [Open Uploads](/en/blob-reference/endpoint/chunked-open) lists the open uploads with their tokens, and [Chunked Status](/en/blob-reference/endpoint/chunked-status) tells which parts already arrived. Uploads idle for 24 hours are aborted automatically. ## Parameters The query parameters are the same as in [Object Post](/en/blob-reference/endpoint/post), plus `filename` and `mime_type`: there is no multipart envelope here, so the extension has to come from the query. Requires the `blob:write` scope, or an [upload token](/en/blob-reference/endpoint/upload-tokens), and an active plan. The file name, without extension. Same pattern as in Object Post. The original file name, extension included. The stored extension comes from it, then from `mime_type`, then falls back to `bin`. Used for the extension only when `filename` has none. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. Same as in Object Post. ## Limits * File size: up to **10 GiB** (10,737,418,240 bytes), or less when a rule or upload token sets a smaller limit. * Part size: **5 MB minimum** (5,242,880 bytes), **32 MB maximum** (33,554,432 bytes). The last part may be smaller. * Parts per file: up to **2048**. * Open uploads per account: **32**, counting uploads opened through the [S3 gateway](/en/blob-reference/s3-compatibility) (`TOO_MANY_OPEN_UPLOADS`, 429). * Rate limit: 5 opens per 10 seconds. * An account already over its included storage can't open uploads (`STORAGE_QUOTA_EXCEEDED`). Read the limits from the `chunk` object of the response rather than hardcoding them. ## Response "success" if successful, "error" if not. The opaque upload token. Send it on every later call of the flow. The id the file will have once completed. Whether the file will be private. The public URL the file will have, or `null` when private. When the file will be deleted. Present only when it expires. The name sent in the request. The prefix, when one was sent. The limits of this upload: `min_size` and `max_size` (part bytes), `max_parts`, and `max_object_size` (file bytes). ```bash cURL theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \ --header 'Authorization: YOUR_API_KEY' ``` ```javascript JavaScript theme={"system"} const params = new URLSearchParams({ name: 'dataset', filename: file.name, prefix: 'genomics', private: 'true', }); const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, { method: 'POST', headers: { Authorization: 'YOUR_API_KEY' }, }); const { response: upload } = await res.json(); // persist upload.upload: it is the handle to this upload ``` ```python Python theme={"system"} import requests response = requests.post( 'https://blob.squarecloud.app/v1/objects/chunked', headers={'Authorization': 'YOUR_API_KEY'}, params={'name': 'dataset', 'filename': 'reads.fastq.gz', 'prefix': 'genomics', 'private': 'true'}, ) upload = response.json()['response'] ``` ```json theme={"system"} { "status": "success", "response": { "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk", "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz", "private": true, "url": null, "name": "dataset", "prefix": "genomics", "chunk": { "min_size": 5242880, "max_size": 33554432, "max_parts": 2048, "max_object_size": 10737418240 } } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT_*` / `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | A parameter is invalid, as in [Object Post](/en/blob-reference/endpoint/post#errors). | | `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED` | 400 | The extension is malformed, blocked, or not allowed by the rule or token. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPLOAD_TOKEN_USED` | 401 | The upload token has no uses left. An expired token answers `ACCESS_DENIED`. | | `STORAGE_QUOTA_EXCEEDED` | 403 | The account is already over its included storage. | | `PREFIX_NOT_ALLOWED` | 403 | The upload token is bound to another prefix. | | `UPGRADE_REQUIRED` | 403 | An option needs a higher plan. | | `TOO_MANY_OPEN_UPLOADS` | 429 | The account has 32 open uploads. Complete or abort one. | | `RATE_LIMITED` | 429 | More than 5 opens in 10 seconds. | | `UPLOAD_FAILED` | 500 | The upload could not be opened. Retry. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | Storage is temporarily unavailable. Retry. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # List open chunked uploads Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-open GET https://blob.squarecloud.app/v1/objects/chunked/open List every open chunked upload of the account with GET /v1/objects/chunked/open, including uploads started over S3, with a token to resume or abort each. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Open Uploads lists the uploads of the account that were started and not yet completed or aborted, including multipart uploads started through the [S3 gateway](/en/blob-reference/s3-compatibility). Each one comes with an `upload` token, so you can [resume](/en/blob-reference/endpoint/chunked-status) or [abort](/en/blob-reference/endpoint/chunked-abort) it even if the client that opened it is gone. Open uploads count toward the limit of 32 per account, and their parts take storage space until they are completed or aborted. Uploads idle for 24 hours are aborted automatically. Requires the `blob:write` scope. ## Rate limits 10 requests per 10 seconds (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The id the file will have once completed. When the upload was opened. The `upload` token to use with Chunked Status, Part, Complete and Abort. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/objects/chunked/open' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "uploads": [ { "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz", "initiated": "2026-09-25T12:00:00.000Z", "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk" } ] } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `RATE_LIMITED` | 429 | More than 10 requests in 10 seconds. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # Upload one part of a chunked upload Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-part PUT https://blob.squarecloud.app/v1/objects/chunked Send one part of a chunked upload with PUT /v1/objects/chunked: raw bytes, 5 to 32 MB each except the last, in any order and safe to retry on failure. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Chunked Part sends one part of an upload opened with [Chunked Init](/en/blob-reference/endpoint/chunked-init). The body is the **raw bytes** of the part, not multipart/form-data. Part numbers run from 1 to 2048 and may be sent in **any order**. Re-sending a part with the same number replaces it, so a failed part can simply be retried. Every part except the last must have from **5 MB to 32 MB**; the last one may be smaller. Send at most **6 parts in parallel** per account: a seventh answers `TOO_MANY_CONCURRENT_CHUNKS`, and you retry that part once another finishes. With 6 in flight, 16 MB parts are a good default for a browser. This route has its own limit of 60 parts per 10 seconds and doesn't consume the account-wide API budget, so a long upload can't exhaust your API quota for the rest of the platform. Requires the `blob:write` scope, or the upload token that opened the upload, and an active plan. ## Parameters The `upload` token returned by Chunked Init. The part number, from 1 to 2048. The raw part bytes (`Content-Type: application/octet-stream`). ## Response "success" if successful, "error" if not. The part number stored. The size of the part, in bytes. The ETag of the part. Informational: Chunked Complete reads the part list on the server, so you never send it back. ```bash cURL theme={"system"} curl --request PUT \ --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/octet-stream' \ --data-binary '@./chunk-1.bin' ``` ```javascript JavaScript theme={"system"} const PART_SIZE = 16 * 1024 * 1024; const total = Math.ceil(file.size / PART_SIZE); async function sendPart(n) { const body = file.slice((n - 1) * PART_SIZE, n * PART_SIZE); const params = new URLSearchParams({ upload: uploadToken, part: String(n) }); const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, { method: 'PUT', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream' }, body, }); if (res.status === 429 || res.status >= 500) return sendPart(n); // add a backoff in production if (!res.ok) throw new Error((await res.json()).code); } // 6 workers, each taking the next part number let next = 1; await Promise.all(Array.from({ length: 6 }, async () => { while (next <= total) await sendPart(next++); })); ``` ```python Python theme={"system"} import requests with open('./bigfile.bin', 'rb') as f: chunk = f.read(16 * 1024 * 1024) response = requests.put( 'https://blob.squarecloud.app/v1/objects/chunked', headers={'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/octet-stream'}, params={'upload': upload_token, 'part': 1}, data=chunk, ) ``` ```json theme={"system"} { "status": "success", "response": { "part": 1, "size": 16777216, "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"" } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | The `upload` token is missing, malformed or not yours. | | `INVALID_CHUNK_PART` | 400 | `part` is not an integer from 1 to 2048. | | `EMPTY_CHUNK` | 400 | The body is empty. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPLOAD_NOT_FOUND` | 404 | The upload was completed, aborted or expired. | | `CHUNK_TOO_LARGE` | 413 | The part has more than 32 MB. | | `FILE_TOO_LARGE` | 413 | With this part, the upload passes its size limit. | | `TOO_MANY_CONCURRENT_CHUNKS` | 429 | 6 parts are already in flight. Retry this part when one finishes. | | `RATE_LIMITED` | 429 | More than 60 parts in 10 seconds. | | `UPLOAD_FAILED` | 500 | The part failed. Retry it. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # Get chunked upload status Source: https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-status GET https://blob.squarecloud.app/v1/objects/chunked See which parts of a chunked upload already arrived with GET /v1/objects/chunked, to resume an interrupted upload by sending only the missing parts. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Chunked Status lists the parts of an open upload that are already stored. Use it to **resume** after a crash, a lost connection or a page reload: send only the missing parts with [Chunked Part](/en/blob-reference/endpoint/chunked-part), then call [Chunked Complete](/en/blob-reference/endpoint/chunked-complete). Requires the `blob:write` scope. If you lost the `upload` token as well, [Open Uploads](/en/blob-reference/endpoint/chunked-open) lists every open upload of the account with its token. ## Parameters The `upload` token returned by Chunked Init. ## Rate limits 10 requests per 10 seconds (`RATE_LIMITED`, 429). Use it to resume an upload, not to poll progress: your client already knows which parts it sent. ## Response "success" if successful, "error" if not. The id the file will have once completed. The stored parts, each as `{ "part", "size", "etag" }`. The lowest part number not stored yet. The total bytes stored so far. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz", "parts": [ { "part": 1, "size": 16777216, "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"" }, { "part": 2, "size": 16777216, "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\"" }, { "part": 4, "size": 16777216, "etag": "\"e1f0a9b8c4a2f0b1c9d8e7f6a5b4c3d2\"" } ], "next_part": 3, "size_so_far": 50331648 } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | The `upload` token is missing, malformed or not yours. | | `UPLOAD_NOT_FOUND` | 404 | The upload was completed, aborted or expired. | | `RATE_LIMITED` | 429 | More than 10 requests in 10 seconds. | ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) runs the whole chunked flow for files above 90 MiB # Copy, move or rename a file Source: https://docs.squarecloud.app/en/blob-reference/endpoint/copy POST https://blob.squarecloud.app/v1/objects/copy Copy, move or rename a file inside Blob Storage with POST /v1/objects/copy, server-side and without downloading it. With move: true the source is removed. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object Copy duplicates a file under a new name, prefix or visibility, entirely on the server: no bytes go through your application. With `move: true` the source is removed afterwards, which is how you **rename** or **move** a file. Requires the `blob:write` scope and an active plan. * The copy keeps the source's extension, content type, cache, disposition and metadata. * A copy counts against your storage quota; a move doesn't. * The destination always uses the current storage, so moving is also how you bring a legacy file, stored before the September 2026 update, to the new format (see [Object Update](/en/blob-reference/endpoint/update#legacy-files)). ## Parameters The id of the file to copy. Where the copy goes. The new name, without extension. Same pattern as in [Object Post](/en/blob-reference/endpoint/post). The new prefix. Omit it to store the copy at the root. The visibility of the copy. Defaults to the source's. A new expiry counted from now (`30d`, `6h`). `null` removes it. Omit it to keep the source's expiry date. Adds a random suffix to the new name. Private copies always get it. `true` removes the source after the copy succeeds. `true` replaces an existing file at the destination. Otherwise the request answers `409 OBJECT_ALREADY_EXISTS`. ## Rate limits 10 requests per 10 seconds (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The id of the new file. Whether the new file is private. The public URL of the new file, or `null` when private. When the new file will be deleted. Present only when it expires. The size of the file, in bytes. The id of the source. Whether the source was removed. Whether an existing file at the destination was replaced. ```bash Rename theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/objects/copy' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "source": "pub/3155597145698959364/uploads/IMG_2041.png", "destination": { "name": "cover", "prefix": "posts/launch" }, "move": true }' ``` ```javascript JavaScript theme={"system"} const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', { method: 'POST', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ source: 'pub/3155597145698959364/uploads/IMG_2041.png', destination: { name: 'cover', prefix: 'posts/launch' }, move: true, }), }); ``` ```json theme={"system"} { "status": "success", "response": { "id": "pub/3155597145698959364/posts/launch/cover.png", "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png", "size": 416230, "source": "pub/3155597145698959364/uploads/IMG_2041.png", "moved": true, "replaced": false } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT` | 400 | `source` is missing, malformed or not yours. | | `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` | 400 | The destination name or prefix doesn't match the pattern. | | `INVALID_DESTINATION` | 400 | `private` or `security_hash` is not a boolean. | | `INVALID_OBJECT_EXPIRE` | 400 | `expire` is not a duration from 1 hour to 1825 days. | | `INVALID_OBJECT_SECURITY_HASH` | 400 | `security_hash: false` on a private copy. | | `SAME_OBJECT` | 400 | The destination is the source. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPGRADE_REQUIRED` | 403 | The expiry needs a higher plan. | | `STORAGE_QUOTA_EXCEEDED` | 403 | The copy would pass the included storage. | | `OBJECT_NOT_FOUND` | 404 | The source doesn't exist. | | `OBJECT_ALREADY_EXISTS` | 409 | A file exists at the destination and `overwrite` is not `true`. | | `RATE_LIMITED` | 429 | More than 10 requests in 10 seconds. | | `COPY_FAILED` | 500 | The copy failed. Retry. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | Storage is temporarily unavailable. Retry. | ## Related * Blob SDK: [`blob.copy()`](/en/sdks/blob/objects), [`blob.move()`](/en/sdks/blob/objects) # Delete files Source: https://docs.squarecloud.app/en/blob-reference/endpoint/delete DELETE https://blob.squarecloud.app/v1/objects Delete one file or up to 100 files per request from Blob Storage with DELETE /v1/objects, with per-file results for batches. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Delete removes one file, or up to **100 files** in a single request. A delete is immediate and final: the file stops being served and its space is freed from your quota. Requires the `blob:write` scope. Deleting doesn't need an active plan, so you can always clean up. * **One id** (`object`, or `objects` with a single entry): answers `200` when deleted, `404 OBJECT_NOT_FOUND` when the file doesn't exist. * **Two or more ids** (`objects`): always answers `200` with the result of each file, so one missing file doesn't fail the rest. Repeated ids count once. An id that is malformed or belongs to another account fails the whole request with `400 INVALID_OBJECT`, before anything is deleted. To find the ids, use [Object List](/en/blob-reference/endpoint/list). ## Parameters The id of the file to delete. Send `object` or `objects`. Up to 100 ids to delete in one request. ## Rate limits 1000 files per 10 seconds, counted per file: a batch of 100 counts as 100. Past that the account is blocked for a short period (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. Present only for batches (two or more ids). The ids that were deleted. The ids that didn't exist. The ids that could not be deleted, each as `{ "id", "code" }`. Retry them. ```bash One file theme={"system"} curl --request DELETE \ --url 'https://blob.squarecloud.app/v1/objects' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png" }' ``` ```bash Batch theme={"system"} curl --request DELETE \ --url 'https://blob.squarecloud.app/v1/objects' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "objects": [ "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png", "pub/3155597145698959364/images/old.png" ] }' ``` ```javascript JavaScript theme={"system"} const response = await fetch('https://blob.squarecloud.app/v1/objects', { method: 'DELETE', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ objects: ids.slice(0, 100) }), }); ``` ```json One file theme={"system"} { "status": "success" } ``` ```json Batch theme={"system"} { "status": "success", "response": { "deleted": [ "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png" ], "not_found": ["pub/3155597145698959364/images/old.png"], "failed": [] } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_BODY` | 400 | The body is missing or is not a JSON object. | | `INVALID_OBJECT` | 400 | No id was sent, or an id is malformed or not yours. | | `TOO_MANY_OBJECTS` | 400 | More than 100 ids. | | `OBJECT_NOT_FOUND` | 404 | The file doesn't exist (single file). | | `RATE_LIMITED` | 429 | More than 1000 files deleted in 10 seconds. | | `DELETE_FAILED` | 500 | Storage failed and the file may still exist. Retry. | ## Related * Blob SDK: [`blob.delete()`](/en/sdks/blob/objects) # Create a temporary download link Source: https://docs.squarecloud.app/en/blob-reference/endpoint/download GET https://blob.squarecloud.app/v1/objects/download Get a download link for any file with GET /v1/objects/download: a temporary link of up to 24 hours for private files, or the public URL. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object Download gives you a link to read a file. For a **private** file it signs a temporary link, valid from 60 seconds to 24 hours, that works without any credential. For a **public** file it returns the public URL. By default it answers with a `302` redirect, so you can point a browser or `curl -L` straight at it; `redirect=false` returns the link as JSON. Requires the `blob:read` scope. Temporary links (`https://files.squarecloud.dev/d/...`) can't be revoked, support `Range` and conditional requests, and stop working when they expire or when the file is deleted, moved or changes visibility. For links you can revoke, cap or protect with a password, use a [share link](/en/blob-reference/endpoint/shares-create). See [Links and sharing](/en/blob-reference/links-and-sharing). ## Parameters The id of the file. How long the temporary link lasts, from 60 to 86400 seconds (24 hours). `false` returns the link as JSON instead of redirecting. `inline` (open in the browser) or `attachment` (download). Setting it always produces a temporary link, even for public files. The name the browser saves the file as. Implies `attachment` unless `disposition` says otherwise, and always produces a temporary link. ## Rate limits * 60 requests per minute to this route (`RATE_LIMITED`, 429). * Each temporary link accepts 60 requests per minute per IP, on top of an overall limit for all the links of your account. Past that the link answers `429` in plain text. To hand one file to many people, make it public: public files are served by the CDN, without this limit. An expired or invalid link answers `404`. ## Response With `redirect=true` (default): `302` with the link in `Location` and `Cache-Control: no-store`. With `redirect=false`: "success" if successful, "error" if not. The link: a temporary link on `files.squarecloud.dev`, or the public URL. When the temporary link expires, or `null` for a public URL. Whether the file is private. The size of the file, in bytes. The `Content-Type` the file is served with. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \ --header 'Authorization: YOUR_API_KEY' ``` ```javascript JavaScript theme={"system"} const params = new URLSearchParams({ object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf', expires: '600', filename: 'invoice-september.pdf', redirect: 'false', }); const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, { headers: { Authorization: 'YOUR_API_KEY' }, }); const { response } = await res.json(); // hand response.url to the user; it works without credentials for 10 minutes ``` ```json theme={"system"} { "status": "success", "response": { "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo", "expires_at": "2026-09-25T12:10:00.000Z", "private": true, "size": 88412, "content_type": "application/pdf" } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT` | 400 | `object` is missing, malformed or not yours. | | `INVALID_DOWNLOAD_EXPIRES` | 400 | `expires` is not an integer from 60 to 86400. | | `INVALID_OBJECT_DISPOSITION` | 400 | `disposition` is not `inline` or `attachment`. | | `INVALID_FILENAME` | 400 | `filename` is empty after removing invalid characters. | | `OBJECT_NOT_FOUND` | 404 | The file doesn't exist. | | `RATE_LIMITED` | 429 | More than 60 requests in a minute. | ## Related * Blob SDK: [`blob.downloadUrl()`](/en/sdks/blob/objects) # Get file details Source: https://docs.squarecloud.app/en/blob-reference/endpoint/info GET https://blob.squarecloud.app/v1/objects/info Read the details of one file with GET /v1/objects/info: size, content type, expiry, visibility, cache, original name and metadata. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object Info returns everything Blob Storage knows about one file without downloading it: size, content type, expiry, visibility, the headers it is served with, the original file name and your metadata. Requires the `blob:read` scope. ## Parameters The id of the file. ## Rate limits 60 requests per minute (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The id of the file. The size, in bytes. The `Content-Type` the file is served with, derived from its extension. The ETag. It changes when the content changes. When the file was written. Changing visibility, expiry or headers rewrites the file and resets this date. When the file will be deleted, or `null`. Whether the file is private. The public URL, or `null` for private files. The `Cache-Control` header, or `null` when the CDN default applies. The `Content-Disposition` header, or `null`. The name of the file as uploaded. Your metadata, as key and value strings. `true` for legacy files, stored before the September 2026 update. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/objects/info?object=pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "size": 416230, "content_type": "image/png", "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"", "created_at": "2026-09-25T12:00:00.000Z", "expires_at": null, "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "cache_control": "public, max-age=31536000, immutable", "content_disposition": null, "original_name": "logo.png", "metadata": { "campaign": "spring" }, "legacy": false } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT` | 400 | `object` is missing, malformed or not yours. | | `OBJECT_NOT_FOUND` | 404 | The file doesn't exist. | | `RATE_LIMITED` | 429 | More than 60 requests in a minute. | ## Related * Blob SDK: [`blob.info()`](/en/sdks/blob/objects) # List files in Blob Storage Source: https://docs.squarecloud.app/en/blob-reference/endpoint/list GET https://blob.squarecloud.app/v1/objects List the files in your Blob Storage with GET /v1/objects: filter by prefix and visibility, browse folders and paginate with a cursor. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object List enumerates the files stored under your account, optionally filtered by prefix and visibility, and paginates with a cursor instead of returning everything at once. Use it to build a file browser, confirm an upload landed, or reconcile your own records against what Blob Storage holds. Requires the `blob:read` scope. Pages are cached for 30 minutes per set of parameters, and your own uploads and deletes clear that cache, so they show up right away. The order of the results is not guaranteed. A page can hold fewer than `limit` objects while more remain: keep requesting until `continuationToken` is absent. ## Parameters Only files whose path starts with this string (for example `images/` or `images/2026-`). Letters, digits, `_`, `.`, `-` and `/`, up to 256 characters. Only `/`. Groups the files below the next `/` into `folders` instead of listing them, like a directory listing. `true` lists only private files, `false` only public ones. Omit it to list both. Maximum number of entries per page, from 1 to 1000. The `continuationToken` of the previous page. `continuationToken` is also accepted as the parameter name. ## Rate limits 30 requests per 30 seconds, blocked for a short period past that (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The object id. Treat it as opaque. The size of the file, in bytes. When the file was stored. When the file will be deleted. Omitted for files that don't expire. Whether the file is private. The public URL, or `null` for private files. The ETag of the file. It changes when the content changes. The folders below `prefix`, each ending in `/`. Present only with `delimiter=/`. Send it back as `cursor` to get the next page. Absent on the last page. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/objects?prefix=images/&delimiter=/&limit=100' \ --header 'Authorization: YOUR_API_KEY' ``` ```javascript JavaScript theme={"system"} let cursor; do { const params = new URLSearchParams({ prefix: 'images/', limit: '1000' }); if (cursor) params.set('cursor', cursor); const res = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, { headers: { Authorization: 'YOUR_API_KEY' }, }); const { response } = await res.json(); for (const object of response.objects) console.log(object.id, object.size); cursor = response.continuationToken; } while (cursor); ``` ```python Python theme={"system"} import requests cursor = None while True: params = {'prefix': 'images/', 'limit': 1000} if cursor: params['cursor'] = cursor response = requests.get( 'https://blob.squarecloud.app/v1/objects', headers={'Authorization': 'YOUR_API_KEY'}, params=params, ).json()['response'] for obj in response['objects']: print(obj['id'], obj['size']) cursor = response.get('continuationToken') if not cursor: break ``` ```json Response - [30m cache] theme={"system"} { "status": "success", "response": { "objects": [ { "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "size": 416230, "created_at": "2026-09-25T12:00:00.000Z", "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\"" }, { "id": "prv/3155597145698959364/images/draft_mugws5c0-1b4f0e9851971998e732078544c96b36.png", "size": 90466, "created_at": "2026-09-25T12:00:00.000Z", "private": true, "url": null, "etag": "\"4a2f0b1c9d8e7f6a5b4c3d2e1f0a9b8c\"" } ], "folders": ["images/icons/"], "continuationToken": "Q7mZp2Xk9LwR4vTn8sHd1c" } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT_PREFIX` | 400 | `prefix` has characters outside the pattern or contains `..`. | | `INVALID_DELIMITER` | 400 | `delimiter` is not `/`. | | `INVALID_OBJECT_PRIVATE` | 400 | `private` is not `true` or `false`. | | `INVALID_LIMIT` | 400 | `limit` is not an integer from 1 to 1000. | | `INVALID_CONTINUATION_TOKEN` | 400 | The `cursor` (or `continuationToken`) is malformed or no longer valid. Start again without a cursor. | | `RATE_LIMITED` | 429 | More than 30 requests in 30 seconds. | ## Related * Blob SDK: [`blob.list()`](/en/sdks/blob/objects), [`blob.listPage()`](/en/sdks/blob/objects) # Upload a file to Blob Storage Source: https://docs.squarecloud.app/en/blob-reference/endpoint/post POST https://blob.squarecloud.app/v1/objects Upload a file of up to 100 MB to Blob Storage with POST /v1/objects: public or private, with expiry, cache, metadata and checksum options. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object Post uploads one file and returns its `id` and, for public files, a CDN `url` you can embed or share directly. It backs attachments, generated exports and user-uploaded media for applications hosted on the platform. A single request accepts files from 512 bytes up to 100 MB. Larger files, up to **10 GiB**, go through the [chunked upload flow](/en/blob-reference/endpoint/chunked-init) or the [S3 gateway](/en/blob-reference/s3-compatibility). Requires the `blob:write` scope, or an [upload token](/en/blob-reference/endpoint/upload-tokens) sent in `Authorization`, and an active plan. Treat the returned `id` as **opaque**: store it as it comes and send it back to the other routes. It starts with `pub/` or `prv/` and can change when the file changes visibility or expiry. Legacy files, stored before the September 2026 update, keep ids without that prefix, and every route accepts both. ## Parameters Use FormData (`multipart/form-data`), exactly one file per request. Send a real filename: the stored extension comes from it (`reads.fastq.gz` stays `.fastq.gz`). The file name, without extension. 1 to 128 characters: letters, digits, `_`, `.` and `-`, starting with a letter, digit or `_`. It can't contain `..`. A folder path for the file, up to 8 segments separated by `/` and 256 characters in total. Each segment follows the same pattern as `name`, up to 64 characters. A trailing `/` is ignored. `true` stores the file without a public URL. Read it through [Object Download](/en/blob-reference/endpoint/download), a [share link](/en/blob-reference/endpoint/shares-create) or the [S3 gateway](/en/blob-reference/s3-compatibility). When omitted, the [rule for the prefix](/en/blob-reference/endpoint/settings-put) decides. Deletes the file automatically after this time: `30` or `30d` for days, `6h` for hours. From 1 hour to 1825 days (5 years). Expiries under 7 days need the Enterprise plan. When omitted, the rule for the prefix decides. `true` adds a random suffix to the name, so the URL can't be guessed and a new upload never replaces an old one. Private files always get it (`false` together with `private=true` is refused). Without a security hash, a new upload with the same name and prefix replaces the file. `false` refuses it with `409 OBJECT_ALREADY_EXISTS` instead. `inline` (open in the browser) or `attachment` (download, with the original file name). `true` makes browsers download the file instead of opening it, whatever its type. How long the CDN and browsers keep the file: `immutable` (1 year), `max-age=N` with N from 60 to 31536000 seconds, or `no-cache` (every read goes to storage; Enterprise only). Files with a security hash default to `immutable`. The cache never outlives the file's expiry. A JSON object of string values, returned by [Object Info](/en/blob-reference/endpoint/info). Keys use `a-z`, `0-9` and `-` (up to 64 characters). Up to 5 keys and 512 bytes in total. Pro and Enterprise only. The SHA-256 of the file. When it doesn't match, the upload is refused with `CHECKSUM_MISMATCH` and nothing is stored. ## Rate limits & concurrency * Every account may have at most **4 uploads in progress** at the same time (`TOO_MANY_CONCURRENT_UPLOADS`, 429). * **Hobby** and **Standard** plans are limited to **1 upload per second** (`RATE_LIMITED`, 429). **Pro** and **Enterprise** are exempt. * Uploads over the account's included storage are refused with `STORAGE_QUOTA_EXCEEDED`. ## File types Practically any extension is accepted, including formats with no registered MIME type (`.bam`, `.vcf`, `.fasta`, `.parquet`, `.h5`, `.npy` and so on). * The served `Content-Type` is derived server-side from the extension. Unknown formats are served as `application/octet-stream`. * Formats a browser renders (`.html`, `.svg`, `.xml` and similar) are always served as downloads. * Executables and installers are refused with `BLOCKED_FILE_TYPE`: `exe`, `msi`, `dll`, `bat`, `cmd`, `com`, `scr`, `cpl`, `pif`, `hta`, `vbs`, `vbe`, `jse`, `wsf`, `wsh`, `msc`, `reg`, `lnk`, `sys`, `drv`, `ps1`, `apk`, `xpi`. * A [rule for the prefix](/en/blob-reference/endpoint/settings-put) or an upload token can restrict the accepted extensions and size. ## Response "success" if successful, "error" if not. The object id: `pub//` or `prv//`. Treat it as opaque. Whether the file is private. The public CDN URL (`https://blob.squarecloud.dev/pub/...`), or `null` for private files. When the file will be deleted. Present only when it expires. The file size, in bytes. The name sent in the request. The prefix, when one was sent. The SHA-256 of the stored file, in hex. `true` when the upload replaced an existing file with the same name. ```bash cURL theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \ --header 'Authorization: YOUR_API_KEY' \ --form 'file=@./logo.png' ``` ```javascript JavaScript theme={"system"} import fs from 'node:fs'; const form = new FormData(); form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png'); const params = new URLSearchParams({ name: 'logo', prefix: 'images', security_hash: 'true', }); const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, { method: 'POST', headers: { Authorization: 'YOUR_API_KEY' }, body: form, }); ``` ```python Python theme={"system"} import requests with open('logo.png', 'rb') as f: response = requests.post( 'https://blob.squarecloud.app/v1/objects', headers={'Authorization': 'YOUR_API_KEY'}, params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'}, files={'file': ('logo.png', f, 'image/png')}, ) ``` ```json Public file theme={"system"} { "status": "success", "response": { "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "size": 416230, "name": "logo", "prefix": "images", "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef", "replaced": false } } ``` ```json Private file theme={"system"} { "status": "success", "response": { "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf", "private": true, "url": null, "size": 88412, "name": "2026-09", "prefix": "invoices", "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "replaced": false } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` | 400 | `name` or `prefix` doesn't match the pattern. | | `INVALID_OBJECT_EXPIRE` | 400 | `expire` is not a duration from 1 hour to 1825 days. | | `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | The flag is not `true` or `false`. | | `INVALID_OBJECT_SECURITY_HASH` | 400 | Not a boolean, or `false` on a private file. | | `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM` | 400 | The value is outside the accepted forms. | | `INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED` | 400 | The file part is missing, its extension is malformed or blocked, or the rule or token doesn't allow it. | | `FILE_TOO_SMALL` | 400 | The file has less than 512 bytes. | | `CHECKSUM_MISMATCH` | 400 | The file doesn't match `checksum_sha256`. Nothing was stored. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPLOAD_TOKEN_USED` | 401 | The upload token has no uses left. An expired token answers `ACCESS_DENIED`. | | `STORAGE_QUOTA_EXCEEDED` | 403 | The upload would pass the included storage. | | `PREFIX_NOT_ALLOWED` | 403 | The upload token is bound to another prefix. | | `UPGRADE_REQUIRED` | 403 | An option needs a higher plan. The `message` says which. | | `ACCOUNT_BLOCKED` | 403 | The account is blocked from storing files. | | `INVALID_CONTENT_TYPE` | 409 | The request is not `multipart/form-data`. | | `OBJECT_ALREADY_EXISTS` | 409 | The name exists and `overwrite=false`. | | `FILE_TOO_LARGE` | 413 | Past 100 MB, or past the size allowed by the rule or token. | | `RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS` | 429 | 1 upload per second (Hobby and Standard), or 4 in progress. | | `UPLOAD_FAILED` | 500 | Storage failed. Retry. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | Storage is temporarily unavailable. Retry. | See [Errors](/en/blob-reference/errors) for the full list. ## Related * Blob SDK: [`blob.put()`](/en/sdks/blob/uploads) # Get S3 credentials Source: https://docs.squarecloud.app/en/blob-reference/endpoint/s3-credentials GET https://blob.squarecloud.app/v1/s3/credentials Get the S3 access key pair of your API key with GET /v1/s3/credentials, to use aws-cli, boto3, rclone and the AWS SDKs with Blob Storage. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). S3 Credentials returns the access key pair that S3 tools use to sign requests to the [S3 gateway](/en/blob-reference/s3-compatibility). The pair is **derived from the API key** that calls this route: calling again returns the same pair, and revoking, regenerating or expiring the key does the same to the pair. There is nothing else to rotate or revoke. Call it with an API key that has `blob:read` or `blob:write`. The pair can read with `blob:read` and write with `blob:write`, as the `access` field shows. The `secret_access_key` gives the same access as the API key. Store it like the key itself. The pair doesn't change while the API key doesn't change. Fetch it once and keep it in your secret manager or in an environment variable: don't call this route every time your application boots. ## Rate limits 10 requests per hour per account (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The access key id (`SQ2_...`). The secret access key. `https://s3-blob.squarecloud.app` `auto` The buckets of your account: `public`, `private` and `legacy`. `read` and `write`, each `true` or `false`, following the key's scopes. When the API key, and so the pair, expires. `null` when it doesn't. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/s3/credentials' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "access_key_id": "SQ2_3155597145698959364_k7Hq2mX9", "secret_access_key": "vR8nLq2Wz5Tc1Yb7Hs0Kd4Jf6Gm3Pa9Xe", "endpoint": "https://s3-blob.squarecloud.app", "region": "auto", "buckets": ["public", "private", "legacy"], "access": { "read": true, "write": true }, "expires_at": null } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `API_KEY_REQUIRED` | 400 | Called with a dashboard session. Use an API key. | | `LEGACY_API_KEY` | 400 | The key uses an older format that can't sign S3 requests. Create a new API key. | | `INVALID_CREDENTIAL` | 401 | The API key could not be verified. | | `MISSING_SCOPE` | 403 | The key has neither `blob:read` nor `blob:write`. | | `RATE_LIMITED` | 429 | More than 10 requests in an hour. | ## Related * Blob SDK: [`blob.s3Credentials()`](/en/sdks/blob/s3), [`blob.s3()`](/en/sdks/blob/s3) # Get prefix rules Source: https://docs.squarecloud.app/en/blob-reference/endpoint/settings-get GET https://blob.squarecloud.app/v1/account/settings Read the per-prefix rules of your Blob Storage account with GET /v1/account/settings: default visibility, expiry and cache, size and type limits, auto-deletion. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Get Settings returns the rules saved with [Update Settings](/en/blob-reference/endpoint/settings-put). Each rule applies to the files under its prefix: default visibility, expiry and cache, size and type limits, and automatic deletion. Requires the `blob:read` scope. ## Response "success" if successful, "error" if not. The rules, as saved. See [Update Settings](/en/blob-reference/endpoint/settings-put) for each field. The prefix the rule applies to, ending in `/`. Default visibility. Default expiry. Maximum file size, in bytes. Accepted extensions. Default cache. Days after which files are deleted. When the rule was saved. When automatic deletion starts to act (24 hours after `created_at`). Present only with `delete_after_days`. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/account/settings' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "rules": [ { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" }, { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" } ] } } ``` ## Related * Blob SDK: [`blob.rules.get()`](/en/sdks/blob/rules_and_stats) # Set prefix rules Source: https://docs.squarecloud.app/en/blob-reference/endpoint/settings-put PUT https://blob.squarecloud.app/v1/account/settings Set rules per prefix with PUT /v1/account/settings: default visibility, expiry and cache, size and file type limits, and automatic deletion after N days. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Update Settings saves your rules, each applying to the files under a prefix. A rule sets defaults and limits once, for every upload under it, whether it comes from your backend, an [upload token](/en/blob-reference/endpoint/upload-tokens) or the dashboard. Requires the `blob:write` scope and an active plan. Each plan allows a number of rules: **5** on Hobby and Standard, **10** on Pro and **20** on Enterprise. Rules saved before a downgrade keep applying, but the next save must fit the new plan. The request **replaces the whole list**: send every rule you want to keep, and `{"rules": []}` removes them all. When several rules match a file, the one with the **longest prefix** wins. * **Defaults** (`private`, `expire`, `cache_control`) apply when the upload doesn't set its own value. * **Limits** (`max_size`, `extensions`) refuse uploads outside them with `FILE_TOO_LARGE` or `FILE_TYPE_NOT_ALLOWED`. They apply to REST uploads, not to the [S3 gateway](/en/blob-reference/s3-compatibility). * **Automatic deletion** (`delete_after_days`) deletes files a number of days after they were written. It applies to every file under the prefix, including files that already existed and files written over S3. Automatic deletion only starts **24 hours after the rule is saved** (`active_from` in [Get Settings](/en/blob-reference/endpoint/settings-get)), so you have a day to catch a prefix that is broader than intended. Saving an unchanged rule again keeps its original date. Once active, deleted files can't be recovered. ## Parameters Up to 5 rules on Hobby and Standard, 10 on Pro and 20 on Enterprise. The prefix, same pattern as in [Object Post](/en/blob-reference/endpoint/post). Saved with a trailing `/`, so `invoices` covers `invoices/...` and not `invoices-old/...`. Default visibility of new files. Default expiry of new files (`30d`, `6h`). Under 7 days needs Enterprise. Maximum file size in bytes, from 512 to 10737418240 (10 GiB). Accepted extensions, 1 to 50, lowercase and without the dot (`pdf`, `tar.gz`). Default cache: `immutable`, `max-age=N` or `no-cache` (Enterprise only). Deletes files this many days after they were written, from 1 to 3650. Under 7 needs Enterprise. If the plan changes to one that doesn't include a rule's option (for example an expiry under 7 days after leaving Enterprise), uploads under that prefix are refused with `UPGRADE_REQUIRED` until the rule is changed. ## Rate limits 10 requests per minute (`RATE_LIMITED`, 429). ## Response Returns the saved rules, in the same shape as [Get Settings](/en/blob-reference/endpoint/settings-get). ```bash cURL theme={"system"} curl --request PUT \ --url 'https://blob.squarecloud.app/v1/account/settings' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "prefix": "invoices", "private": true, "extensions": ["pdf"] }, { "prefix": "avatars", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400" }, { "prefix": "tmp", "delete_after_days": 7 } ] }' ``` ```json theme={"system"} { "status": "success", "response": { "rules": [ { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" }, { "prefix": "avatars/", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400", "created_at": "2026-09-25T12:00:00.000Z" }, { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" } ] } } ``` ## Errors Errors about one rule include its `prefix` in the response. | Code | HTTP | When | | - | - | - | | `INVALID_BODY` | 400 | The body is not a JSON object. | | `NOTHING_TO_UPDATE` | 400 | The body has no `rules`. | | `INVALID_RULES` | 400 | `rules` is not an array of objects. | | `TOO_MANY_RULES` | 400 | More than 20 rules on Enterprise. | | `INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX` | 400 | A prefix is malformed or repeated. | | `INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER` | 400 | A rule field is invalid. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPGRADE_REQUIRED` | 403 | More rules than the plan allows, or a rule uses an option that needs a higher plan. The `message` says the limit or the plan. | | `RATE_LIMITED` | 429 | More than 10 requests in a minute. | ## Related * Blob SDK: [`blob.rules.set()`](/en/sdks/blob/rules_and_stats) # Create a share link Source: https://docs.squarecloud.app/en/blob-reference/endpoint/shares-create POST https://blob.squarecloud.app/v1/shares Create a share link with POST /v1/shares: valid up to 30 days, revocable, with an optional download cap and, on Pro and Enterprise, a password. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Create Share makes a link (`https://files.squarecloud.dev/s/...`) to hand one file to people: a client, a team, a tester. It works for public and private files, lasts up to 30 days, can be revoked at any time and can limit how many times the file is downloaded. On **Pro and Enterprise** it can also ask for a password. Requires the `blob:write` scope. Opening the link downloads the file. A password-protected link first shows a page asking for the password, in the visitor's language. The link is tied to the file's current id: deleting, moving or changing the visibility of the file makes it answer `404` right away, without spending a download. See [Links and sharing](/en/blob-reference/links-and-sharing) for how it compares to temporary links. ## Parameters The id of the file to share. How long the link lasts, from 60 to 2592000 seconds (30 days). How many downloads the link allows, from 1 to 10000. Once spent, it answers `410`. Without it, there is no cap. A password of 8 to 128 characters the visitor must type before downloading. Pro and Enterprise only. For a **public** file the link redirects to its permanent public URL, which anyone who opens it can keep using. The password, the download cap and the expiry only truly protect **private** files. ## Limits * 30 links per minute (`RATE_LIMITED`, 429), and up to 1000 active links per account (`TOO_MANY_SHARES`, 409). * Each link accepts 120 visits per minute per IP. Wrong passwords are limited per IP and per link. * Downloading a private file goes through a temporary link: 60 requests per minute per IP, plus the overall limit of your account. To hand a file to many people, make it public. ## Response Answers `201 Created`. "success" if successful, "error" if not. The share id. Use it with [Delete Share](/en/blob-reference/endpoint/shares-delete). The link to hand out. When the link expires. The download cap, or `null`. Whether the link asks for a password. The id of the shared file. `true` when the file is public: anyone with its public URL can still download it, so revoking, capping or protecting the share doesn't restrict access to the file itself. ```bash cURL theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/shares' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "expires_in": 604800, "max_downloads": 5 }' ``` ```javascript JavaScript theme={"system"} const response = await fetch('https://blob.squarecloud.app/v1/shares', { method: 'POST', headers: { Authorization: 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf', expires_in: 7 * 24 * 60 * 60, max_downloads: 5, }), }); ``` ```json theme={"system"} { "status": "success", "response": { "id": "q8Zr2LwX7nT0vKc4Hs1YbA", "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA", "expires_at": "2026-10-02T12:00:00.000Z", "max_downloads": 5, "password": false, "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "object_is_public": false } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_OBJECT` | 400 | `object` is missing, malformed or not yours. | | `INVALID_EXPIRES_IN` | 400 | `expires_in` is not an integer from 60 to 2592000. | | `INVALID_MAX_DOWNLOADS` | 400 | `max_downloads` is not an integer from 1 to 10000. | | `INVALID_PASSWORD` | 400 | The password doesn't have 8 to 128 characters. | | `UPGRADE_REQUIRED` | 403 | Passwords need Pro or Enterprise. | | `OBJECT_NOT_FOUND` | 404 | The file doesn't exist. | | `TOO_MANY_SHARES` | 409 | The account has 1000 active links. Revoke some first. | | `RATE_LIMITED` | 429 | More than 30 links in a minute. | ## Related * Blob SDK: [`blob.shares.create()`](/en/sdks/blob/sharing) # Revoke a share link Source: https://docs.squarecloud.app/en/blob-reference/endpoint/shares-delete DELETE https://blob.squarecloud.app/v1/shares Revoke a Blob Storage share link with DELETE /v1/shares using its share id. The link answers 404 from then on, and the file itself is kept in storage. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Delete Share revokes a share link. The link answers `404` from then on, and the file itself is kept. Requires the `blob:write` scope. ## Parameters The share id, from [Create Share](/en/blob-reference/endpoint/shares-create) or [List Shares](/en/blob-reference/endpoint/shares-list). ## Response "success" if successful, "error" if not. ```bash cURL theme={"system"} curl --request DELETE \ --url 'https://blob.squarecloud.app/v1/shares' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "id": "q8Zr2LwX7nT0vKc4Hs1YbA" }' ``` ```json theme={"system"} { "status": "success" } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_SHARE` | 400 | `id` is missing or malformed. | | `SHARE_NOT_FOUND` | 404 | The link doesn't exist, expired or was already revoked. | ## Related * Blob SDK: [`blob.shares.revoke()`](/en/sdks/blob/sharing) # List share links Source: https://docs.squarecloud.app/en/blob-reference/endpoint/shares-list GET https://blob.squarecloud.app/v1/shares List the active share links of your account with GET /v1/shares, with the expiry, remaining downloads and password status of each link still valid. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). List Shares returns every share link of the account that hasn't expired or been revoked, with how many downloads each has left. Requires the `blob:read` scope. A link whose file was deleted, moved or changed visibility leaves the list the first time someone opens it. ## Rate limits 20 requests per minute (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The share id. The link. The id of the shared file. When the link expires. Downloads left, or `null` when there is no cap. Whether the link asks for a password. When the link was created. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/shares' \ --header 'Authorization: YOUR_API_KEY' ``` ```json theme={"system"} { "status": "success", "response": { "shares": [ { "id": "q8Zr2LwX7nT0vKc4Hs1YbA", "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA", "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "expires_at": "2026-10-02T12:00:00.000Z", "remaining_downloads": 3, "password": false, "created_at": "2026-09-25T12:00:00.000Z" } ] } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `RATE_LIMITED` | 429 | More than 20 requests in a minute. | ## Related * Blob SDK: [`blob.shares.list()`](/en/sdks/blob/sharing) # Get Blob Storage usage Source: https://docs.squarecloud.app/en/blob-reference/endpoint/stats GET https://blob.squarecloud.app/v1/account/stats Read your Blob Storage usage with GET /v1/account/stats: files, bytes, included storage, this month's average and the estimate of any storage beyond the quota. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Account Stats returns a snapshot of your Blob Storage usage: number of files, bytes stored, the storage included in your plan, this month's average usage and the estimated cost of anything held beyond the included storage (R\$ 0.20 per started GiB). Use it to build a usage meter or check headroom before a large batch of uploads. Requires the `blob:read` scope. The response is cached for 1 minute, and your own uploads and deletes clear that cache, so they show up right away. ## Rate limits 20 requests per minute, blocked for a short period past that (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. The number of files in your account. The total size of your files, in bytes. The storage included in your plan, in bytes. The storage beyond the included amount, in bytes. The estimated cost of that storage, in BRL (R\$ 0.20 per started GiB). Reserved for per-file pricing; always 0. The total estimate, in BRL. How many days of the current month (UTC) have a usage sample. The average of those daily samples, in bytes. ```bash cURL theme={"system"} curl --request GET \ --url 'https://blob.squarecloud.app/v1/account/stats' \ --header 'Authorization: YOUR_API_KEY' ``` ```json Response - [1m cache] theme={"system"} { "status": "success", "response": { "usage": { "objects": 1284, "storage": 3221225472 }, "plan": { "included": 5368709120 }, "billing": { "extraStorage": 0, "storagePrice": 0, "objectsPrice": 0, "totalEstimate": 0 }, "month": { "days": 24, "average_storage": 3006477107 } } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `RATE_LIMITED` | 429 | More than 20 requests in a minute. | ## Related * Blob SDK: [`blob.stats()`](/en/sdks/blob/rules_and_stats) # Update file options Source: https://docs.squarecloud.app/en/blob-reference/endpoint/update PATCH https://blob.squarecloud.app/v1/objects Change the visibility, expiry, cache, disposition or metadata of up to 50 files per request with PATCH /v1/objects, without uploading them again. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Object Update changes files already stored, without uploading them again: make them private or public, set or remove an expiry, and change the cache, disposition or metadata. It accepts one file or up to **50 per request**, all getting the same changes. Requires the `blob:write` scope. Changes are applied in the order of the fields below, each on the result of the previous one. Once the body is valid the route always answers `200`, with one result per file. **Changing `private` or `expire` changes the file's id** (and its URL, for public files). Store the new `id` from each result. Share links and temporary links to the old id stop working. The other fields keep the id. ## Parameters The id of one file. Send `object` or `objects`. Up to 50 ids. `true` makes the file private: the public copy is removed before the request answers, and the CDN drops it in about 60 seconds. `false` publishes it, which needs an active plan. See [Links and sharing](/en/blob-reference/links-and-sharing#making-a-file-private-or-public). A new expiry counted from now (`30d`, `6h`, `30`), or `null` to keep the file forever. Needs an active plan, and expiries under 7 days need Enterprise. `immutable`, `max-age=N` (60 to 31536000) or `no-cache` (Enterprise only). `null` removes the header and the CDN default applies. `inline` or `attachment` (download with the original file name). `null` removes the header. Keys to set or change. A key with a `null` value is removed, and `metadata: null` removes all of them. Up to 5 keys and 512 bytes after the change. Setting keys needs Pro or Enterprise; removing is always allowed. ## Legacy files Legacy files, uploaded before the September 2026 update (ids without `pub/` or `prv/`), can be made private and can get a new expiry: both move them to the new storage, with a new id. Their headers (`cache_control`, `disposition`, `metadata`) can't change in place and answer `OBJECT_IS_LEGACY`: move the file first with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`), then update it. ## Rate limits 50 files per 10 seconds, counted per file: one full batch of 50 uses the whole window (`RATE_LIMITED`, 429). ## Response "success" if successful, "error" if not. One entry per file, in the order sent. The id as sent in the request. Whether every change was applied to this file. Only when `ok` is `false`: why this file failed. Whether the id changed. The current id of the file. Store it. Whether the file is private. The public URL, or `null` for private files. The size of the file, in bytes. When the file will be deleted, or `null` when it doesn't expire. ```bash Make private theme={"system"} curl --request PATCH \ --url 'https://blob.squarecloud.app/v1/objects' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "private": true }' ``` ```bash Change headers theme={"system"} curl --request PATCH \ --url 'https://blob.squarecloud.app/v1/objects' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "objects": [ "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png" ], "cache_control": "max-age=3600", "metadata": { "campaign": "spring", "draft": null } }' ``` ```json Make private theme={"system"} { "status": "success", "response": { "results": [ { "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "ok": true, "changed": true, "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf", "private": true, "url": null, "size": 88412, "expires_at": null } ] } } ``` ```json With a failure theme={"system"} { "status": "success", "response": { "results": [ { "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "ok": true, "changed": false, "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png", "size": 416230, "expires_at": null }, { "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png", "ok": false, "code": "OBJECT_NOT_FOUND" } ] } } ``` ## Errors Errors of the whole request: | Code | HTTP | When | | - | - | - | | `INVALID_BODY` / `INVALID_OBJECT` | 400 | The body is not a JSON object, or an id is missing, malformed or not yours. | | `TOO_MANY_OBJECTS` | 400 | More than 50 ids. | | `NOTHING_TO_UPDATE` | 400 | No field to change was sent. | | `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA` | 400 | A field has an invalid value. | | `UPGRADE_REQUIRED` | 403 | A value needs a higher plan. The `message` says which. | | `RATE_LIMITED` | 429 | More than 50 files in 10 seconds. | Codes of a single file, in its result: | Code | When | | - | - | | `OBJECT_NOT_FOUND` | The file doesn't exist. | | `PERMISSION_DENIED` | Publishing or changing the expiry needs an active plan. | | `OBJECT_IS_LEGACY` | Header change on a legacy file. Move it first. | | `INVALID_OBJECT_METADATA` | The file would pass 5 keys or 512 bytes of metadata. | | `VISIBILITY_CHANGE_FAILED` | The public copy could not be removed: the file **is still public**. Retry. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | Storage is temporarily unavailable. Retry. | | `UPDATE_FAILED` | The change failed. Retry. | ## Related * Blob SDK: [`blob.update()`](/en/sdks/blob/objects) # Create an upload token Source: https://docs.squarecloud.app/en/blob-reference/endpoint/upload-tokens POST https://blob.squarecloud.app/v1/upload-tokens Mint a short-lived upload token with POST /v1/upload-tokens so a browser can upload straight to Blob Storage without your API key. The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security). Upload Tokens lets your **server** mint a short-lived token that a **browser** or mobile app uses to upload directly to Blob Storage. The file never passes through your server, and your API key never leaves it. Requires the `blob:write` scope and an active plan. The token goes in the `Authorization` header of [Object Post](/en/blob-reference/endpoint/post) or the [chunked upload](/en/blob-reference/endpoint/chunked-init) routes, and works nowhere else (`403 UPLOAD_TOKEN_NOT_ALLOWED`). Everything you set when minting it is **pinned**: the browser can't change the name, prefix, visibility, expiry or metadata, send a larger file, or use another file type. * Each upload spends one use: a call to Object Post, or opening a chunked upload (its parts and completion don't spend more). * Without a `name`, the browser picks it and the name always gets a security hash, so a leaked token can never replace your existing files. * The token stops working when its uses run out (`401 UPLOAD_TOKEN_USED`), when it expires or when the API key that minted it is revoked (`401 ACCESS_DENIED`). ## Parameters Pins the file name. Without it, the browser sends `name` in the query. Pins the prefix. A browser that sends a different one gets `403 PREFIX_NOT_ALLOWED`. Pins the visibility. Only with `name`: `false` lets the upload replace the file with that name. Otherwise the name always gets a hash. Pins the expiry (`30d`, `6h`), or `null` for none. Under 7 days needs Enterprise. Maximum file size in bytes, from 512 to 10737418240 (10 GiB). Accepted extensions, 1 to 20, lowercase and without the dot (`png`, `tar.gz`). Metadata added to every file uploaded with the token. Pro and Enterprise only. How long the token lasts, from 60 to 3600 seconds. How many uploads the token allows, from 1 to 100. ## Rate limits 120 tokens per minute (`RATE_LIMITED`, 429). Minting stores nothing, so one token per end-user upload is fine. ## Response "success" if successful, "error" if not. The upload token (`squp_...`). Hand it to the browser. When the token expires. How many uploads the token allows. ```javascript Server (Node.js) theme={"system"} // Your backend: mint a token for the signed-in user and return it to the page. const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', { method: 'POST', headers: { Authorization: process.env.SQUARE_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ prefix: `avatars/${userId}`, allowed_extensions: ['png', 'jpg', 'webp'], max_size: 2 * 1024 * 1024, expires_in: 300, }), }); const { response } = await res.json(); // send response.token to the browser ``` ```javascript Browser theme={"system"} const form = new FormData(); form.append('file', input.files[0]); const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', { method: 'POST', headers: { Authorization: token }, body: form, }); const { response } = await res.json(); // response.url is the public URL of the new file ``` ```bash cURL theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/upload-tokens' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }' ``` ```json theme={"system"} { "status": "success", "response": { "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb", "expires_at": "2026-09-25T12:15:00.000Z", "max_uses": 1 } } ``` ## Errors | Code | HTTP | When | | - | - | - | | `INVALID_BODY` | 400 | The body is not a JSON object. | | `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA` | 400 | A pinned value is invalid. | | `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES` | 400 | A limit is out of range. | | `UPLOAD_TOKEN_TOO_LARGE` | 400 | Too many options for one token. Shorten the metadata or the extension list. | | `PERMISSION_DENIED` | 401 | The account has no active plan. | | `UPGRADE_REQUIRED` | 403 | The expiry or metadata needs a higher plan. | | `RATE_LIMITED` | 429 | More than 120 tokens in a minute. | When the browser uploads: `401 UPLOAD_TOKEN_USED` (used up), `401 ACCESS_DENIED` (expired or revoked), `403 PREFIX_NOT_ALLOWED` (other prefix), `400 FILE_TYPE_NOT_ALLOWED` (extension not allowed) and `413 FILE_TOO_LARGE` (over `max_size`). ## Related * Blob SDK: [`blob.uploadTokens.create()`](/en/sdks/blob/uploads) # Blob Storage API error codes Source: https://docs.squarecloud.app/en/blob-reference/errors Every error code the Blob Storage API returns, with its HTTP status and what to do about it, plus when to retry with backoff and when to fix the request. Every error has the same shape. `code` is stable and meant for your code; `message`, when present, is a human explanation and may change. ```json theme={"system"} { "status": "error", "code": "UPGRADE_REQUIRED", "message": "Custom metadata is available on Pro and Enterprise plans only." } ``` Retry only on `429` and `5xx`, with backoff. Every `4xx` other than `429` means the request itself has to change. ## Authentication and limits | Code | HTTP | Meaning | | - | - | - | | `ACCESS_DENIED` | 401 | The credential is missing or was not recognized. | | `PERMISSION_DENIED` | 401 | The account has no active plan, which this action needs. | | `MISSING_SCOPE` | 403 | The API key lacks the scope this route needs. See [Authentication](/en/blob-reference/authentication#scopes). | | `RESOURCE_NOT_ALLOWED` | 403 | The API key is restricted to specific applications. | | `UPLOAD_TOKEN_NOT_ALLOWED` | 403 | Upload tokens only work on upload routes. | | `UPLOAD_TOKEN_USED` | 401 | The upload token has no uses left. An expired token answers `ACCESS_DENIED`. | | `ACCOUNT_BLOCKED` | 403 | The account is blocked from storing files. Contact support. | | `UPGRADE_REQUIRED` | 403 | The option is not part of your plan. The `message` names the plan that unlocks it. | | `RATE_LIMITED` | 429 | This route's own limit or the account-wide API budget was reached, or the IP sent too many invalid credentials. Wait and retry. | ## Objects | Code | HTTP | Meaning | | - | - | - | | `INVALID_OBJECT` | 400 | The object id is malformed or not yours. | | `INVALID_OBJECT_NAME` | 400 | `name` does not match the allowed pattern (1 to 128 characters). | | `INVALID_OBJECT_PREFIX` | 400 | `prefix` does not match the allowed pattern. | | `INVALID_OBJECT_EXPIRE` | 400 | `expire` is not a valid duration (1 hour to 1825 days). | | `INVALID_OBJECT_PRIVATE` | 400 | `private` is not `true` or `false`. | | `INVALID_OBJECT_SECURITY_HASH` | 400 | `security_hash` is not a boolean, or is `false` on a private object. | | `INVALID_OBJECT_OVERWRITE` | 400 | `overwrite` is not `true` or `false`. | | `INVALID_OBJECT_DISPOSITION` | 400 | `disposition` is not `inline` or `attachment`. | | `INVALID_OBJECT_CACHE_CONTROL` | 400 | `cache_control` is not `immutable`, `no-cache` or `max-age=60..31536000`. | | `INVALID_OBJECT_METADATA` | 400 | `metadata` is malformed, uses a reserved key, or passes 5 keys or 512 bytes. | | `INVALID_STORAGE_AUTO_DOWNLOAD` | 400 | `auto_download` is not `true` or `false`. | | `INVALID_CHECKSUM` | 400 | `checksum_sha256` is not 64 lowercase hex characters. | | `CHECKSUM_MISMATCH` | 400 | The file does not match `checksum_sha256`. Nothing was stored. | | `INVALID_DESTINATION` | 400 | The copy `destination` is malformed. | | `SAME_OBJECT` | 400 | The copy source and destination are the same object. | | `NOTHING_TO_UPDATE` | 400 | The request changes no field. | | `INVALID_CONTINUATION_TOKEN` | 400 | The list `cursor` is malformed or no longer valid. Start again without a cursor. | | `TOO_MANY_OBJECTS` | 400 | Too many objects in one request (100 to delete, 50 to update). | | `PREFIX_NOT_ALLOWED` | 403 | The upload token is bound to another prefix. | | `OBJECT_NOT_FOUND` | 404 | The object does not exist. | | `OBJECT_ALREADY_EXISTS` | 409 | An object with this id exists and `overwrite` is `false`. | | `OBJECT_IS_LEGACY` | per object | Returned in the `results` of [Object Update](/en/blob-reference/endpoint/update). The object is a legacy file, stored before the September 2026 update, and must be moved with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`) before its headers can change. | | `VISIBILITY_CHANGE_FAILED` | per object | Returned in the `results` of [Object Update](/en/blob-reference/endpoint/update): the object could not be made private and **is still public**. Retry. | | `UPDATE_FAILED` / `COPY_FAILED` / `DELETE_FAILED` | 500 | The operation failed. Retry. | ## Uploads | Code | HTTP | Meaning | | - | - | - | | `INVALID_CONTENT_TYPE` | 409 | [Object Post](/en/blob-reference/endpoint/post) only accepts `multipart/form-data` with exactly one file. | | `INVALID_FILE` | 400 | The file part is missing or unreadable. | | `INVALID_FILE_TYPE` | 400 | The file extension is malformed or too long. | | `BLOCKED_FILE_TYPE` | 400 | Executables and installers are not accepted. | | `FILE_TYPE_NOT_ALLOWED` | 400 | The upload token or the prefix rule does not allow this extension. | | `FILE_TOO_SMALL` | 400 | Files must have at least 512 bytes. | | `FILE_TOO_LARGE` | 413 | Past 100 MB in one request (use chunked uploads), or past the size allowed by the plan, token or rule. | | `STORAGE_QUOTA_EXCEEDED` | 403 | The account reached its included storage. | | `TOO_MANY_CONCURRENT_UPLOADS` | 429 | 4 uploads are already running on this account. | | `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503 | Storage is temporarily unavailable. Retry. | | `UPLOAD_FAILED` | 500 | The upload failed. Retry. | ## Chunked uploads | Code | HTTP | Meaning | | - | - | - | | `INVALID_UPLOAD_TOKEN` | 400 | The `upload` token is missing, malformed or not yours. | | `INVALID_CHUNK_PART` | 400 | `part` is not an integer from 1 to 2048. | | `EMPTY_CHUNK` | 400 | The part body is empty. | | `CHUNK_TOO_LARGE` | 413 | A part has more than 32 MB. | | `CHUNK_TOO_SMALL` | 400 | A part other than the last has less than 5 MB. | | `NO_CHUNKS_UPLOADED` | 400 | Complete was called before any part was sent. | | `TOO_MANY_OPEN_UPLOADS` | 429 | The account has 32 open uploads. Complete or abort one. | | `TOO_MANY_CONCURRENT_CHUNKS` | 429 | 6 parts are already in flight on this account. | | `UPLOAD_NOT_FOUND` | 404 | The upload was completed, aborted or expired. | ## Temporary links and shares | Code | HTTP | Meaning | | - | - | - | | `INVALID_DOWNLOAD_EXPIRES` | 400 | `expires` is outside 60 to 86400 seconds. | | `INVALID_FILENAME` | 400 | `filename` is empty after removing invalid characters. | | `INVALID_EXPIRES_IN` | 400 | `expires_in` is outside the allowed range. | | `INVALID_MAX_DOWNLOADS` | 400 | `max_downloads` is outside 1 to 10000. | | `INVALID_PASSWORD` | 400 | The password must have 8 to 128 characters. | | `INVALID_SHARE` | 400 | The share id is malformed. | | `SHARE_NOT_FOUND` | 404 | The share does not exist or was already revoked. | | `TOO_MANY_SHARES` | 409 | The account has 1000 active shares. Revoke some first. | ## Account settings and upload tokens | Code | HTTP | Meaning | | - | - | - | | `INVALID_BODY` | 400 | The body is missing or is not a JSON object. | | `INVALID_RULES` | 400 | `rules` is not an array. | | `TOO_MANY_RULES` | 400 | More than 20 rules on Enterprise. On other plans, passing the plan's limit (5 on Hobby and Standard, 10 on Pro) answers `UPGRADE_REQUIRED`. | | `INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX` | 400 | A rule prefix is malformed, or repeats another rule's. | | `INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER` | 400 | A rule field is invalid. The response carries the `prefix` of the rule. | | `INVALID_EXPIRES_IN` / `INVALID_MAX_USES` / `INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` | 400 | An upload token field is out of range. | | `UPLOAD_TOKEN_TOO_LARGE` | 400 | The token options don't fit in a token. Shorten metadata or the extension list. | ## S3 credentials | Code | HTTP | Meaning | | - | - | - | | `API_KEY_REQUIRED` | 400 | S3 credentials derive from an API key, not a dashboard session. | | `LEGACY_API_KEY` | 400 | The API key uses the old format. Create a new key in your account settings. | | `INVALID_CREDENTIAL` | 401 | The API key could not be verified. | The [S3 gateway](/en/blob-reference/s3-compatibility#errors) answers with standard S3 XML errors instead. ## Global | Code | HTTP | Meaning | | - | - | - | | `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | The route does not exist. | | `INTERNAL_SERVER_ERROR` | 500 | Unexpected failure. Retry later. | # Blob Storage links and sharing Source: https://docs.squarecloud.app/en/blob-reference/links-and-sharing Public URLs, temporary links and share links in Blob Storage: when to use each, how long they last and what happens when a file changes visibility. Blob Storage has three ways to hand a file to someone. Pick by how long the link must live and whether you need to take it back. | | Public URL | Temporary link | Share link | | - | - | - | - | | Created by | [Object Post](/en/blob-reference/endpoint/post) (public files) | [Object Download](/en/blob-reference/endpoint/download) | [Create Share](/en/blob-reference/endpoint/shares-create) | | Address | `blob.squarecloud.dev/pub/...` | `files.squarecloud.dev/d/...` | `files.squarecloud.dev/s/...` | | Works on | Public files | Public and private files | Public and private files | | Lifetime | While the file is public | 60 seconds to 24 hours | 60 seconds to 30 days | | Can be revoked | Make the file private | No | Yes | | Download cap | No | No | Optional, 1 to 10000 | | Password | No | No | Optional (Pro and Enterprise) | | Served from | Global CDN | Blob Storage | Blob Storage | ## Public URLs A public file has a permanent URL on the CDN: ``` https://blob.squarecloud.dev/pub// ``` Use it for assets you embed: images on a site, attachments in a bot, files other services fetch. Legacy files, stored before the September 2026 update, keep their URL on `https://public-blob.squarecloud.dev//` for 30 days, until October 25, 2026. Move them with [Object Copy](/en/blob-reference/endpoint/copy) (`move: true`) to get a URL on `blob.squarecloud.dev`. With `security_hash=true` (the default for private files and upload tokens without a name), the path gets a random suffix, so the URL can't be guessed from the name. ## Temporary links [Object Download](/en/blob-reference/endpoint/download) signs a link to one file, valid for 60 seconds up to 24 hours (default 1 hour). Use it to deliver a private file right now: a download button, an email attachment, a file your backend passes to another service. * The link needs no credential and **cannot be revoked**: it only stops working when it expires or when the file is deleted, moved or changes visibility. Keep the lifetime short. * It supports `Range` (resumable downloads and video seeking) and conditional requests (`If-None-Match`, `If-Modified-Since`). * You can force a download and pick the file name the browser saves (`disposition` and `filename`). * For a public file without those overrides, Object Download returns the public URL itself. * A link accepts 60 requests per minute per IP, on top of an overall limit for all the links of your account. Past that it answers `429` in plain text. To hand one file to many people, make it public: public files are served by the CDN, without this limit. An expired or invalid link answers `404`. ## Share links [Create Share](/en/blob-reference/endpoint/shares-create) makes a link with a page of its own, for people rather than programs: sending a file to a client, a report to a team, a build to a tester. * It lasts from 60 seconds to 30 days (default 24 hours). * It can be **revoked** at any time with [Delete Share](/en/blob-reference/endpoint/shares-delete), and is listed by [List Shares](/en/blob-reference/endpoint/shares-list). * `max_downloads` caps how many times the file can be downloaded. The count is exact, even under concurrent downloads. Once it runs out the link answers `410`. * On **Pro and Enterprise**, a `password` makes the page ask for it before the download. Wrong attempts are limited per IP and per link. A password link created before a downgrade keeps its password. * The page follows the visitor's browser language (English, Portuguese, Spanish, French, German, Italian, Japanese and Chinese). * The account can have up to 1000 active share links. * Downloading a private file goes through a temporary link, with the same limits: 60 requests per minute per IP, plus the overall limit of your account. A share link is tied to the file as it was when the link was created. Deleting the file, moving or renaming it, or changing its visibility makes the link answer `404` right away, before any password page and without spending a download. The next visit removes it from [List Shares](/en/blob-reference/endpoint/shares-list). A share link to a **public** file ends in a redirect to the file's permanent public URL. Whoever opens it gets that URL and can download the file again without going through the link, so the password, the download cap and the expiry only truly protect **private** files. When the protection matters, share a private file. ## Making a file private or public Change visibility with [Object Update](/en/blob-reference/endpoint/update) (`private: true` or `false`), or when copying with [Object Copy](/en/blob-reference/endpoint/copy). * The object **id changes**: `pub/...` becomes `prv/...` and the other way around. Store the new `id` from the response. * **Making a file private** removes the public copy before the request answers. Its public URL stops working, and CDN caches drop it in about 60 seconds. If the public copy can't be removed, the object answers `VISIBILITY_CHANGE_FAILED` and **stays public**, so you can retry. * **Making a file public** needs an active plan. Making it private is always allowed, even without a plan. * Share links and temporary links to the file stop working, since they point to the old id. Create new ones for the new id. A file that was public may have been downloaded or cached by others before you made it private. Upload sensitive files as private from the start (`private=true`). # Blob Storage API quickstart Source: https://docs.squarecloud.app/en/blob-reference/quickstart Upload and download your first file with the Blob Storage API: the v1 base URL, the Authorization header, a curl upload, its response and a download link. Blob Storage keeps your files, serves public ones from a CDN and hands out links to private ones. This page takes you from an API key to an uploaded file and a download link, with `curl`. Storage is included in every plan: see [Blob Storage](/en/services/blob) for the plans, prices and FAQ. ## Base URL Every endpoint of this reference is relative to: ```bash theme={"system"} https://blob.squarecloud.app/v1 ``` ## Authentication Blob Storage takes the same API keys as the [Square Cloud API](/en/api-reference/introduction), in the `Authorization` header. The key needs the `blob:write` scope to upload and `blob:read` to list and download, and it can't be restricted to specific applications. Create one in your [account security settings](https://squarecloud.app/en/account/security) and keep it in an environment variable: ```bash theme={"system"} export SQUARECLOUD_API_KEY="your-api-key" ``` More on scopes and upload tokens in [Authentication](/en/blob-reference/authentication). ## Upload a file [Object Post](/en/blob-reference/endpoint/post) takes the file as `multipart/form-data` and its name, without extension, in the query: ```bash theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \ --header "Authorization: $SQUARECLOUD_API_KEY" \ --form 'file=@./logo.png' ``` ```json theme={"system"} { "status": "success", "response": { "id": "pub/3155597145698959364/images/logo.png", "private": false, "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png", "size": 416230, "name": "logo", "prefix": "images", "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef", "replaced": false } } ``` The file is public by default: `url` works right away in a browser or an `` tag. Store the `id` as it comes, since every other route takes it. A single request takes files from 512 bytes to 100 MB. Larger files, up to 10 GiB, go through the [chunked upload](/en/blob-reference/endpoint/chunked-init) or the [S3 gateway](/en/blob-reference/s3-compatibility). ## Upload a private file Add `private=true` and the file gets no public URL (`url` is `null`): ```bash theme={"system"} curl --request POST \ --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \ --header "Authorization: $SQUARECLOUD_API_KEY" \ --form 'file=@./invoice.pdf' ``` ## Download a file A public file downloads from its `url`. For a private one, [Object Download](/en/blob-reference/endpoint/download) signs a temporary link that works without credentials, and redirects to it, so `curl -L` saves the file: ```bash theme={"system"} curl -L --output invoice.pdf \ --url 'https://blob.squarecloud.app/v1/objects/download?object=' \ --header "Authorization: $SQUARECLOUD_API_KEY" ``` Replace `` with the `id` of the upload. Add `redirect=false` to get the link as JSON and hand it to someone else. For links you can revoke or protect with a password, create a [share link](/en/blob-reference/endpoint/shares-create). ## List and delete files [Object List](/en/blob-reference/endpoint/list) returns your files page by page: ```bash theme={"system"} curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \ --header "Authorization: $SQUARECLOUD_API_KEY" ``` [Objects Delete](/en/blob-reference/endpoint/delete) removes one file, or up to 100 in one request: ```bash theme={"system"} curl --request DELETE \ --url 'https://blob.squarecloud.app/v1/objects' \ --header "Authorization: $SQUARECLOUD_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "object": "" }' ``` ## When something fails Errors come as `{ "status": "error", "code": "..." }`. The ones you are most likely to meet first: | Code | HTTP | Fix | | - | - | - | | `ACCESS_DENIED` | 401 | The key is missing or not recognized. Check the `Authorization` header. | | `PERMISSION_DENIED` | 401 | The account has no active plan, so it can't upload. | | `MISSING_SCOPE` | 403 | The key lacks `blob:write` or `blob:read`. Create a key with that scope. | | `RESOURCE_NOT_ALLOWED` | 403 | The key is restricted to applications. Use a key without that restriction. | | `FILE_TOO_LARGE` | 413 | The file is over 100 MB. Use the chunked upload. | Every code is in [Errors](/en/blob-reference/errors). ## Next steps Upload and manage files from JavaScript, with chunked uploads handled for you. Use aws-cli, boto3, rclone or any AWS SDK. Temporary links, share links and when to use each. Let visitors upload without exposing your API key. # Blob Storage S3 compatibility Source: https://docs.squarecloud.app/en/blob-reference/s3-compatibility Use aws-cli, boto3, rclone and the AWS SDKs with Blob Storage through the S3-compatible gateway: endpoint, buckets, supported operations and limits. Blob Storage speaks the S3 API at `https://s3-blob.squarecloud.app`. Any tool that lets you set a custom endpoint works: aws-cli, boto3, the AWS SDK for JavaScript, rclone, Cyberduck and most backup tools. ## Credentials S3 tools sign requests with an access key pair. Get it from [S3 Credentials](/en/blob-reference/endpoint/s3-credentials): ```bash theme={"system"} curl https://blob.squarecloud.app/v1/s3/credentials \ --header 'Authorization: YOUR_API_KEY' ``` The pair is **derived from your API key**. It needs no separate management: revoking or regenerating the key does the same to the pair, and the pair gets the same scopes. A key with only `blob:read` gives a read-only pair. The pair doesn't change while the API key doesn't change, so fetch it once and keep it in your secret manager or in an environment variable. Don't call the route on every boot: it accepts 10 requests per hour. | Setting | Value | | - | - | | Endpoint | `https://s3-blob.squarecloud.app` | | Region | `auto` | | Addressing | Path-style (`https://s3-blob.squarecloud.app//`) | | Signature | AWS Signature Version 4 | ## Buckets Your account sees three fixed buckets. You can't create or delete buckets. | Bucket | Contents | Access | | - | - | - | | `public` | Public files, served on `https://blob.squarecloud.dev/pub//` | Read and write | | `private` | Private files, with no public URL | Read and write | | `legacy` | Legacy files, uploaded before the September 2026 update | Read, list and delete | A key in the `public` or `private` bucket is the object path **without** your user id: `images/logo.png` in the `public` bucket is the object `pub//images/logo.png` on the REST API. Files written over S3 appear on the REST API and in the dashboard, and the other way around. ## Configuration ```bash aws-cli theme={"system"} aws configure set aws_access_key_id SQ2_... aws configure set aws_secret_access_key ... aws configure set region auto aws s3 cp ./logo.png s3://public/images/logo.png \ --endpoint-url https://s3-blob.squarecloud.app aws s3 ls s3://public/images/ --endpoint-url https://s3-blob.squarecloud.app ``` ```python boto3 theme={"system"} import boto3 from botocore.config import Config s3 = boto3.client( "s3", endpoint_url="https://s3-blob.squarecloud.app", aws_access_key_id="SQ2_...", aws_secret_access_key="...", region_name="auto", config=Config(signature_version="s3v4", s3={"addressing_style": "path"}), ) s3.upload_file("report.pdf", "private", "reports/2026/report.pdf") url = s3.generate_presigned_url( "get_object", Params={"Bucket": "private", "Key": "reports/2026/report.pdf"}, ExpiresIn=3600, ) ``` ```javascript AWS SDK v3 theme={"system"} import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; const s3 = new S3Client({ endpoint: "https://s3-blob.squarecloud.app", region: "auto", forcePathStyle: true, credentials: { accessKeyId: "SQ2_...", secretAccessKey: "..." }, }); await s3.send(new PutObjectCommand({ Bucket: "public", Key: "images/logo.png", Body: buffer, ContentType: "image/png", })); ``` ```ini rclone theme={"system"} [squarecloud] type = s3 provider = Other access_key_id = SQ2_... secret_access_key = ... endpoint = https://s3-blob.squarecloud.app region = auto force_path_style = true ``` boto3 needs `signature_version="s3v4"` for presigned URLs: without it, `generate_presigned_url` signs with the older SigV2, which the gateway doesn't accept. Presigned URLs last up to 7 days (604800 seconds). Gateway responses are never cached at the edge. A presigned URL stops working exactly when it expires, when the API key is revoked or when the object is deleted. ## Supported operations | Area | Operations | | - | - | | Buckets | `ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` on an existing bucket succeeds; `DeleteBucket` answers `BucketNotEmpty` while the bucket has files. | | Listing | `ListObjects` and `ListObjectsV2`, with `delimiter`, `prefix` and `encoding-type=url`. | | Objects | `HeadObject`, `GetObject` (with `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (up to 100 MB in one request), `CopyObject` (`COPY` and `REPLACE` metadata directives), `DeleteObject`, `DeleteObjects` (up to 1000 keys). | | Multipart | `CreateMultipartUpload`, `UploadPart` (5 MB to 80 MB per part, except the last one), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objects up to 10 GiB. | | Integrity | `Content-MD5` is always verified, even when an `x-amz-checksum-*` header is also sent. `x-amz-checksum-crc32`, `-sha1` and `-sha256` are verified too; a mismatch answers `BadDigest`. `crc32c` and `crc64nvme` are accepted without verification. `aws-chunked` bodies are supported. | | Compatibility | `GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` and the tagging reads answer fixed values so tools that probe them keep working. | Bucket policies, CORS, lifecycle, website, encryption, object lock, versions, logging, notifications, replication, ACL and tag writes, `GET` by `partNumber` and browser POST form uploads answer `501 NotImplemented`. Use [account settings](/en/blob-reference/endpoint/settings-put) for lifecycle rules. ## Keys * Keys are literal paths. A key can have up to about 1000 bytes: the 1024-byte limit counts the account prefix too. A longer key answers `KeyTooLongError`, and its message says the exact number of bytes you have. Segments can't be empty, `.` or `..`. * A 0-byte key ending in `/` is a folder marker, the way the AWS console creates folders. * The served `Content-Type` is derived from the extension, as on the REST API. Executables are refused with `InvalidArgument` and `.html`, `.svg` and `.xml` are served as downloads. ## Metadata, cache and expiry * `x-amz-meta-*` headers are kept on **Pro and Enterprise** (up to 5 keys and 512 bytes, otherwise `MetadataTooLarge`). On other plans they are dropped. * `Cache-Control` and `Content-Disposition` are kept. An uncached `Cache-Control` (`no-cache`, `no-store` or `max-age=0`) outside Enterprise is refused with `AccessDenied`. * [Rules per prefix](/en/blob-reference/endpoint/settings-put) apply to objects written over S3, including automatic deletion. A rule's `max_size` and `extensions` apply to REST uploads only. ## Limits | Limit | Value | | - | - | | Requests per account, every 10 seconds | **Hobby** 100 · **Standard** 200 · **Pro** 400 · **Enterprise** 600 | | Server-side copies (`CopyObject`, `UploadPartCopy`) | 20 per 10 seconds | | Keys deleted by `DeleteObjects` | 2000 per 10 seconds | | Open multipart uploads | 32 per account, shared with the REST chunked uploads | | Single `PutObject` | 100 MB | | Part (`UploadPart`) | 5 MB to 80 MB, except the last part | | Object size | 10 GiB | | Invalid credentials | Too many failures block the IP for a short period | Past a limit the gateway answers `SlowDown` (HTTP 503), and the AWS SDKs back off and retry on their own. S3 requests **don't count** against your plan's API request limit. Check the key pair before retrying in a loop: an IP that sends too many invalid credentials is blocked for a short period. ### Part size Multipart tools split big files on their own; keep each part at **80 MB or less**. The defaults of the AWS CLI (8 MB) and rclone (5 MB) already fit. ```bash aws-cli theme={"system"} aws configure set default.s3.multipart_chunksize 64MB ``` ```python boto3 theme={"system"} from boto3.s3.transfer import TransferConfig config = TransferConfig(multipart_chunksize=64 * 1024 * 1024) s3.upload_file("backup.tar.gz", "private", "backups/backup.tar.gz", Config=config) ``` ```javascript AWS SDK v3 theme={"system"} import { Upload } from "@aws-sdk/lib-storage"; await new Upload({ client: s3, params: { Bucket: "private", Key: "backups/backup.tar.gz", Body: stream }, partSize: 64 * 1024 * 1024, // up to 80 MB }).done(); ``` Writing needs an active plan. Without one, and on the read-only `legacy` bucket, writes answer `AccessDenied`. Storage quota applies as on the REST API. ## Errors The gateway answers standard S3 XML errors, so SDKs handle them natively: | Error | When | | - | - | | `AccessDenied` | No active plan, read-only key, write to `legacy`, or an option outside your plan. | | `NoSuchBucket` | The bucket is not `public`, `private` or `legacy`. | | `NoSuchKey` | The object does not exist. | | `InvalidArgument` | A blocked file type (executables and installers) or a malformed header. | | `QuotaExceeded` | The account reached its included storage. | | `EntityTooLarge` / `EntityTooSmall` | A `PutObject` over 100 MB, a part over 80 MB, or a part under 5 MB that isn't the last one. | | `InvalidPart` / `InvalidPartOrder` / `NoSuchUpload` | Multipart completion with bad parts, or an upload that no longer exists. | | `BadDigest` | The body doesn't match `Content-MD5` or the `x-amz-checksum-*` header. | | `PreconditionFailed` | An `If-Match` or `If-None-Match` condition failed. | | `MetadataTooLarge` | More than 5 metadata keys or 512 bytes. | | `KeyTooLongError` | The key is too long (about 1000 bytes). The message says the exact limit for your account. | | `SlowDown` | HTTP 503: a rate limit or the open upload limit was reached. SDKs retry with backoff on their own. | | `NotImplemented` | The operation is not supported (see above). |