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

# BrowserPair REST API for Durable Browser Automation

> Create idempotent scoped browser tasks, request observations or subgoals, respond to browser state, and cancel work over REST.

Use the REST API when you want explicit HTTP control over BrowserPair's durable browser-task lifecycle.

<CardGroup cols={3}>
  <Card title="Base URL" icon="globe">
    `https://api.browserpair.com`
  </Card>

  <Card title="Authentication" icon="key">
    Bearer `bp_live_…` agent key.
  </Card>

  <Card title="Create safely" icon="fingerprint">
    `POST /v1/tasks` requires an idempotency key.
  </Card>
</CardGroup>

## Agent endpoints

| Method | Path                    | Purpose                                     |
| ------ | ----------------------- | ------------------------------------------- |
| `GET`  | `/v1/browsers`          | List browsers available to the agent key.   |
| `POST` | `/v1/tasks`             | Create a durable bounded task.              |
| `GET`  | `/v1/tasks/:id`         | Read current durable state and interaction. |
| `POST` | `/v1/tasks/:id/subgoal` | Delegate bounded work to Reflex.            |
| `POST` | `/v1/tasks/:id/observe` | Request a fresh observation.                |
| `POST` | `/v1/tasks/:id/respond` | Send one bounded agent response.            |
| `POST` | `/v1/tasks/:id/cancel`  | Cancel the task.                            |

<Note>
  Human approval is intentionally separate from agent authority. A task that needs a confirmation or runtime scope expansion surfaces that request to the signed-in user.
</Note>

## Create a task

```bash theme={null}
curl https://api.browserpair.com/v1/tasks \
  -H 'Authorization: Bearer bp_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-check-001' \
  -d '{
    "browserId": "brw_…",
    "goal": "Open the billing page and read the latest invoice status",
    "contract": {
      "version": 1,
      "domains": ["example.com"],
      "capabilities": ["read", "navigate", "click"],
      "confirmations": [],
      "maxSideEffects": 2
    }
  }'
```

## Task contract

<ParamField body="browserId" type="string" required>
  Connected browser identifier inside the reusable agent key's browser scope.
</ParamField>

<ParamField body="goal" type="string" required>
  Human-readable durable task intent.
</ParamField>

<ParamField body="contract" type="object" required>
  The task authority created at start.

  <Expandable title="Contract fields">
    <ParamField body="version" type="integer" required>
      Use `1`.
    </ParamField>

    <ParamField body="domains" type="string[]" required>
      One or more explicit websites, all inside the reusable key's domain ceiling.
    </ParamField>

    <ParamField body="capabilities" type="string[]" required>
      The exact capability classes this task may exercise.
    </ParamField>

    <ParamField body="confirmations" type="string[]">
      Additional immutable task confirmation requirements.
    </ParamField>

    <ParamField body="maxSideEffects" type="integer">
      Optional bound on side-effecting operations.
    </ParamField>
  </Expandable>
</ParamField>

## Capability classes

<CardGroup cols={2}>
  <Card title="Ordinary browsing" icon="mouse-pointer">
    `read`, `navigate`, `click`, `fill`, `select`
  </Card>

  <Card title="Elevated effects" icon="shield">
    `communication`, `publish`, `destructive`, `authentication`, `payment`, `account_security`, `state_change`
  </Card>
</CardGroup>

A task can narrow the reusable key, never widen it.

## Idempotency

<Warning>
  Every `POST /v1/tasks` request requires `Idempotency-Key`.
</Warning>

The key must be 8–200 characters using letters, numbers, `.`, `_`, `:`, or `-`.

<Tabs>
  <Tab title="Same key + same request">
    BrowserPair returns the original task.
  </Tab>

  <Tab title="Same key + different request">
    BrowserPair fails closed with an idempotency conflict.
  </Tab>
</Tabs>

## Read current state

`GET /v1/tasks/:id` returns the durable task state and, when relevant, the current bounded interaction.

<Tip>
  Treat the interaction generation as part of the action context. Do not reuse stale element refs from an older generation.
</Tip>

## Delegate a Reflex subgoal

`POST /v1/tasks/:id/subgoal` can include:

* a bounded subgoal;
* success criteria;
* maximum Reflex steps;
* observation mode and scope; and
* an optional compatible Skill ID.

The original task authority remains unchanged.

## Request an observation

`POST /v1/tasks/:id/observe` requests fresh context without performing a browser mutation.

Modes are `lite`, `accessibility`, `dom`, `screenshot`, and `combined`. Scope is `relevant-region` or `full-page`.

## Respond to the task

`POST /v1/tasks/:id/respond` accepts one action against the current interaction generation.

Supported kinds include `navigate`, `open_tab`, `back`, `click`, `fill`, `select`, `focus`, `press`, `scroll`, `wait`, `done`, `blocked`, and `resolve_effect`.

<Warning>
  Use only refs returned by the current observation. BrowserPair rejects authority-expanding or stale requests rather than inferring intent.
</Warning>

<CardGroup cols={3}>
  <Card title="Remote MCP" icon="plug" href="/remote-mcp">
    Use the same capabilities through MCP tools.
  </Card>

  <Card title="Task semantics" icon="arrows-rotate" href="/task-semantics">
    Understand durable state and safe retries.
  </Card>

  <Card title="Permissions" icon="shield" href="/permissions">
    See how agent-key and task authority interact.
  </Card>
</CardGroup>