> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser automation API

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

# Browser automation API

<Note>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.</Note>

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

```http theme={"dark"}
GET /api/browser
```

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

### Response

```json theme={"dark"}
{
  "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

```http theme={"dark"}
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.

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

**Required parameters:** `url`

**Response:**

```json theme={"dark"}
{
  "success": true,
  "action": "navigate",
  "url": "https://example.com",
  "message": "Navigated to https://example.com"
}
```

#### screenshot

Capture a screenshot of a page.

```bash theme={"dark"}
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.

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

#### click

Click an element on the page.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

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

**Required parameters:** `url`

**Response:**

```json theme={"dark"}
{
  "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.

```bash theme={"dark"}
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:**

```json theme={"dark"}
{
  "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.

```bash theme={"dark"}
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:**

```json theme={"dark"}
{
  "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. |