Filling forms

Filling in a form and submitting it is the most common automation task. This guide shows the workflow that works across most pages, including animated forms and custom dropdowns. Every action runs through trusted, humanized events inside the profile’s anti-detect browser, so the form sees a real user.

All examples assume a launched profile whose id is in $PROFILE (see Launch profiles) and the automation base http://localhost:7891/api/automation/$PROFILE.

The workflow

Navigate to the page.
Snapshot to see the fields and their selectors.
Fill the page — set every field and submit in one call.
Re-snapshot only if the submit loaded a new page or step.

curl -s localhost:7891/api/automation/$PROFILE/navigate -X POST \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com/signin"}'

curl -s localhost:7891/api/automation/$PROFILE/snapshot -X POST | jq -r .data.snapshot

The snapshot is an accessibility tree with a [ref=eN] id for every element, plus roles and labels. Use it to pick selectors.

`fill-page` — the primary endpoint

fill-page fills all fields and submits in a single request. It clicks and types with real coordinates, so it works on animated pages where ordinary locators time out, and it handles dropdowns with auto-retry.

curl -s localhost:7891/api/automation/$PROFILE/fill-page -X POST \
  -H 'Content-Type: application/json' -d '{
    "fields": [
      {"selector": "#email", "value": "user@example.com"},
      {"selector": "#password", "value": "s3cret"},
      {"selector": "[role=combobox]", "value": "English", "type": "combobox"}
    ],
    "submit": {"text": "Sign in"},
    "waitAfterSubmit": 2000
  }'

Field options:

Option	Meaning
`selector` / `ref`	The element to fill. `ref` comes from a snapshot; `selector` is a CSS selector.
`type`	`"text"` (default) or `"combobox"` for ARIA dropdowns.
`nth`	When a selector matches several visible elements, pick the Nth (0-based).
`value`	The text to type, or the option label to choose.

submit clicks the matching button; waitAfterSubmit (ms) waits for the next page to settle before the call returns.

When to use the other endpoints

Endpoint	Use it for
`fill-page`	The default for any form — text fields, dropdowns and submit in one call.
`batch`	Non-form sequences — click links, hover, navigate, wait — or ref-based actions taken from a snapshot.
`fill-form`	Simple forms on well-behaved pages; tries a locator first, falls back to coordinates.

Dropdowns

Native <select> (shows as select in the snapshot) → select-option with the option values.
ARIA combobox (combobox role) → set type: "combobox" in fill-page, or call select-combobox.
Detached overlays — some sites render the option list outside the combobox. If select-combobox times out, don’t retry it. Open the dropdown with a real click, read the option’s coordinates with evaluate (reading only), then click them with mouse/click:

# open the dropdown
curl -s localhost:7891/api/automation/$PROFILE/click -X POST -d '{"ref":"e12"}'
# read the option's center (evaluate is read-only)
curl -s localhost:7891/api/automation/$PROFILE/evaluate -X POST -d '{"code":"const o=[...document.querySelectorAll(\"li[role=option]\")].find(e=>e.textContent.trim()===\"English\"); const r=o.getBoundingClientRect(); JSON.stringify({x:r.x+r.width/2,y:r.y+r.height/2})"}'
# click the coordinates (trusted, humanized)
curl -s localhost:7891/api/automation/$PROFILE/mouse/click -X POST -d '{"x":512,"y":340}'

Keyboard type-ahead is often simpler: open the combobox, then press-key the first letters of the option and Enter to commit.

Hard cases

Animated forms — fields move during CSS transitions, so locators report “not stable”. fill-page sidesteps this with coordinate input. The action timeout is short (2s), so a wrong path fails fast.
Offscreen submit button — if a submit button is below the fold, Tab to it from the last field and press Enter, or read its coordinates and mouse/click.
Multi-step forms — one fill-page per step, with waitAfterSubmit, then re-snapshot the next step. Reload between steps if the page leaves stale DOM behind.