Optexity uses a declarative model for browser automation. Define what actions to perform, and Optexity handles the how using AI-assisted element location.
Overview
Automation
├── url # Starting point
├── browser_channel # "chromium" or "chrome"
├── os_emulation # OS to emulate: "windows", "linux", or null
├── max_retries # Total run attempts on failure (default: 1)
├── expected_downloads # Number of files to download
├── parameters # Input, secure, and generated variables
└── nodes[] # Sequence of actions
├── action_node
├── for_loop_node
└── if_else_node
Complete Example
{
"url": "https://example.com/login",
"browser_channel": "chromium",
"os_emulation": null,
"max_retries": 1,
"expected_downloads": 0,
"parameters": {
"input_parameters": {
"email": ["user@example.com"]
},
"secure_parameters": {},
"generated_parameters": {}
},
"nodes": [
{
"type": "action_node",
"interaction_action": {
"input_text": {
"command": "get_by_label(\"Email\")",
"input_text": "{email[0]}"
}
}
}
]
}
Properties
| Property | Type | Default | Description |
|---|
url | str | — | Starting URL—use the URL closest to your target to reduce navigation steps |
browser_channel | "chromium" | "chrome" | "chromium" | Browser to use |
os_emulation | "windows" | "linux" | null | null | OS user-agent to emulate; null uses the default system OS |
max_retries | int | 0 | Total number of run attempts. 0 = no retry, 1 = one retry, etc. |
expected_downloads | int | 0 | Number of expected downloads (automation waits for completion) |
parameters | Parameters | — | Input, secure, and generated variables |
nodes | list[action_node | for_loop_node | if_else_node] | — | Ordered list of actions |
Parameters
Three types of parameters control data flow:
| Type | Purpose | Example |
|---|
input_parameters | Values provided before execution | Username, search queries |
secure_parameters | Sensitive data from secure storage | Passwords, API keys |
generated_parameters | Values extracted during execution | Order IDs, confirmation numbers |
{
"parameters": {
"input_parameters": {
"username": ["admin@example.com"]
},
"secure_parameters": {
"password": [{
"onepassword": {
"vault_name": "vault",
"item_name": "login",
"field_name": "password"
}
}]
},
"generated_parameters": {
"order_ids": []
}
}
}
Node Types
| Node | Purpose | Documentation |
|---|
action_node | Single atomic action | Action Node |
for_loop_node | Iterate over values | For Loop Node |
if_else_node | Conditional execution | If Else Node |
Browser Channel
| Channel | Use When |
|---|
"chromium" | Default, works for most sites |
"chrome" | Site requires Chrome specifically, or automation is unreliable with Chromium |
{
"browser_channel": "chrome"
}
Expected Downloads
Set this to wait for file downloads to complete:
{
"expected_downloads": 3
}
OS Emulation
Override the OS reported in the browser’s user-agent string:
| Value | Use When |
|---|
null | Default — uses the host system’s OS (recommended for most sites) |
"windows" | Site behaves differently on Windows (e.g. Windows-only portals) |
"linux" | Site behaves differently on Linux |
{
"os_emulation": "windows"
}
Only set os_emulation when a site serves different content or layouts based on the OS. Leave it as null otherwise.
Max Retries
Control how many times the full automation reruns when an unexpected error occurs:
| Value | Behavior |
|---|
1 (default) | Runs once; fails immediately on error |
2 | Runs up to twice (1 retry) |
3 | Runs up to three times (2 retries) |
max_retries is the total number of attempts, not the number of extra retries. AssertionError failures are never retried regardless of this value.
See Timing & Retries for controlling per-element retry behavior (max_tries) vs. full-automation retries (max_retries). 
