Skip to main content

​
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

FieldTypeDescription
servicestringService name
versionstringCurrent API version
statusstringRelease status (beta)
capabilitiesarrayList of supported actions with short descriptions
notestringAdditional 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

FieldTypeRequiredDescription
actionstringYesThe action to perform. One of: navigate, screenshot, click, type, extract, fill-form, automate.
urlstringConditionalTarget URL. Required for navigate, screenshot, extract, and fill-form.
selectorstringNoCSS selector for targeting a specific element. Used by extract (defaults to body).
textstringNoText input. Used by type.
stepsarrayConditionalArray of step objects defining a sequence of actions. Required for fill-form and automate.

​
Actions

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>"
}
FieldTypeDescription
selectorstringThe 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:
FieldTypeDescription
successbooleantrue when the action completed successfully
actionstringThe action that was performed
messagestringHuman-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

CodeBodyDescription
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.