---
title: "Send a command to a browser"
method: POST
path: "/browsers/{browserId}/command"
---

# Send a command to a browser

`POST /browsers/{browserId}/command`

## Request

- Base URL: `https://oyabrowser.com`
- URL: `https://oyabrowser.com/browsers/{browserId}/command`
- Auth: HTTP bearer

Execute a browser action (analyze, navigate, click, type, press_key, screenshot, scroll, wait, list_tabs, open_tab, switch_tab, close_tab, read_page).

## Path parameters

- `browserId` string, required

## Request body

- object
  - `action` 'analyze' | 'navigate' | 'click' | 'type' | 'press_key' | 'screenshot' | 'scroll' | 'wait' | 'read_page' | 'list_tabs' | 'open_tab' | 'switch_tab' | 'close_tab', required: The browser action to execute. Each action uses only specific params (see examples).
  - `params` object: Action-specific parameters. Only include params relevant to the chosen action.
    - `url` string: URL (for navigate, open_tab)
    - `selector` string: CSS selector, e.g. [data-ac-id="3"] (for click, type, wait, read_page)
    - `text` string: Text to type (for type)
    - `key` string: Key to press (for press_key): Enter, Escape, Tab, Backspace, ArrowDown, ArrowUp, etc.
    - `direction` 'up' | 'down': Scroll direction (for scroll)
    - `amount` number: Pixels to scroll (for scroll, default 500)
    - `timeout` number: Timeout in ms (for wait, default 10000)
    - `tab_id` number: Tab ID (for switch_tab, close_tab)
    - `limit` number: Max elements (for read_page, default 50)

## Response `200`

Command result

- CommandResult
  - `ok` boolean: Whether the command succeeded
  - `code` string: For ok:false, a stable reason: command_failed for a refusal the page answered, or one named per action.
  - `data` object: Action-specific result data
    - `url` string
    - `title` string
    - `screenshot` string: Base64 PNG data URL (for screenshot action)
    - `format` 'markdown' | 'toon' | 'jsonl': The format page is written in (for analyze action)
    - `page` string: The page, written in format (for analyze action)
    - `markdown` string: Page content as markdown, when format is markdown (for analyze action)
    - `blocks` object[]: The page as data: one block per heading, paragraph, list item, table row, image and element, in reading order (for analyze action)
    - `elements` object[]: Interactive elements (for analyze/read_page actions)
      - `id` integer
      - `type` string
      - `text` string
      - `href` string
      - `visible` boolean
    - `tabs` object[]: Open tabs (for list_tabs action)
      - `id` integer
      - `title` string
      - `url` string
      - `active` boolean
    - `tab_id` integer: New tab ID (for open_tab action)
    - `selector` string
    - `direction` string
    - `amount` number
    - `key` string
    - `found` boolean
    - `closed` boolean
    - `needs_capture` boolean
    - `scroll` object
      - `top` number
      - `height` number
      - `scrollHeight` number
    - `viewport` object
      - `width` number
      - `height` number
    - `truncated` boolean
  - `error` string, nullable: Error message if ok is false

## Other responses

- `400`: Missing action
- `404`: Browser not connected
- `500`: Server fault, not the request: the body carries a ref that matches the server's log line

---

[API](https://skmtc.dev/oyabrowser/apis/oya-browser-api.md) · [All operations](https://skmtc.dev/oyabrowser/apis/oya-browser-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oyabrowser/apis/oya-browser-api/revisions/748c4b34f8e4?raw)