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

# POST /v1/capsules/{id}/files/read — Download a file

> POST /v1/capsules/{id}/files/read — Download a file from inside a capsule. Returns raw binary content as application/octet-stream.

Use this endpoint to read a file from an absolute path inside a running capsule. The response is raw binary content with `Content-Type: application/octet-stream`. For large files, use the streaming variant to avoid loading the entire file into memory at once.

## Endpoint

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

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

## Request body

<ParamField body="path" type="string" required>
  Absolute path to the file inside the capsule, e.g. `"/app/output.json"`.
</ParamField>

### Example request

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

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

## Response

Returns `200 OK` with raw binary file content. The `Content-Type` header is `application/octet-stream`.

## Streaming download

For large files, use the streaming endpoint instead. It returns the file content using chunked transfer encoding, so you can process or write the data incrementally without buffering the whole file:

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

The request body is identical — a JSON object with a `path` field.

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

<Note>
  Use the streaming endpoint for large files to avoid loading the entire response into memory before writing it to disk.
</Note>

## Python SDK

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

with Capsule(wait=True) as capsule:
    # Read file content as a decoded string
    content = capsule.files.read("/app/output.json")
    print(content)

    # Read file content as raw bytes
    data = capsule.files.read_bytes("/app/image.png")

    # Stream a large file to disk without buffering
    with open("large-output.bin", "wb") as f:
        for chunk in capsule.files.download_stream("/data/large-output.bin"):
            f.write(chunk)
```

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