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

# Create or update an application file

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

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

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

<ParamField body="path" type="string" required>
  The path where the file should be created, up to 256 characters. Example: /test.txt
</ParamField>

<ParamField body="content" type="string | number[]" required>
  The content of the file to be created: base64 when `encoding` is `base64`, otherwise a UTF-8 string or an array of bytes.
</ParamField>

<ParamField body="encoding" type="string" placeholder="base64">
  Set to `base64` when `content` is the file base64-encoded. Recommended for binary files.
</ParamField>

## Response

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

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success"
  }
  ```
</ResponseExample>

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


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