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

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

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

Authentication

string

required

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

Path parameters

string

required

The ID of the capsule to read the file from. The capsule must be in the running state.

Request body

string

required

Absolute path to the file inside the capsule, e.g. "/app/output.json".

Example request

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

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

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

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

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

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

Python SDK

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.

Capsules

Execution

Files

Snapshots

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

Endpoint

Authentication

Path parameters

Request body

Example request

Response

Streaming download

Python SDK

Error responses

​Endpoint

​Authentication

​Path parameters

​Request body

​Example request

​Response

​Streaming download

​Python SDK

​Error responses

Endpoint

Authentication

Path parameters

Request body

Example request

Response

Streaming download

Python SDK

Error responses