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": "agent@example.com" },
      { "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": "agent@example.com" },
    { "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": "user@example.com" },
      { "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": "user@example.com" },
    { "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.

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Browser automation API

Browser automation API

Authentication

Get service info

Response

Response fields

Perform a browser action

Request body

Actions

navigate

screenshot

click

type

extract

fill-form

automate

Common response fields

Errors

​Browser automation API

​Authentication

​Get service info

​Response

​Response fields

​Perform a browser action

​Request body

​Actions

​navigate

​screenshot

​click

​type

​extract

​fill-form

​automate

​Common response fields

​Errors

Browser automation API

Authentication

Get service info

Response

Response fields

Perform a browser action

Request body

Actions

navigate

screenshot

click

type

extract

fill-form

automate

Common response fields

Errors