Skip to content
Registry

browser

v0.2.13

A browser on the iii bus - shared Chromium with persistent, restorable tabs and incognito tabs. Navigate, act, read the page console, pick elements. Also parses HTML natively without a browser (browser::* - css/xpath/regex, element search, markdown).

license: Apache-2.0automationbrowsercdpchromiumextractionparsingscrapingweb

Install

bash
iii trigger compose::add worker=browser@0.2.13

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions65

browser::act

Function

Interact with the page: click (left/right/middle, single or double), hover, type, press, scroll, or drag (press at the start point, glide to x2/y2, release). Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.

Request
  • actionstringrequired

    `click`, `hover`, `type`, `press`, `scroll`, or `drag`.

  • buttonstring

    Mouse button for `click`: `left` (default), `right`, or `middle`.

  • click_countinteger· uint32min 0

    Clicks in the gesture: 2 double-clicks (`click` only, default 1).

  • delta_ynumber· double

    Scroll distance in pixels; positive scrolls down (`scroll`).

  • keystring

    Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.

  • refstring

    Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.

  • session_idstringrequired
  • textstring

    Text to insert (`type`).

  • xnumber· double

    Viewport x, when acting by coordinates instead of ref.

  • x2number· double

    Drag end x, in viewport pixels (`drag`). The start is `x`/`y` or a `ref`; the end is `x2`/`y2`.

  • ynumber· double

    Viewport y, when acting by coordinates instead of ref.

  • y2number· double

    Drag end y, in viewport pixels (`drag`).

Response
  • detailstringrequired

    What was done, for the transcript.

  • okbooleanrequired

browser::clear-browser-data

Function

Clear ALL browser data: closes every tab's page, quits Chromium, and deletes the profile (every site's cookies, logins, storage, cache) and the downloads on disk. Tabs stay and reopen signed out. Incognito tabs are closed.

Request
Empty object
Response
  • closed_pagesinteger· uint64requiredmin 0

    Tabs whose page was closed to release the profile; they reopen on the next call, signed out.

  • okbooleanrequired
  • profile_dirstringrequired

    The profile directory that was deleted.

browser::clear-data

Function

Clear the browsing data of the site the tab is on: its cookies, its storage, and the shared cache — like a browser's per-site 'Clear cookies and site data'. Other sites keep their logins; browser::clear-browser-data wipes everything.

Request
  • cacheboolean

    Clear the HTTP cache (shared by every tab). Default true.

  • cookiesboolean

    Delete the cookies the current page can see (its site's cookies). Default true.

  • session_idstringrequired
  • storageboolean

    Clear localStorage / sessionStorage / IndexedDB for the current origin. Default true.

Response
  • clearedstring[]required

    What was cleared, for the confirmation message.

  • okbooleanrequired

browser::console::read

Function

Read the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.

Request
  • levelstring

    Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • levelstringrequired

      `log`, `info`, `warning`, `error`, `debug`, or `exception`.

    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • sourcestring

      `url:line` of the emitting frame, when known.

    • textstringrequired
    • timestampinteger· int64required
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::cookies::clear

Function

Delete the cookies the tab's current page can see (its site's cookies). Other sites keep theirs; browser::clear-browser-data removes everything.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::cookies::list

Function

The cookies visible to the session's current page (name, value, domain, path, flags).

Request
  • session_idstringrequired
Response
  • cookiesobject[]required
    • domainstring
    • expiresnumber· double

      Seconds since the Unix epoch; omitted for a session cookie.

    • http_onlyboolean
    • namestringrequired
    • pathstring
    • same_sitestring

      `Strict`, `Lax`, or `None`.

    • secureboolean
    • valuestringrequired

browser::cookies::set

Function

Set cookies on the session, like importing a cookie file. A cookie without a domain is scoped to the current page's URL. same_site is Strict, Lax, or None.

Request
  • cookiesobject[]required

    Cookies to set. A cookie without a domain is scoped to the current page's URL.

    • domainstring
    • expiresnumber· double

      Seconds since the Unix epoch; omitted for a session cookie.

    • http_onlyboolean
    • namestringrequired
    • pathstring
    • same_sitestring

      `Strict`, `Lax`, or `None`.

    • secureboolean
    • valuestringrequired
  • session_idstringrequired
Response
  • countinteger· uintrequiredmin 0

    How many cookies were sent.

  • okbooleanrequired

browser::crawl

Function

BFS-crawl from start_urls (follow same-domain links), extract per page, stream items.

Request
  • allowed_domainsstring[]

    only follow links on these hosts

  • concurrencyinteger
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • download_delaynumber

    seconds to wait between crawl rounds

  • fetcherstringenum http, stealthy, dynamic
  • formatstringenum markdown, text

    render page body to this format

  • impersonatestring
  • include_htmlboolean
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_depthinteger
  • max_pagesinteger
  • same_domainboolean

    follow only same-host links (default true)

  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • start_urlsstring[]
  • stream_namestring

    stream to emit items on (default browser::crawl)

  • urlstring

    single start URL (alternative to start_urls)

Response
  • itemsobject[]

    a small sample of streamed items

    Empty object
  • statsobject
    • crawledinteger
    • errorsinteger
    • itemsinteger
    • stoppedstring
  • streamobject

    read the full item stream via stream::on with this name + group_id

    • group_idstring
    • namestring

browser::css

Function

One CSS query over HTML; first-or-all; `attr` pulls an attribute else text.

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • attrstring
  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • firstboolean
  • htmlstringrequired
  • identifierstring

    stable key for the saved element

  • querystringrequired
Response
  • resultstring[]

browser::describe

Function

Describe the first css/xpath match: attrs, generated selectors, class list, DOM context.

Request
  • htmlstringrequired
  • kindstringenum css, xpath
  • querystringrequired
Response
  • elementobject
    • attrsobject
    • childreninteger
    • classesstring[]
    • cssstring
    • full_cssstring
    • full_xpathstring
    • htmlstring
    • parent_tagstring
    • siblingsinteger
    • tagstring
    • textstring
    • xpathstring
  • foundboolean

browser::doctor

Function

Read-only environment diagnostics: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.

Request
Empty object
Response
  • active_sessionsinteger· uint64requiredmin 0

    Tabs with a page open right now.

  • allow_cookie_importbooleanrequired
  • allow_history_accessbooleanrequired
  • allowed_schemesstring[]required
  • attach_enabledbooleanrequired

    Whether attach mode is enabled (allow_attach).

  • browser_runningbooleanrequired

    Whether the shared Chromium process is running.

  • chromium_pathstring
  • chromium_versionstring
  • configured_origin_policiesinteger· uint64requiredmin 0
  • data_dirstringrequired

    Where the profile, downloads and tab list live.

  • default_origin_policy_setbooleanrequired
  • headless_defaultbooleanrequired
  • issuesobject[]required
    • enable_howstringrequired
    • whatstringrequired
  • max_sessionsinteger· uint64requiredmin 0

    Live-tab cap (`max_sessions`).

  • okbooleanrequired

    True when sessions can start right now.

  • open_tabsinteger· uint64requiredmin 0

    Every tab, live or asleep.

  • recording_availablebooleanrequired

    Whether ffmpeg is on PATH, which browser::recording requires.

browser::dom::read

Function

Read the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.

Request
  • depthinteger· uint32min 0

    Levels of children to include (default 3).

  • refstring

    Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.

  • session_idstringrequired
Response
  • rootobjectrequired

    One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.

    • child_countinteger· uint32requiredmin 0

      Total children in the document, which may exceed `children` returned at this depth.

    • childrenunknown[]
    • classesstring
    • idstring
    • refstringrequired
    • tagstringrequired

      Lowercase tag (`div`, `button`) or node name (`#text`).

    • textstring

      Trimmed text content for text nodes.

  • truncatedbooleanrequired

    True when the node cap cut the tree short; read a subtree via `ref`.

browser::download

Function

Read one downloaded file's bytes by guid (from browser::downloads::list), base64, for saving or attaching to the chat.

Request
  • guidstringrequired

    The download's CDP guid, from `browser::downloads::list`.

  • session_idstringrequired
Response
  • datastringrequired

    The file, base64.

  • file_namestringrequired
  • okbooleanrequired
  • size_bytesinteger· uint64requiredmin 0

browser::download::remove

Function

Forget a download and delete its file from the session's download dir.

Request
  • guidstringrequired

    The download to forget, and delete from disk.

  • session_idstringrequired
Response
  • okbooleanrequired

browser::downloads::list

Function

The files this session downloaded (name, url, size, state), newest first. Downloads are allowed and named per session; read one with browser::download.

Request
  • session_idstringrequired
Response
  • downloadsobject[]required

    Newest first.

    • file_namestringrequired
    • guidstringrequired
    • received_bytesinteger· uint64requiredmin 0
    • started_msinteger· int64required
    • statestringrequired

      `in_progress`, `completed`, or `canceled`.

    • total_bytesinteger· uint64requiredmin 0
    • urlstringrequired

browser::dynamic-fetch

Function

Playwright/Chromium fetch: JS render, waits, XHR capture, CDP; extraction + bulk.

Request
  • block_adsboolean
  • blocked_domainsstring[]
  • capture_xhrstring
  • cdp_urlstring
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • disable_resourcesboolean
  • dns_over_httpsboolean
  • extra_flagsstring[]
  • extra_headersobject
  • formatstringenum markdown, text

    render page body to this format

  • google_searchboolean
  • headlessboolean
  • include_htmlboolean
  • load_domboolean
  • localestring
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_pagesinteger
  • network_idleboolean
  • proxystring
  • real_chromeboolean
  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • timeoutnumber

    milliseconds (browser fetcher)

  • timezone_idstring
  • urlstring
  • urlsstring[]
  • useragentstring
  • waitnumber

    extra ms to wait after load

  • wait_selectorstring
  • wait_selector_statestringenum attached, detached, visible, hidden
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::evaluate

Function

Evaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.

Request
  • expressionstringrequired

    JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on evaluation; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`.

  • okbooleanrequired
  • valueunknown

    JSON completion value when `ok`.

browser::execute

Function

Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.

Request
  • codestringrequired

    Async JavaScript body run in the page; `state`, `log(...)`, `sleep(ms)` and `waitFor(selector, { timeout })` are in scope. Return plain JSON.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the run; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.

  • logsstring[]required

    `log(...)` output collected during the run, in order.

  • okbooleanrequired
  • resultunknown

    The script's return value when `ok`.

  • stateunknownrequired

    Session state after the run; the next execute call sees this as `state`.

browser::extract

Function

Parse HTML with a selector list (css/xpath/regex, text/attr/html, all-or-first).

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • htmlstringrequired
  • selectorsobject[]required
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
Response
  • extractedobject

browser::fetch

Function

Fast HTTP fetch, TLS impersonation: get/post/put/delete, inline extraction, bulk `urls`.

Request
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • dataobject
  • follow_redirectsboolean
  • formatstringenum markdown, text

    render page body to this format

  • headersobject
  • http3boolean
  • impersonatestring

    TLS/UA fingerprint, e.g. 'chrome'

  • include_htmlboolean
  • jsonobject
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_redirectsinteger
  • methodstringenum get, post, put, delete
  • paramsobject
  • proxiesobject

    per-scheme proxies, e.g. {"https": "http://..."}

  • proxystring
  • proxy_authstring[]

    [user, password]

  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • stealthy_headersboolean
  • timeoutnumber

    seconds (HTTP fetcher)

  • urlstring
  • urlsstring[]
  • verifyboolean
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::find

Function

Find elements by tag/attribute filters (+ optional text regex); BeautifulSoup-style.

Request
  • attrsobject

    attribute filters, e.g. {"class": "card"}

  • firstboolean
  • htmlstringrequired
  • limitinteger
  • tagstring

    tag name or list of tag names

  • text_regexstring

    keep only elements whose text matches this regex

Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-by-regex

Function

Find elements whose visible text matches a regex pattern.

Request
  • case_sensitiveboolean
  • clean_matchboolean
  • firstboolean
  • htmlstringrequired
  • limitinteger
  • patternstringrequired
Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-by-text

Function

Find elements whose visible text matches a string (exact or `partial`).

Request
  • case_sensitiveboolean
  • clean_matchboolean

    ignore surrounding/collapsing whitespace

  • firstboolean
  • htmlstringrequired
  • limitinteger
  • partialboolean

    match elements that contain the text

  • textstringrequired
Response
  • countinteger
  • itemsobject[]
    • attrsobject
    • cssstring
    • htmlstring
    • tagstring
    • textstring
    • xpathstring

browser::find-in-page

Function

Find text in the page like the browser's find bar: highlights every match in the live document, scrolls the current one into view, and steps with next / previous. close clears the highlights. Returns count and the 1-based index.

Request
  • actionstring

    `search` (default: run the query from the top), `next`, `previous`, or `close`.

  • case_sensitiveboolean

    Match case. Default false.

  • querystring

    Text to look for. Empty with `action: close` clears the search.

  • session_idstringrequired
Response
  • countinteger· uint64requiredmin 0

    Number of matches in the visible text of the page.

  • indexinteger· uint64requiredmin 0

    1-based index of the highlighted match; 0 when there is none.

  • okbooleanrequired
  • querystringrequired

    The query the counts refer to.

browser::find-similar

Function

Structural auto-match: given one example element, return it plus similar elements.

Request
  • anchorstringrequired

    CSS selector to one example element

  • htmlstringrequired
  • match_textboolean
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • similarity_thresholdnumber
Response
  • countinteger
  • itemsobject[]
    Empty object

browser::frame

Function

Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.

Request
  • session_idstringrequired
  • since_frameinteger· uint64min 0

    Frame cursor from the previous read; the response omits `frame` while the newest frame still has this seq.

Response
  • activebooleanrequired

    False when no screencast is running (call screencast::start first).

  • framestring

    Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.

  • frame_seqinteger· uint64requiredmin 0
  • heightinteger· uint32requiredmin 0

    Page-viewport height the frame maps to.

  • timestampinteger· int64required
  • widthinteger· uint32requiredmin 0

    Page-viewport width the frame maps to (input coordinate space).

browser::handoff

Function

Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.

Request
  • instructionsstringrequired

    What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Give up after this many ms and return `via: "timeout"` (clamped to `max_timeout_ms`); set generously, a human is slow.

Response
  • confirmedbooleanrequired

    True when a human confirmed; false when the wait timed out.

  • handoff_idstringrequired
  • urlstringrequired

    The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).

  • viastringrequired

    How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.

browser::handoff::confirm

Function

Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.

Request
  • handoff_idstring

    Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.

  • session_idstring
Response
  • handoff_idstring
  • okbooleanrequired

    True when a pending handoff matched and was resolved.

browser::history

Function

Go back, go forward, or reload the tab's page. History survives the tab sleeping and the worker restarting. Back/forward at the history edge is a no-op with moved=false.

Request
  • actionstringrequired

    `back`, `forward`, or `reload`.

  • session_idstringrequired
Response
  • movedbooleanrequired

    False when back/forward had no entry to move to.

  • okbooleanrequired
  • urlstringrequired

    URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.

browser::history::list

Function

The session's visited pages, newest first, for a history panel or address-bar suggestions. Filter with query. Distinct from browser::history, which moves back / forward / reloads.

Request
  • limitinteger· uintmin 0

    Cap on returned entries. Default 100.

  • querystring

    Only entries whose url or title contains this (case-insensitive).

  • session_idstringrequired
Response
  • visitsobject[]required
    • timestampinteger· int64required
    • titlestringrequired
    • urlstringrequired

browser::inject-guidance

Function

Internal: appends browser::* scraping and HTML parsing guidance to the agent system prompt.

Request
  • generateobject
    • system_promptstring
Response
  • mutationsobjectrequired
    • system_promptstring

browser::navigate

Function

Navigate a tab to a URL and wait for the page to load. Like a browser, a network failure or an empty HTTP error response leaves Chromium's error page in the tab and is reported in `error` rather than failing the call. Element refs from earlier snapshots are invalidated by navigation.

Request
  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the navigation wait; clamped to `max_timeout_ms`.

  • urlstringrequired

    Absolute URL; scheme must be on the configured allowlist.

Response
  • errorstring

    Chromium's error text when the navigation ended on the browser's own error page: a network failure (`net::ERR_NAME_NOT_RESOLVED`), or an empty HTTP error response (`net::ERR_HTTP_RESPONSE_CODE_FAILURE`, a 4xx/5xx with no body). Like a browser, the tab still shows that page and stays usable.

  • okbooleanrequired

    False when the tab shows Chromium's error page instead of the site; see `error`.

  • timed_outbooleanrequired

    True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.

  • titlestring
  • urlstringrequired

    URL after redirects.

browser::network::read

Function

Read the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.

Request
  • failed_onlyboolean

    Only failed requests (network error or status >= 400).

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to the request URL.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • errorstring
    • failedbooleanrequired
    • methodstringrequired
    • mime_typestring
    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • statusinteger· int64
    • timestampinteger· int64required
    • urlstringrequired
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::on-config-change

Function

Internal: reload browser settings from the authoritative configuration on change.

Request
Empty object
Response
  • okbooleanrequired

browser::pdf

Function

Print the page to a PDF (the browser's Print -> Save as PDF) and return it base64 with a file name from the title.

Request
  • landscapeboolean

    Landscape orientation. Default portrait.

  • print_backgroundboolean

    Print background colours and images. Default true (what the page looks like, not what a printer would save ink on).

  • scalenumber· double

    Page scale, 0.1–2. Default 1.

  • session_idstringrequired
Response
  • datastringrequired

    The PDF, base64.

  • file_namestringrequired

    Suggested file name, from the page title.

  • okbooleanrequired
  • size_bytesinteger· uint64requiredmin 0
  • urlstringrequired

browser::pick::hint

Function

Internal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the cursor.

  • ynumber· doublerequired

    Viewport y of the cursor.

Response
  • boundsany of

    Viewport-space box to draw the highlight over.

    any of (2)
    Variant 1
    • heightnumber· doublerequired
    • widthnumber· doublerequired
    • xnumber· doublerequired
    • ynumber· doublerequired
    Variant 2
    valuenull
  • classesstring
  • hitbooleanrequired

    False when no element sits at the point.

  • idstring
  • tagstring

    Lowercase tag name.

browser::pick::resolve

Function

Internal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the click.

  • ynumber· doublerequired

    Viewport y of the click.

Response
  • okbooleanrequired

browser::pick::start

Function

Internal: enter pick mode so the human can select an element in the console UI. Not an agent function.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::pick::stop

Function

Internal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.

Request
  • session_idstringrequired

    Cancelling pick mode on an unknown session succeeds.

Response
  • okbooleanrequired

browser::recording::start

Function

Record a session's live viewport to a video file (webm or mp4) by piping the screencast through ffmpeg. Turns screencast on if needed. Requires ffmpeg on PATH; browser::doctor reports whether it is available.

Request
  • formatstring

    `webm` (VP9) or `mp4` (H.264). Defaults to webm.

  • pathstringrequired

    Output file path. The extension should match `format`.

  • session_idstringrequired
Response
  • formatstringrequired
  • okbooleanrequired
  • pathstringrequired

browser::recording::stop

Function

Stop a session's recording, finalize the file, and return its path, duration, and frame count. Idempotent: stopping when nothing is recording returns ok=false.

Request
  • session_idstringrequired
Response
  • duration_msinteger· int64required

    Wall-clock duration captured, milliseconds.

  • framesinteger· uint64requiredmin 0

    Frames written to the encoder.

  • okbooleanrequired

    False when no recording was running.

  • pathstring

browser::regex

Function

Run a regex over the visible text of provided HTML; `first` returns the first match, else all.

Request
  • firstboolean
  • htmlstringrequired
  • patternstringrequired
Response
  • resultstring[]

browser::resize

Function

Set the session's live viewport size (CSS pixels). The console calls this as its browser pane resizes so the streamed frame fills the pane with no letterboxing and clicks map 1:1; the device toolbar calls it with a preset. Clamped 200..4000.

Request
  • device_scale_factornumber· double

    Device pixel ratio. Default 1.

  • fitboolean

    Mark this resize as a pane auto-fit; a fit is refused (current size returned) while more than one viewer watches the session.

  • heightinteger· uint32requiredmin 0

    Viewport height in CSS pixels (clamped 200..4000).

  • mobileboolean

    Emulate a mobile device (viewport meta, overlay scrollbars, touch). Default false. The device toolbar sets this for phone presets.

  • session_idstringrequired
  • widthinteger· uint32requiredmin 0

    Viewport width in CSS pixels (clamped 200..4000).

Response
  • heightinteger· uint32requiredmin 0
  • okbooleanrequired
  • widthinteger· uint32requiredmin 0

    The clamped size actually applied.

browser::screencast::start

Function

Internal: start the live viewport feed — frames arrive on the browser::frame-event trigger and browser::frame reads the newest. Console-UI plumbing; agents use browser::screenshot. Not an agent function.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::screencast::stop

Function

Internal: stop the live frame push. Idempotent. Not an agent function.

Request
  • session_idstringrequired

    Stopping the screencast on an unknown session succeeds.

Response
  • okbooleanrequired

browser::screenshot

Function

Capture the session viewport as a viewable JPEG. Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.

Request
  • full_pageboolean

    Capture the full scrollable page instead of the viewport.

  • session_idstringrequired
Response
  • contentobject[]required
    • datastring
    • mimestring
    • textstring
    • typestringrequired
  • detailsobjectrequired
    • heightinteger· uint32requiredmin 0
    • session_idstringrequired
    • urlstringrequired
    • widthinteger· uint32requiredmin 0

browser::screenshot-url

Function

Capture a page screenshot as image content blocks via a browser fetcher (dynamic or stealthy).

Request
  • fetcherstringenum dynamic, stealthy
  • formatstringenum png, jpeg
  • full_pageboolean
  • headlessboolean
  • network_idleboolean
  • proxystring
  • timeoutnumber
  • urlstringrequired
  • wait_selectorstring
Response
  • contentobject[]

    image blocks (one per tile, width<=1024/height<=1536) + a text caption

    • datastring

      base64 image bytes (image blocks)

    • mimestring
    • textstring
    • typestringrequiredenum image, text
  • mimestring
  • urlstring

browser::session-close

Function

Close a session and free its browser/connection.

Request
  • session_idstringrequired
Response
  • closedboolean

browser::session-fetch

Function

Fetch a URL on an open scraping session (reuses its cookies/state); returns page content, shows nothing. For a page the user should see, use browser::sessions::start + browser::navigate.

Request
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • dataobject
  • formatstringenum markdown, text

    render page body to this format

  • headersobject
  • include_htmlboolean
  • jsonobject
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • methodstringenum get, post, put, delete
  • paramsobject
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • session_idstringrequired
  • urlstringrequired
  • wait_selectorstring
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::session-list

Function

List open sessions with their type and idle time.

Request
  • typestringenum http, dynamic, stealthy

    filter by type

Response
  • sessionsobject[]
    • created_atnumber
    • idle_snumber
    • last_usednumber
    • session_idstring
    • typestring

browser::session-open

Function

Open a persistent scraping session (HTTP or headless fetcher) whose session_id reuses cookies and state across fetches. Renders nothing the user can see; to open a page in the visible browser use browser::sessions::start.

Request
  • capture_xhrstring

    regex; capture matching XHRs (browser sessions)

  • headersobject
  • headlessboolean
  • impersonatestring
  • proxiesobject
  • proxystring
  • real_chromeboolean
  • solve_cloudflareboolean
  • timeoutnumber
  • typestringenum http, dynamic, stealthy

    session engine

  • useragentstring
Response
  • session_idstring
  • typestring

browser::sessions::attach

Function

Attach a session to an already-running browser over CDP (Chrome started with --remote-debugging-port): opens a fresh tab the session owns, or adopts a user tab by URL substring and releases it untouched on stop. Reaches the real profile and its logins; requires allow_attach in config.

Request
  • adopt_url_substringstring

    Adopt the one open tab whose URL contains this substring (released untouched on stop); omit to open a fresh tab the session owns.

  • cdp_urlstringrequired

    CDP endpoint of the running browser: `http://127.0.0.1:9222` (resolved via `/json/version`) or a `ws://` debugger URL.

  • read_onlyboolean

    Inspection-only session; see browser::sessions::start.

  • urlstring

    URL to open in the fresh tab (ignored when adopting). Omit for about:blank.

Response
  • adoptedbooleanrequired

    True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.

  • read_onlybooleanrequired
  • session_idstringrequired
  • urlstringrequired

browser::sessions::list

Function

List every browser tab, live or asleep, with its current URL, title, and activity.

Request
Empty object
Response
  • sessionsobject[]required
    • activebooleanrequired

      True while the tab has its page open. A sleeping tab (false) is listed and usable; the next call on it reopens the page at `url`.

    • console_entriesinteger· uint64requiredmin 0

      Console entries captured since the page opened; 0 while asleep.

    • created_msinteger· int64required
    • headlessbooleanrequired
    • incognitobooleanrequired

      Private tab: nothing persisted, closes instead of sleeping.

    • last_used_msinteger· int64required
    • read_onlybooleanrequired
    • session_idstringrequired
    • titlestring
    • ttl_msinteger· uint64min 0

      Lifetime the tab was opened with, when any.

    • urlstringrequired

browser::sessions::start

Function

Open a browser tab (a session) and return its session_id. Tabs share one browser profile (cookies, logins) and stay open until stopped or until an optional ttl_ms; an unused tab sleeps and wakes on the next call. incognito=true opens a PRIVATE tab: nothing it does is saved, and inactivity closes it for good.

Request
  • headfulboolean

    Force a visible window, overriding the configured `headless` default. Applies when this call launches the browser process; a browser that is already running keeps its mode.

  • incognitoboolean

    INCOGNITO TAB. Opens the tab in a private browser context: it shares no cookies, logins, or storage with the regular tabs, nothing it does is saved to disk (no cookies, no history, no tab record), it does not come back after a restart, and inactivity closes it for good instead of putting it to sleep. Everything lives in memory for as long as the tab does. Use it for logins you do not want kept, or to see a site signed out.

  • read_onlyboolean

    Inspection-only session for its whole lifetime: act, evaluate, execute and styles::write are rejected; navigation and reads work.

  • ttl_msinteger· uint64min 0

    Optional lifetime in milliseconds: the tab closes on its own this long after it opened, even while in use. Omit for a tab that stays until stopped (what the console does).

  • urlstring

    URL to open immediately. Omit to start on about:blank.

Response
  • errorstring

    Chromium's error text when the requested url did not load and the tab shows the browser's error page instead (a network failure, or an empty HTTP error response such as a 400). Absent when the page came up. The tab is open either way.

  • headlessbooleanrequired
  • incognitobooleanrequired

    True for a private tab; see `incognito` on the request.

  • read_onlybooleanrequired
  • session_idstringrequired

    Pass this to every other browser function.

  • urlstringrequired

browser::sessions::stop

Function

Close a browser tab for good. Idempotent: closing an unknown or already-closed tab succeeds with was_running=false.

Request
  • session_idstringrequired

    Tab to close. Closing an unknown or already-closed id succeeds.

Response
  • okbooleanrequired
  • was_runningbooleanrequired

    False when the session was already gone.

browser::snapshot

Function

Read the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.

Request
  • diffboolean

    Return only what changed since the previous snapshot; a full outline when there is no baseline (first snapshot or after a navigation).

  • session_idstringrequired
Response
  • diffany of

    Present when the caller asked for `diff: true` and a baseline existed. Covers only the emitted nodes of both snapshots; check `truncated` before trusting it as a complete change set.

    any of (2)
    Variant 1
    • addedstring[]required
    • removedstring[]required
    • unchangedinteger· uint64requiredmin 0
    Variant 2
    valuenull
  • generationinteger· uint64requiredmin 0

    Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.

  • titlestring
  • treestringrequired

    Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.

  • truncatedbooleanrequired

    True when the tree hit `max_snapshot_nodes` and was cut short. Also the signal that a `diff` may be incomplete: the diff is computed over emitted nodes only, so when either snapshot was truncated a node that was emitted before and capped out now can show up in `removed` even though it still exists (and vice versa for `added`).

  • urlstringrequired

browser::stealthy-fetch

Function

Camoufox stealth browser: solves Cloudflare, hardens WebRTC/canvas; extraction + bulk.

Request
  • allow_webglboolean
  • block_adsboolean
  • block_webrtcboolean
  • blocked_domainsstring[]
  • capture_xhrstring
  • cookiesobject
  • css_selectorstring

    scope the render to this CSS subtree (e.g. a page's content div)

  • disable_resourcesboolean
  • dns_over_httpsboolean
  • extra_flagsstring[]
  • extra_headersobject
  • formatstringenum markdown, text

    render page body to this format

  • google_searchboolean
  • headlessboolean
  • hide_canvasboolean
  • include_htmlboolean
  • load_domboolean
  • localestring
  • main_content_onlyboolean

    strip nav/scripts/hidden before rendering

  • max_pagesinteger
  • network_idleboolean
  • proxystring
  • retriesinteger
  • retry_delaynumber
  • selectorsobject[]
    • allboolean

      return every match as a list

    • attrstring

      extract this attribute instead of text

    • cssstring
    • htmlboolean

      extract inner HTML instead of text

    • namestringrequired
    • regexstring
    • xpathstring
  • solve_cloudflareboolean
  • timeoutnumber

    milliseconds (browser fetcher)

  • timezone_idstring
  • urlstring
  • urlsstring[]
  • useragentstring
  • waitnumber

    extra ms to wait after load

  • wait_selectorstring
  • wait_selector_statestringenum attached, detached, visible, hidden
Response
  • captured_xhrobject[]
    Empty object
  • contentstring

    markdown/text render when `format` requested

  • cookiesobject
  • encodingstring
  • errorstring
  • extractedobject
  • formatstring
  • headersobject
  • htmlstring
  • resultsobject[]
    Empty object
  • statusinteger
  • urlstring

browser::styles::read

Function

Read an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.

Request
  • propertiesstring[]

    Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.

  • refstringrequired

    Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.

  • session_idstringrequired
Response
  • inline_stylestring

    The element's inline `style` attribute, when present.

  • propertiesobject[]required
    • namestringrequired
    • valuestringrequired
  • refstringrequired

browser::styles::write

Function

Set one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.

Request
  • importantboolean

    Apply with `!important`.

  • propertystringrequired

    CSS property name (`background-color`).

  • refstringrequired

    Element ref to edit.

  • session_idstringrequired
  • valuestringrequired

    CSS value (`#101418`). Empty string removes the inline property.

Response
  • inline_stylestringrequired

    The element's inline `style` attribute after the edit.

  • okbooleanrequired

browser::tabs::list

Function

List the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.

Request
  • cdp_urlstringrequired

    CDP endpoint of the running browser, as in browser::sessions::attach.

Response
  • tabsobject[]required
    • adoptedbooleanrequired

      True when a session already adopted this tab; it cannot be adopted again until that session stops.

    • titlestring
    • urlstringrequired

browser::to-markdown

Function

Convert HTML to compact Markdown (or text/html); optional CSS scope + main-content clean.

Request
  • css_selectorstring

    convert only the subtree matching this CSS selector

  • formatstringenum markdown, text, html
  • htmlstringrequired
  • main_content_onlyboolean

    strip nav/scripts/hidden nodes first

Response
  • contentstring
  • formatstring

browser::ui-content

Function

Serve the browser worker's injected console UI assets (content function for its console:script / console:style triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

browser::upload

Function

Attach up to eight base64 files to exactly one input[type=file] selected by CSS. Files are staged privately for the session and removed when it stops.

Request
  • filesobject[]required

    Up to eight files, each at most 25 MB decoded.

    • datastringrequired

      File bytes, base64.

    • namestringrequired

      File name exposed to the page. Path components are rejected.

  • selectorstringrequired

    CSS selector that must match exactly one input[type=file].

  • session_idstringrequired
Response
  • attachedinteger· uintrequiredmin 0
  • file_namesstring[]required
  • okbooleanrequired

browser::xpath

Function

One XPath query over HTML; first-or-all; `attr` pulls an attribute else text.

Request
  • adaptiveboolean

    relocate elements after a site change via saved identities

  • adaptive_domainstring

    page URL/domain that keys saved identities

  • attrstring
  • auto_saveboolean

    save matched identities (defaults on when adaptive)

  • firstboolean
  • htmlstringrequired
  • identifierstring

    stable key for the saved element

  • querystringrequired
Response
  • resultstring[]

browser::zoom

Function

Zoom the page in, out, to a level (50-200 %) or back to 100 %, the way the browser's zoom menu does. The viewport keeps its size; the page scales inside it. The level belongs to the loaded document and resets on navigation.

Request
  • actionstring

    `in`, `out`, `reset`, `set` (default when `level` is given), or `read` to report the current level without changing it.

  • levelinteger· uint32min 0

    Explicit level in percent (50–200); snapped to the ladder.

  • session_idstringrequired
Response
  • levelinteger· uint32requiredmin 0

    Level in percent now applied to the document.

  • okbooleanrequired

Triggers11

browser::console-event

Trigger

A console/log/exception entry was captured on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::download-changed

Trigger

A download started, progressed, or finished in a session.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::frame-event

Trigger

Internal: a live screencast frame of a watched tab (console viewport plumbing, high volume).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-requested

Trigger

A session is paused waiting for a human to complete a step (CAPTCHA, 2FA, payment).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-resolved

Trigger

A paused handoff finished (confirmed in page, by call, or timed out).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::navigated

Trigger

The session's page committed a navigation.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::network-event

Trigger

A network request was captured (completed or failed) on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::picked

Trigger

The human picked an element in inspect mode.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-started

Trigger

A browser tab opened and is ready.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-stopped

Trigger

A browser tab closed for good (stopped, idle, expired, or crashed).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-updated

Trigger

A browser tab woke up (page open again) or went to sleep (page closed, tab kept).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.