Actions DSL

All commands are executed via POST /v1/browser/action with the action name and parameters.

{
  "session_id": "sess_xxxx",
  "action": "navigate",
  "params": { "url": "https://example.com" }
}

navigate

Navigate the browser to a URL.

Param	Type	Default	Description
url	string	required	Target URL including protocol
wait_until	string	networkidle	`load`, `domcontentloaded`, or `networkidle`
timeout_ms	number	30000	Max wait time in milliseconds

Result:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "status_code": 200,
  "load_time_ms": 847
}

Credit cost: 1

get_a11y_tree

Extract the accessibility tree from the current page. This is the primary tool for LLM consumption — 77% fewer tokens than a screenshot.

Param	Type	Default	Description
include_hidden	boolean	false	Include aria-hidden elements
root_selector	string	null	Scope to a specific CSS selector

Result:

{
  "tree": "- heading \"Example Domain\" [level=1]\n- link \"More information...\"",
  "node_count": 12,
  "estimated_tokens": 340
}

Credit cost: 1

click

Click an element by CSS selector or accessible label.

Param	Type	Default	Description
selector	string	null	CSS selector
label	string	null	Accessible name from a11y tree
button	string	left	`left`, `right`, or `middle`
click_count	number	1	Number of clicks
wait_after_ms	number	0	Wait after clicking (for animations)

Use label when possible — it's more reliable than CSS selectors across page changes.

Credit cost: 1

fill

Type text into an input, textarea, or contenteditable element.

Param	Type	Default	Description
selector	string	null	CSS selector
label	string	null	Accessible label
value	string	required	Text to type
clear_first	boolean	true	Clear existing value first

Credit cost: 1

select

Select an option from a <select> element.

Param	Type	Default	Description
selector	string	null	CSS selector
value	string	null	Option value
label_text	string	null	Visible option text

Credit cost: 1

scroll

Scroll the page or a specific element.

Param	Type	Default	Description
direction	string	down	`up`, `down`, `left`, `right`
amount	number	500	Pixels to scroll
selector	string	null	Scroll within a specific element

Credit cost: 1

wait_for

Wait for a condition before proceeding.

Param	Type	Description
type	string	`selector`, `text`, `url`, or `timeout`
value	string	CSS selector, text to find, URL pattern, or milliseconds
state	string	For selectors: `visible`, `hidden`, `attached`, `detached`
timeout_ms	number	Max wait time (default: 10000)

Credit cost: 0

screenshot

Capture a screenshot within an active session.

Param	Type	Default	Description
selector	string	null	Screenshot a specific element
full_page	boolean	false	Capture full scrollable page
format	string	png	`png` or `jpeg`

Result:

{
  "url": "https://s3.amazonaws.com/rove-artifacts/scr_xxxx.png?...",
  "expires_at": "2026-04-20T10:00:00Z"
}

Credit cost: 1

get_text

Extract text content from an element.

Param	Type	Description
selector	string	CSS selector
trim	boolean	Trim whitespace (default: true)

Result:

{ "text": "$49.99" }

Credit cost: 1

get_attribute

Get an attribute value from an element.

Param	Type	Description
selector	string	CSS selector
attribute	string	Attribute name (e.g. `href`, `src`)

Credit cost: 1

evaluate

Execute JavaScript in the browser context. Power-user escape hatch.

Param	Type	Description
expression	string	JavaScript expression to evaluate

Result:

{
  "value": 23,
  "type": "number"
}

Credit cost: 1

close_session

Close a session and trigger artifact upload (if video was recorded).

Returns artifact URLs if record_video was enabled.

Credit cost: 0

Credit Cost Summary

Action	Credits
navigate	1
get_a11y_tree	1
click	1
fill	1
select	1
scroll	1
wait_for	0
screenshot	1
get_text	1
get_attribute	1
evaluate	1
close_session	0