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

# Downloads & Files

> Handling file downloads and uploads in automations

Optexity can download files from websites and upload files to forms.

## Download Methods

| Method               | Trigger                                     |
| -------------------- | ------------------------------------------- |
| Click download link  | `click_element` with `expect_download=true` |
| Select export option | `select_option` with `expect_download=true` |
| Save page as PDF     | `download_url_as_pdf`                       |

***

## Click to Download

```json theme={null}
{
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Download Report\")",
      "expect_download": true,
      "download_filename": "monthly_report.pdf"
    }
  }
}
```

| Property            | Type          | Default             | Description              |
| ------------------- | ------------- | ------------------- | ------------------------ |
| `expect_download`   | `bool`        | `False`             | Action triggers download |
| `download_filename` | `str \| None` | Auto-generated UUID | Filename for download    |

***

## Select to Download

```json theme={null}
{
  "interaction_action": {
    "select_option": {
      "command": "get_by_label(\"Export Format\")",
      "select_values": ["CSV"],
      "expect_download": true,
      "download_filename": "data.csv"
    }
  }
}
```

***

## Save Page as PDF

Capture current page or specific URL as PDF:

```json theme={null}
{
  "interaction_action": {
    "download_url_as_pdf": {
      "download_filename": "page_snapshot.pdf"
    }
  }
}
```

***

## Multiple Downloads

Use `for_loop_node` to download multiple files:

```json theme={null}
{
  "type": "for_loop_node",
  "variable_name": "doc_ids",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "get_by_text(\"{doc_ids[index]}\")",
        "expect_download": true,
        "download_filename": "doc_{doc_ids[index]}.pdf"
      }
    }
  }]
}
```

<Tip>
  Use variable substitution in `download_filename` to create unique filenames.
</Tip>

***

## Upload Files

The file source must be **exactly one** of `file_path` or `file_url`. Setting both, or neither, is rejected by the schema.

Upload from a local path:

```json theme={null}
{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_path": "/path/to/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}
```

Upload from a public URL (downloaded to a temp file just before upload, then cleaned up):

```json theme={null}
{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_url": "https://example.com/files/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}
```

| Property            | Description                                                                                                                                                                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command` / `xpath` | Locator for file input                                                                                                                                                                                                                                                                                                  |
| `file_path`         | Absolute or relative local path (supports variables)                                                                                                                                                                                                                                                                    |
| `file_url`          | Public `http://` or `https://` URL (supports variables). 120s download timeout. The automation fails if the download errors or returns a non-2xx status. The file extension is derived from the URL path, `Content-Disposition`, or `Content-Type` (in that order) so file inputs that check extensions still validate. |

***

## Download Storage

Downloaded files are stored in the task's downloads directory:

```
/tmp/optexity/{task_id}/downloads/
├── monthly_report.pdf
├── data.csv
└── doc_123.pdf
```

***

## Waiting for Downloads

Optexity automatically waits for downloads when `expect_download=true`. For large files, increase timing:

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "click_element": {
      "command": "get_by_text(\"Download Large File\")",
      "expect_download": true
    }
  },
  "end_sleep_time": 10.0
}
```

***

## Best Practices

| Practice                  | Recommendation                       |
| ------------------------- | ------------------------------------ |
| Set `expect_download`     | Always when download is expected     |
| Use descriptive filenames | Include IDs or dates                 |
| Handle large files        | Increase `end_sleep_time`            |
| Validate upload paths     | Ensure absolute paths are accessible |