List directory contents in a capsule

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

POST https://app.wrenn.dev/api/v1/capsules/{id}/files/list

Authentication

string

required

Your team’s API key. Pass the full wrn_... key value.

Path parameters

string

required

The ID of the capsule to list files in. The capsule must be in the running state.

Request body

string

required

Absolute path to the directory inside the capsule, e.g. "/home/user".

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.

Example request

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

{
  "path": "/home/user",
  "depth": 1
}

Response

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

object[]

Array of file and directory entries found at the specified path.

Show entry fields

string

The file or directory name (without the full path).

string

Full absolute path to the entry inside the capsule.

string

Entry type: "file", "directory", or "symlink".

integer

Size of the entry in bytes. For directories, this reflects the directory’s metadata size rather than total contents.

string

Human-readable permission string, e.g. "-rwxr-xr-x".

string

Owner username of the file.

string

Group name of the file.

integer

Unix timestamp (seconds) of the last modification time.

string

For symlinks, the path the link points to. null for regular files and directories.

Example response

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

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.

Capsules

Execution

Files

Snapshots

List directory contents in a capsule

Endpoint

Authentication

Path parameters

Request body

Example request

Response

Example response

Python SDK

Error responses

​Endpoint

​Authentication

​Path parameters

​Request body

​Example request

​Response

​Example response

​Python SDK

​Error responses

Endpoint

Authentication

Path parameters

Request body

Example request

Response

Example response

Python SDK

Error responses