Skip to main content
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

​
X-API-Key
string
required
Your team’s API key. Pass the full wrn_... key value.

​
Path parameters

​
id
string
required
The ID of the capsule to list files in. The capsule must be in the running state.

​
Request body

​
path
string
required
Absolute path to the directory inside the capsule, e.g. "/home/user".
​
depth
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.
​
entries
object[]
Array of file and directory entries found at the specified path.

​
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

StatusMeaning
404 Not FoundThe capsule does not exist, or the specified path does not exist inside the capsule.
409 ConflictThe capsule is not in the running state. Resume or start the capsule first.