> ## 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.

# Create Directories and Remove Files in a Capsule

> Use POST /v1/capsules/{id}/files/mkdir to create directories and POST /files/remove to delete files or directories inside a capsule.

Two endpoints let you manage the structure of a capsule's filesystem: one for creating directories and one for removing files or directories. Both require the capsule to be in the `running` state.

## Create a directory

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

Creates a directory at the specified path inside the capsule. Intermediate directories are created as needed (equivalent to `mkdir -p`).

### 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. The capsule must be in the `running` state.
</ParamField>

### Request body

<ParamField body="path" type="string" required>
  Absolute path of the directory to create inside the capsule, e.g. `"/app/data"`.
</ParamField>

### Example request

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

```json theme={null}
{"path": "/app/data"}
```

### Response

Returns `200 OK` with a `FileEntry` object describing the created directory.

<ResponseField name="entry" type="object">
  The created directory entry.

  <Expandable title="entry fields">
    <ResponseField name="name" type="string">
      Directory name.
    </ResponseField>

    <ResponseField name="path" type="string">
      Full absolute path of the created directory.
    </ResponseField>

    <ResponseField name="type" type="string">
      Always `"directory"`.
    </ResponseField>

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

    <ResponseField name="modified_at" type="integer">
      Unix timestamp (seconds) of creation time.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "entry": {
    "name": "data",
    "path": "/app/data",
    "type": "directory",
    "size": 4096,
    "permissions": "drwxr-xr-x",
    "owner": "user",
    "group": "user",
    "modified_at": 1730000000,
    "symlink_target": null
  }
}
```

***

## Remove a file or directory

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

Removes a file or directory at the specified path inside the capsule. Removal is recursive for directories — all contents are deleted.

<Warning>
  This operation is irreversible. Entire directory trees are removed without confirmation. Make sure you have a copy of any data you need before calling this endpoint.
</Warning>

### 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. The capsule must be in the `running` state.
</ParamField>

### Request body

<ParamField body="path" type="string" required>
  Absolute path to the file or directory to remove, e.g. `"/app/old"`.
</ParamField>

### Example request

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

```json theme={null}
{"path": "/app/old"}
```

### Response

Returns `204 No Content` on success. No body is returned.

***

## Python SDK

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

with Capsule(wait=True) as capsule:
    # Create a directory (and any needed parents)
    capsule.files.make_dir("/app/data")

    # Remove a file
    capsule.files.remove("/app/old-script.py")

    # Remove an entire directory tree
    capsule.files.remove("/app/old")
```

<Note>
  `remove` works recursively for directories. There is no `rmdir`-style safe guard — it behaves like `rm -rf`.
</Note>

## 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.        |