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

# Ler um arquivo da aplicação

> Leia um arquivo de até 10 MB de uma aplicação com GET /v2/apps/{app_id}/files/content. Envie encoding=base64, já que o formato Buffer foi descontinuado.

<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:read`.

Ler arquivo retorna um único arquivo dentro de uma aplicação em execução como JSON. Envie `?encoding=base64` para receber o arquivo como uma string base64. É indicado para inspecionar ou baixar arquivos individuais (configurações, logs, assets pequenos) de até 10 MB através da API, não para transferências em massa: use [Criar snapshot](/pt-br/api-reference/endpoint/apps/snapshots/create) para obter uma cópia completa da aplicação.

<Warning>
  Sem `encoding`, a resposta é o objeto legado `{ type: "Buffer", data: number[] }`. Esse formato está **obsoleto desde 27 de setembro de 2026** e será removido em **27 de março de 2027**, quando base64 passará a ser o padrão. Até lá, as respostas legadas trazem os headers `Deprecation` e `Sunset`. Envie `?encoding=base64` em toda requisição.
</Warning>

Para ver o que está disponível antes de ler, chame [Listar arquivos](/pt-br/api-reference/endpoint/apps/filemanager/list) primeiro. Para gravar um arquivo de volta, use [Criar/modificar arquivo](/pt-br/api-reference/endpoint/apps/filemanager/put), que recebe o mesmo conteúdo base64 com `encoding: "base64"`.

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 não podem ler `.env` ou `.env.production`; a requisição é rejeitada com `PERMISSION_DENIED` antes de o arquivo ser tocado.

## 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 query="path" type="string" placeholder="Exemplo: src/index.js" required>
  O caminho para o arquivo que você deseja ler, relativo à raiz da sua aplicação. Até 256 caracteres.
</ParamField>

<ParamField query="encoding" type="string" placeholder="base64">
  Envie `base64` para receber o arquivo como uma string base64. Qualquer outro valor responde `INVALID_ENCODING`. Sem ele, a resposta usa o formato Buffer obsoleto.
</ParamField>

## Resposta

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

<ResponseField name="response" type="object">
  O conteúdo do arquivo.

  <Expandable title="Alternar objeto">
    <ResponseField name="encoding" type="string">
      Sempre `base64`.
    </ResponseField>

    <ResponseField name="data" type="string">
      O arquivo, codificado em base64.
    </ResponseField>
  </Expandable>
</ResponseField>

Decodifique `data` para obter os bytes do arquivo:

<CodeGroup>
  ```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)
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success",
      "response": {
          "encoding": "base64",
          "data": "Y29uc29sZS5sb2coIkhlbGxvLCBTcXVhcmUgQ2xvdWQhIik7Cg=="
      }
  }
  ```
</ResponseExample>

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `INVALID_PATH` | 400 | O parâmetro de consulta `path` falhou na validação (travessia, caracteres inválidos ou mais de 256 caracteres). |
| `INVALID_ENCODING` | 400 | `encoding` tem um valor diferente de `base64`. |
| `PERMISSION_DENIED` | 403 | Quem chama não tem a permissão de workspace para ler um arquivo restrito (`.env`, `.env.production`). |
| `FILE_NOT_FOUND` | 404 | Não existe nenhum arquivo no caminho informado. |
| `FILE_TOO_LARGE` | 413 | O arquivo é maior que 10 MB, o máximo que o gerenciador de arquivos lê. |

## Relacionados

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


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