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

# Criar ou atualizar um arquivo da aplicação

> Crie ou sobrescreva um arquivo de uma aplicação com PUT /v2/apps/{app_id}/files. Envie conteúdo em base64 para binários, até 10 MB cada, sem reinício.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `files:write`.

Criar/modificar arquivo grava `content` em `path` dentro de uma aplicação em execução, criando o arquivo se ele não existir ou sobrescrevendo-o se existir. Para arquivos binários, envie `content` codificado em base64 junto com `encoding: "base64"`, o formato recomendado. `content` também aceita uma string UTF-8 para arquivos de texto, um array simples de bytes (`[104, 105]`) ou um objeto `{ type: "Buffer", data: number[] }`. Um `content` vazio (`""` ou `[]`) grava um arquivo vazio. Cada gravação aceita até 10 MB, medidos nos bytes decodificados. As gravações têm limite de 10 requisições a cada 5 segundos por usuário. Use-o para edições pequenas e pontuais, como ajustar um valor de configuração ou inserir um arquivo gerado, sem reenviar toda a aplicação; para alterações em massa ou um `.zip`, use [Enviar commit da aplicação](/pt-br/api-reference/endpoint/apps/commit).

Gravar em `squarecloud.app` ou `squarecloud.config` é tratado de forma especial: a plataforma interpreta o conteúdo como a configuração da aplicação (nome de exibição, descrição, memória, autorestart, subdomínio) e valida cada campo; um valor inválido retorna um código de erro específico (por exemplo, `INVALID_MEMORY` ou `INVALID_SUBDOMAIN`) em vez de gravar o arquivo. Essas regravações de configuração são limitadas a 1 requisição a cada 15 segundos por usuário.

Em aplicações compartilhadas em workspace, quem chama precisa da [função](/pt-br/api-reference/endpoint/workspace/members/invite#funções) `maintain` ou `admin`, e membros sem a permissão de arquivos restritos ficam bloqueados de gravar em caminhos excluídos como `.env`. Assim como outras rotas do gerenciador de arquivos, isso não reinicia a aplicação; chame [Reiniciar aplicação](/pt-br/api-reference/endpoint/apps/restart) para aplicar alterações que exijam um processo novo.

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

<ParamField body="path" type="string" required>
  O caminho onde o arquivo deve ser criado, com até 256 caracteres. Exemplo: /test.txt
</ParamField>

<ParamField body="content" type="string | number[]" required>
  O conteúdo do arquivo a ser criado: base64 quando `encoding` é `base64`; caso contrário, uma string UTF-8 ou um array de bytes.
</ParamField>

<ParamField body="encoding" type="string" placeholder="base64">
  Defina como `base64` quando `content` for o arquivo codificado em base64. Recomendado para arquivos binários.
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

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

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `INVALID_PATH` | 400 | O campo `path` falhou na validação (travessia, caracteres inválidos ou mais de 256 caracteres). |
| `INVALID_CONTENT` | 400 | `content` está ausente, não está em um dos formatos aceitos ou não é base64 válido quando `encoding` é `base64`. |
| `INVALID_DISPLAY_NAME` / `INVALID_DESCRIPTION` / `INVALID_MEMORY` / `INVALID_AUTORESTART` / `INVALID_SUBDOMAIN` | 400 | Um campo interpretado a partir de uma gravação em `squarecloud.app`/`squarecloud.config` falhou na validação. |
| `CANNOT_SET_SUBDOMAIN` | 400 | A configuração interpretada tentou definir um subdomínio que o plano ou a conta não pode usar. |
| `BLOCKED_PATH` | 403 | Quem chama não tem a permissão de workspace para gravar em um arquivo restrito. |
| `FILE_TOO_LARGE` | 413 | O `content` decodificado excede 10 MB; use Enviar commit da aplicação para arquivos maiores. |
| `KEEP_CALM` | 429 | Mais de 10 gravações em 5 segundos; aguarde alguns segundos e tente novamente. |
| `SAVE_FAILED` | 500 | Não foi possível persistir a atualização da configuração interpretada. |

## Relacionados

* CLI: [`squarecloud app file write`](/pt-br/cli-reference/files#squarecloud-app-file-write)
* SDKs: [`api.apps.files.write()`](/pt-br/sdks/js/managing_files) (JavaScript), [`client.apps.files.write()`](/pt-br/sdks/py/managing_files) (Python), [`c.Apps.Files.Write()`](/pt-br/sdks/go/managing_files) (Go)


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