Commands

POST /commands executes tagged browser commands in order.

Use it when you want precise, stateful browser automation against a session.

Request shape

curl -X POST https://api.browsr.dev/commands \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "headless": true,
    "commands": [
      {"command": "navigate_to", "data": {"url": "https://example.com"}},
      {"command": "get_title"}
    ]
  }'

Top-level fields:

Field	Type	Required	Description
`commands`	array	Yes	Ordered list of tagged commands
`session_id`	string	No	Reuse an existing browser or relay session
`headless`	boolean	No	Session creation hint when Browsr auto-creates a session
`context`	object	No	Extra thread/task metadata for agent-style execution

Each command is encoded as:

{"command":"command_name","data":{"field":"value"}}

Commands without arguments omit data:

{"command":"get_title"}

Response shape

{
  "success": true,
  "steps_completed": 2,
  "total_steps": 2,
  "results": [
    {"success": true, "command_type": "action"},
    {
      "success": true,
      "command_type": "extraction",
      "content_type": "data",
      "data": {"result": {"type": "string", "value": "Example Domain"}}
    }
  ]
}

Supported commands

Utility overlays

`toggle_click_overlay`

{"command":"toggle_click_overlay","data":{"enabled":true}}

`toggle_bounding_boxes`

Minimal:

{"command":"toggle_bounding_boxes","data":{"enabled":true}}

Scoped:

{
  "command":"toggle_bounding_boxes",
  "data":{
    "enabled":true,
    "selector":"button, a",
    "limit":20,
    "include_html":false
  }
}

`navigate_to`

{"command":"navigate_to","data":{"url":"https://example.com"}}

`refresh`

{"command":"refresh"}

`wait_for_navigation`

Default timeout:

{"command":"wait_for_navigation"}

Custom timeout:

{"command":"wait_for_navigation","data":{"timeout_ms":10000}}

`wait_for_element`

Basic:

{"command":"wait_for_element","data":{"selector":"main"}}

Visible-only:

{
  "command":"wait_for_element",
  "data":{"selector":".dashboard","timeout_ms":10000,"visible_only":true}
}

Basic interaction

`click`

{"command":"click","data":{"selector":"button[type=submit]"}}

`click_at`

{"command":"click_at","data":{"x":640,"y":320}}

`clear`

{"command":"clear","data":{"selector":"input[name=email]"}}

`press_key`

{"command":"press_key","data":{"selector":"input[name=q]","key":"Enter"}}

Content and page info

`get_content`

Whole page markdown:

{"command":"get_content"}

Selector-scoped markdown:

{"command":"get_content","data":{"selector":"main","kind":"markdown"}}

HTML:

{"command":"get_content","data":{"selector":"article","kind":"html"}}

JSON:

{"command":"get_content","data":{"selector":"script[type=\"application/ld+json\"]","kind":"json"}}

`get_text`

{"command":"get_text","data":{"selector":"h1"}}

`get_attribute`

{"command":"get_attribute","data":{"selector":"a.primary","attribute":"href"}}

`get_title`

{"command":"get_title"}

`extract_structured_content`

Prompt only:

{
  "command":"extract_structured_content",
  "data":{"query":"Extract all visible product names"}
}

With schema:

{
  "command":"extract_structured_content",
  "data":{
    "query":"Extract product cards",
    "schema":{
      "type":"array",
      "items":{
        "type":"object",
        "properties":{
          "name":{"type":"string"},
          "price":{"type":"string"}
        }
      }
    },
    "max_chars":12000
  }
}

JavaScript and inspection

`evaluate`

{"command":"evaluate","data":{"expression":"document.title"}}

`get_bounding_boxes`

{
  "command":"get_bounding_boxes",
  "data":{"selector":"button","limit":10,"include_html":false}
}

`inspect_element`

{"command":"inspect_element","data":{"selector":"#hero"}}

Mouse and scroll

`scroll_to`

Vertical scroll:

{"command":"scroll_to","data":{"y":1200}}

Two-axis scroll:

{"command":"scroll_to","data":{"x":0,"y":600}}

`move_mouse_to`

Instant:

{"command":"move_mouse_to","data":{"x":400,"y":240}}

Human-like:

{"command":"move_mouse_to","data":{"x":400,"y":240,"steps":18}}

`drag`

{
  "command":"drag",
  "data":{
    "from":{"x":120,"y":220},
    "to":{"x":480,"y":220},
    "modifiers":0
  }
}

`scroll_into_view`

{"command":"scroll_into_view","data":{"selector":"footer"}}

Element-focused interactions

`click_advanced`

{
  "command":"click_advanced",
  "data":{"selector":"button.buy","button":"left","click_count":2,"modifiers":0}
}

`type_text`

{
  "command":"type_text",
  "data":{"selector":"input[name=email]","text":"user@example.com","clear":true}
}

`hover`

{"command":"hover","data":{"selector":".menu-trigger"}}

`focus`

{"command":"focus","data":{"selector":"textarea"}}

`check`

{"command":"check","data":{"selector":"input[type=checkbox]"}}

`select_option`

{"command":"select_option","data":{"selector":"select[name=country]","values":["SG"]}}

`drag_to`

By selector:

{
  "command":"drag_to",
  "data":{"selector":".card","target_selector":".dropzone"}
}

By explicit positions:

{
  "command":"drag_to",
  "data":{
    "selector":".card",
    "source_position":{"x":10,"y":10},
    "target_position":{"x":120,"y":40},
    "modifiers":0
  }
}

`evaluate_on_element`

{
  "command":"evaluate_on_element",
  "data":{"selector":"#hero","expression":"function(){ return this.innerText; }"}
}

`get_element_bounding_box`

{"command":"get_element_bounding_box","data":{"selector":"#hero"}}

`element_screenshot`

PNG:

{"command":"element_screenshot","data":{"selector":".hero"}}

JPEG:

{"command":"element_screenshot","data":{"selector":".hero","format":"jpeg","quality":80}}

`get_basic_info`

{"command":"get_basic_info","data":{"selector":"#hero"}}

Screenshots

`screenshot`

Viewport screenshot:

{"command":"screenshot","data":{"full_page":false}}

Full page screenshot:

{"command":"screenshot","data":{"full_page":true}}

Save to path:

{"command":"screenshot","data":{"full_page":true,"path":"artifacts/page.png"}}

Cookies

`set_cookie`

Minimal:

{"command":"set_cookie","data":{"name":"session","value":"abc123"}}

Extended:

{
  "command":"set_cookie",
  "data":{
    "name":"session",
    "value":"abc123",
    "domain":"example.com",
    "path":"/",
    "secure":true,
    "http_only":true,
    "same_site":"Lax"
  }
}

`set_cookies`

{
  "command":"set_cookies",
  "data":{"cookies":"a=1; b=2","domain":"example.com","path":"/","secure":true}
}

`get_cookies`

{"command":"get_cookies"}

`delete_cookie`

{"command":"delete_cookie","data":{"name":"session","domain":"example.com"}}

Local storage

`get_local_storage`

{"command":"get_local_storage"}

`set_local_storage`

{
  "command":"set_local_storage",
  "data":{"items":[{"key":"theme","value":"dark"},{"key":"token","value":"abc"}]}
}

`clear_local_storage`

{"command":"clear_local_storage"}

Session storage

`get_session_storage`

{"command":"get_session_storage"}

`set_session_storage`

{
  "command":"set_session_storage",
  "data":{"items":[{"key":"wizardStep","value":"2"}]}
}

`clear_session_storage`

{"command":"clear_session_storage"}

State capture

`capture_state`

{"command":"capture_state"}

End-to-end examples

curl -X POST https://api.browsr.dev/commands \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"session-abc123",
    "commands":[
      {"command":"navigate_to","data":{"url":"https://app.example.com/login"}},
      {"command":"wait_for_element","data":{"selector":"#email","timeout_ms":10000}},
      {"command":"type_text","data":{"selector":"#email","text":"user@example.com","clear":true}},
      {"command":"type_text","data":{"selector":"#password","text":"secret","clear":true}},
      {"command":"click","data":{"selector":"button[type=submit]"}},
      {"command":"wait_for_navigation","data":{"timeout_ms":10000}},
      {"command":"get_title"}
    ]
  }'

Inspect and extract

curl -X POST https://api.browsr.dev/commands \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"session-abc123",
    "commands":[
      {"command":"navigate_to","data":{"url":"https://example.com"}},
      {"command":"inspect_element","data":{"selector":"main"}},
      {"command":"get_bounding_boxes","data":{"selector":"a","limit":5}},
      {"command":"get_content","data":{"selector":"main","kind":"markdown"}}
    ]
  }'

Capture browser state for reuse

curl -X POST https://api.browsr.dev/commands \
  -H "x-api-key: $BROWSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"session-abc123",
    "commands":[
      {"command":"get_cookies"},
      {"command":"get_local_storage"},
      {"command":"capture_state"}
    ]
  }'

Notes

The command names above match the current browsr-types enum and CLI.
POST /browser_step and POST /observe are complementary APIs built on top of the same session model.
For local Chrome debugging through Browsr Relay, combine session commands with the relay APIs documented in the API overview and relay docs.

Request shape
Response shape
Supported commands
Utility overlays
- toggle_click_overlay
- toggle_bounding_boxes
Navigation
Basic interaction
Content and page info
JavaScript and inspection
Mouse and scroll
Element-focused interactions
Screenshots
- screenshot
Cookies
Local storage
Session storage
State capture
- capture_state
End-to-end examples
Notes

Request shape​

Response shape​

Supported commands​

Utility overlays​

toggle_click_overlay​

toggle_bounding_boxes​

Navigation​

navigate_to​

refresh​

wait_for_navigation​

wait_for_element​

Basic interaction​

click​

click_at​

clear​

press_key​

Content and page info​

get_content​

get_text​

get_attribute​

get_title​

extract_structured_content​

JavaScript and inspection​

evaluate​

get_bounding_boxes​

inspect_element​

Mouse and scroll​

scroll_to​

move_mouse_to​

drag​

scroll_into_view​

Element-focused interactions​

click_advanced​

type_text​

hover​

focus​

check​

select_option​

drag_to​

evaluate_on_element​

get_element_bounding_box​

element_screenshot​

get_basic_info​

Screenshots​

screenshot​

Cookies​

set_cookie​

set_cookies​

get_cookies​

delete_cookie​

Local storage​

get_local_storage​

set_local_storage​

clear_local_storage​

Session storage​

get_session_storage​

set_session_storage​

clear_session_storage​

State capture​

capture_state​

End-to-end examples​

Login flow​

Inspect and extract​

Capture browser state for reuse​

Notes​