# list_files

Source: https://modulify.ai/docs/api/code/list-files

Lists the source files of a site with their sizes.

- Title: List the source files of a site
- Scope: `code:read`
- Access: Read only
- Endpoint: `POST /v1/list_files`

The files come from the preview branch of the site repository, not from the container the preview runs in, and that branch is only as fresh as the last sync. Straight after a generation you can see a file the agent has already replaced, or miss one it has just written.

Pass `path` to narrow the list to one folder. At most 2,000 entries come back, each with its `path` and `size`, while `total` reports how many matched, so `truncated:true` means you are seeing only part of the list and should narrow the path.

If the site repository cannot be read at that moment, the call fails with `Could not read your code from GitHub. Please try again in a moment!` instead of returning an empty list, so retry shortly rather than treating the site as empty. A site with no code yet answers `There is no code for this site yet!`

To change code, use `write_file` when you know exactly what the new file should contain, or describe the change to `send_message` and let the site agent edit it when the change depends on the surrounding code. See [Files and code](https://modulify.ai/docs/editor/files-and-code).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/list_files`, sending the inputs below as a JSON object. The token needs the `code:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/list_files \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'
```

Over MCP, the same method is the [list_files tool](https://modulify.ai/docs/mcp/code/list-files).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |
| `path` | string | No | Only list the files inside this folder, for example `app/` or `components/`. Folder names match whole, so `comp` does not match `components/`, and leading and trailing slashes are ignored. Leave it out to list the whole site. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.