> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wrenn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List directory contents in a capsule

> POST /v1/capsules/{id}/files/list — List files and directories at a given path inside a capsule. Returns name, type, size, and modification time.

Use this endpoint to inspect the contents of a directory inside a running capsule. Each entry in the response includes the name, type, size, permissions, and last modification time. You can control how deep the listing recurses using the `depth` parameter.

## Endpoint

```http theme={null}
POST https://app.wrenn.dev/api/v1/capsules/{id}/files/list
```

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your team's API key. Pass the full `wrn_...` key value.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  The ID of the capsule to list files in. The capsule must be in the `running` state.
</ParamField>

## Request body

<ParamField body="path" type="string" required>
  Absolute path to the directory inside the capsule, e.g. `"/home/user"`.
</ParamField>

<ParamField body="depth" type="integer" default="1">
  Recursion depth for the listing. `0` returns only the directory itself (non-recursive); `1` returns its immediate children. Higher values recurse further into subdirectories.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://app.wrenn.dev/api/v1/capsules/cl-abc123/files/list \
  -H "X-API-Key: wrn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user", "depth": 1}'
```

```json theme={null}
{
  "path": "/home/user",
  "depth": 1
}
```

## Response

Returns `200 OK` with a JSON object containing an `entries` array.

<ResponseField name="entries" type="object[]">
  Array of file and directory entries found at the specified path.

  <Expandable title="entry fields">
    <ResponseField name="name" type="string">
      The file or directory name (without the full path).
    </ResponseField>

    <ResponseField name="path" type="string">
      Full absolute path to the entry inside the capsule.
    </ResponseField>

    <ResponseField name="type" type="string">
      Entry type: `"file"`, `"directory"`, or `"symlink"`.
    </ResponseField>

    <ResponseField name="size" type="integer">
      Size of the entry in bytes. For directories, this reflects the directory's metadata size rather than total contents.
    </ResponseField>

    <ResponseField name="permissions" type="string">
      Human-readable permission string, e.g. `"-rwxr-xr-x"`.
    </ResponseField>

    <ResponseField name="owner" type="string">
      Owner username of the file.
    </ResponseField>

    <ResponseField name="group" type="string">
      Group name of the file.
    </ResponseField>

    <ResponseField name="modified_at" type="integer">
      Unix timestamp (seconds) of the last modification time.
    </ResponseField>

    <ResponseField name="symlink_target" type="string">
      For symlinks, the path the link points to. `null` for regular files and directories.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "entries": [
    {
      "name": "main.py",
      "path": "/home/user/main.py",
      "type": "file",
      "size": 1024,
      "permissions": "-rw-r--r--",
      "owner": "user",
      "group": "user",
      "modified_at": 1730000000,
      "symlink_target": null
    },
    {
      "name": "data",
      "path": "/home/user/data",
      "type": "directory",
      "size": 4096,
      "permissions": "drwxr-xr-x",
      "owner": "user",
      "group": "user",
      "modified_at": 1730000100,
      "symlink_target": null
    }
  ]
}
```

## Python SDK

```python theme={null}
from wrenn import Capsule

with Capsule(wait=True) as capsule:
    # List immediate children of a directory
    entries = capsule.files.list("/home/user", depth=1)
    for entry in entries:
        print(entry.name, entry.type, entry.size)

    # Check whether a path exists
    if capsule.files.exists("/app/config.json"):
        print("config found")
```

## Error responses

| Status          | Meaning                                                                              |
| --------------- | ------------------------------------------------------------------------------------ |
| `404 Not Found` | The capsule does not exist, or the specified path does not exist inside the capsule. |
| `409 Conflict`  | The capsule is not in the `running` state. Resume or start the capsule first.        |