Browser automation API

Automate web browsing tasks including navigation, screenshots, content extraction, form filling, and multi-step workflows

Browser automation API

This feature is in beta. All actions are executed against a real headless Chrome instance via a Playwright backend. Requests have a 60-second timeout.

The browser automation API lets your agents interact with web pages programmatically. You can navigate to URLs, capture screenshots, extract page content, fill forms, and chain multiple actions into automated workflows. Actions are proxied to a Playwright backend service running headless Chrome.

Authentication

All endpoints require a valid session. Requests without an authenticated session receive a 401 response.

Get service info

GET /api/browser

Returns the current status of the browser automation service, including the API version and a list of supported capabilities.

Response

{
  "service": "Browser Automation API",
  "version": "0.1.0-beta",
  "status": "beta",
  "capabilities": [
    "navigate — Go to a URL",
    "screenshot — Capture page screenshot",
    "click — Click an element",
    "type — Type text into a field",
    "extract — Extract content from a page",
    "fill-form — Fill and submit forms",
    "automate — Multi-step browser workflows"
  ],
  "note": "Browser automation is in beta. Requires Playwright instance for full functionality."
}

Response fields

Field	Type	Description
service	string	Service name
version	string	Current API version
status	string	Release status (beta)
capabilities	array	List of supported actions with short descriptions
note	string	Additional information about the beta status

Perform a browser action

POST /api/browser

Executes a browser automation action. The action field determines which operation runs and which additional parameters are required.

Request body

Field	Type	Required	Description
action	string	Yes	The action to perform. One of: navigate, screenshot, click, type, extract, fill-form, automate.
url	string	Conditional	Target URL. Required for navigate, screenshot, extract, and fill-form.
selector	string	No	CSS selector for targeting a specific element. Used by extract (defaults to body).
text	string	No	Text input. Used by type.
steps	array	Conditional	Array of step objects defining a sequence of actions. Required for fill-form and automate.

Actions

navigate

Go to a URL and return the result.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "navigate",
    "url": "https://example.com"
  }'

Required parameters: url

Response:

{
  "success": true,
  "action": "navigate",
  "url": "https://example.com",
  "message": "Navigated to https://example.com"
}

screenshot

Capture a screenshot of a page.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "screenshot",
    "url": "https://example.com"
  }'

Required parameters: url

Response:

The response contains the screenshot data from the Playwright backend. Screenshots are captured in full-page mode by default.

{
  "success": true,
  "action": "screenshot",
  "url": "https://example.com",
  "screenshot": "<base64-encoded image data>"
}

click

Click an element on the page.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "click",
    "url": "https://example.com",
    "selector": "#submit-button"
  }'

type

Type text into a form field.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "type",
    "url": "https://example.com",
    "selector": "#search-input",
    "text": "hello world"
  }'

extract

Extract content from a page using an optional CSS selector.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "extract",
    "url": "https://example.com",
    "selector": "article"
  }'

Required parameters: url

Response:

{
  "success": true,
  "action": "extract",
  "url": "https://example.com",
  "selector": "article",
  "content": "<extracted text content>"
}

Field	Type	Description
selector	string	The CSS selector used for extraction. Defaults to body if not provided.

fill-form

Automate form filling on a target page.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "fill-form",
    "url": "https://example.com/signup",
    "steps": [
      { "selector": "#name", "value": "Agent" },
      { "selector": "#email", "value": "[e-mail]" },
      { "selector": "#submit", "action": "click" }
    ]
  }'

Required parameters: url, steps

Response:

{
  "success": true,
  "action": "fill-form",
  "url": "https://example.com/signup",
  "steps": [
    { "selector": "#name", "value": "Agent" },
    { "selector": "#email", "value": "[e-mail]" },
    { "selector": "#submit", "action": "click" }
  ],
  "message": "Form filled on https://example.com/signup"
}

automate

Run a multi-step browser workflow.

curl -X POST /api/browser \
  -H "Content-Type: application/json" \
  -d '{
    "action": "automate",
    "steps": [
      { "action": "navigate", "url": "https://example.com" },
      { "action": "click", "selector": "#login" },
      { "action": "type", "selector": "#email", "text": "[e-mail]" },
      { "action": "screenshot" }
    ]
  }'

Required parameters: steps (must be an array)

Response:

{
  "success": true,
  "action": "automate",
  "steps": [
    { "action": "navigate", "url": "https://example.com" },
    { "action": "click", "selector": "#login" },
    { "action": "type", "selector": "#email", "text": "[e-mail]" },
    { "action": "screenshot" }
  ],
  "message": "Automation workflow completed with 4 steps"
}

Common response fields

All action responses include these fields:

Field	Type	Description
success	boolean	true when the action completed successfully
action	string	The action that was performed
message	string	Human-readable summary of the result

Additional fields vary by action (for example, screenshot returns a screenshot field with base64-encoded image data, and extract returns a content field).

Errors

Code	Body	Description
400	{ "error": "Invalid action. Must be one of: navigate, screenshot, click, type, extract, fill-form, automate" }	Invalid or missing action parameter
400	{ "error": "Invalid request body" }	The request body could not be parsed as JSON
401	{ "error": "Unauthorized" }	No authenticated session
502	{ "error": "<message>", "service": "playwright-backend" }	The Playwright backend is unreachable or returned an error. The service field identifies the failing upstream service.