Automation Structure

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
├── reuse_page_if_already_on_url   # Skip navigation when already on url (dedicated only)
├── parameters           # Input, secure, and generated variables
└── nodes[]              # Sequence of actions
    ├── action_node
    ├── for_loop_node
    ├── if_else_node
    └── private_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)
`reuse_page_if_already_on_url`	`bool`	`false`	Start on the existing page instead of navigating, when a dedicated browser is already on `url`. See Reuse Page If Already On URL
`parameters`	`Parameters`	—	Input, secure, and generated variables
`nodes`	`list[action_node \| for_loop_node \| if_else_node \| private_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": []
    }
  }
}

See Parameters for detailed usage.

Node Types

Node	Purpose	Documentation
`action_node`	Single atomic action	Action Node
`for_loop_node`	Iterate over list values or locator matches	For Loop Node
`if_else_node`	Conditional execution	If Else Node
`private_node`	Closed-source handler, runs only on Optexity’s servers	Private 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
}

The automation waits until all expected files are downloaded before completing.

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:

{
  "max_retries": 3
}

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

Reuse Page If Already On URL

Every run navigates to url before the first node executes, even on a warm dedicated instance. Set reuse_page_if_already_on_url to leave the existing page untouched when the reused browser is already sitting on url:

{
  "reuse_page_if_already_on_url": true
}

Use this only for portals that break when their page is reloaded — some session-bound portals throw an error or invalidate the session on any refresh, so the safest thing is not to navigate at all.

Condition	Behavior
Dedicated run, browser already on `url`	Nodes start on the existing page; no navigation
URL differs, or the page is unresponsive	Normal navigation to `url`
Non-dedicated run	Normal navigation to `url` (flag has no effect)

The URL comparison is exact on scheme, host, path, query string, and fragment — only a trailing slash on the path is ignored. A hash-routed portal on #/dashboard therefore does not match a url of #/home. Anything that doesn’t match falls back to normal navigation, so enabling the flag can never leave a run stranded.

Your first node now runs against whatever the previous task left behind — an open modal, a filled form, a scrolled list. Make it tolerant of a mid-session page, or pair it with an if-else node that resets the portal to a known state.

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Overview

Complete Example

Properties

Parameters

Node Types

Browser Channel

Expected Downloads

OS Emulation

Max Retries

Reuse Page If Already On URL

​Overview

​Complete Example

​Properties

​Parameters

​Node Types

​Browser Channel

​Expected Downloads

​OS Emulation

​Max Retries

​Reuse Page If Already On URL

Overview

Complete Example

Properties

Parameters

Node Types

Browser Channel

Expected Downloads

OS Emulation

Max Retries

Reuse Page If Already On URL