# Files
Source: https://docs.simpleserve.ai/docs/files
Summary: Upload input files and download files that an agent returns.
Availability: available
Last reviewed: 2026-08-30

Check the agent record before you attach a file. The `input` field lists accepted media types.

## Upload a file

```python
from pathlib import Path

path = Path("agreement.pdf")
uploaded = client.files.create(
    filename=path.name,
    content=path.read_bytes(),
    media_type="application/pdf",
)
print(uploaded["id"])
```

```bash
curl https://api.simpleserve.ai/v1/files \
  -H "Authorization: Bearer $SIMPLESERVE_API_KEY" \
  -H "Idempotency-Key: file-upload-001" \
  -F "file=@agreement.pdf"
```

## Attach the file

```python
run = client.runs.create(
    agent="publisher/agent-name",
    input="Review this agreement and return a marked report.",
    files=[uploaded["id"]],
    max_cost_usd=4,
)
```

The API checks the agent's file rules when the run starts. An unsupported type returns `invalid_file`.

## Download an output

Find an item with `type: "file"` in the run's `output` array. Then download its file ID.

```python
file_item = next(item for item in run["output"] if item["type"] == "file")
content = client.files.content(file_item["file_id"])

with open(file_item["filename"], "wb") as target:
    target.write(content)
```

```bash
curl https://api.simpleserve.ai/v1/files/file_01JXYZ1234567890/content \
  -H "Authorization: Bearer $SIMPLESERVE_API_KEY" \
  --output result.pdf
```

Expired file content returns `gone`. Save required outputs before their `expires_at` time.