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

# List Directory

> List the contents of a directory on the instance.

Lists the files and subdirectories at a given path on the instance. Defaults to the root directory (`.`) if no path is specified.

## Authentication

Requires an **org-level API key** or a **scoped token** with the appropriate permission.

## Path Parameters

<ParamField path="instance_id" type="string" required>
  The ID of the instance.
</ParamField>

## Query Parameters

<ParamField query="path" type="string" default=".">
  The directory path to list, relative to the instance root.
</ParamField>

## Response

<ResponseField name="path" type="string">
  The directory path that was listed.
</ResponseField>

<ResponseField name="entries" type="array">
  <Expandable title="Entry object">
    <ResponseField name="name" type="string">
      The file or directory name.
    </ResponseField>

    <ResponseField name="path" type="string">
      The full path relative to the instance root.
    </ResponseField>

    <ResponseField name="is_dir" type="boolean">
      Whether this entry is a directory.
    </ResponseField>

    <ResponseField name="size" type="integer">
      File size in bytes. `0` for directories.
    </ResponseField>

    <ResponseField name="mod_time" type="string">
      Last modification timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="permissions" type="string">
      Unix-style permission string (e.g. `"-rw-r--r--"`).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X GET "https://api.chowder.dev/v1/instances/ins_abc123/files?path=skills" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "path": "skills",
    "entries": [
      {
        "name": "web-search",
        "path": "skills/web-search",
        "is_dir": true,
        "size": 0,
        "mod_time": "2026-01-15T10:30:00Z",
        "permissions": "drwxr-xr-x"
      },
      {
        "name": "openclaw.json",
        "path": "skills/openclaw.json",
        "is_dir": false,
        "size": 1024,
        "mod_time": "2026-01-15T09:00:00Z",
        "permissions": "-rw-r--r--"
      }
    ]
  }
  ```
</ResponseExample>