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

# Read an application file

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

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

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

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

<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 query="path" type="string" placeholder="Example: src/index.js" required>
  The path to the file you want to read, relative to the root of your application. Up to 256 characters.
</ParamField>

<ParamField query="encoding" type="string" placeholder="base64">
  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.
</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 file.

  <Expandable title="Toggle object">
    <ResponseField name="encoding" type="string">
      Always `base64`.
    </ResponseField>

    <ResponseField name="data" type="string">
      The file, base64-encoded.
    </ResponseField>
  </Expandable>
</ResponseField>

Decode `data` to get the file's bytes:

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

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


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