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

# Upload application

> 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.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

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

<ParamField body="file" type="file" placeholder="application.zip" required>
  The application to be uploaded must be compressed in a zip file (.zip) and the Content-Type must be multipart/form-data.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `error` if not.
</ResponseField>

<ResponseField name="response" type="object">
  The contents of the response.

  <Expandable title="Toggle object">
    <ResponseField name="id" type="string">
      The ID of the uploaded application.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the uploaded application.
    </ResponseField>

    <ResponseField name="description" type="string">
      The description of the uploaded application.
    </ResponseField>

    <ResponseField name="domain" type="string">
      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.
    </ResponseField>

    <ResponseField name="ram" type="number">
      The memory allocated to the application, in MB.
    </ResponseField>

    <ResponseField name="cpu" type="number">
      The CPU allocated to the application.
    </ResponseField>

    <ResponseField name="language" type="object">
      <Expandable title="Toggle object">
        <ResponseField name="name" type="string">
          The detected runtime, in lowercase (for example `javascript`), as in Get Application Info.
        </ResponseField>

        <ResponseField name="version" type="string">
          The recommended version of the programming language.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cluster" type="string">
      The cluster where the application is cloud hosted.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```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')},
      )
  ```
</RequestExample>

<ResponseExample>
  ```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"
          }
      }
  }
  ```
</ResponseExample>

## 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.