BrowserPair REST API for Durable Browser Automation

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

Base URL

https://api.browserpair.com

Authentication

Bearer bp_live_… agent key.

Create safely

POST /v1/tasks requires an idempotency key.

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.

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.

Create a task

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

string

required

Connected browser identifier inside the reusable agent key’s browser scope.

string

required

Human-readable durable task intent.

object

required

The task authority created at start.

Show Contract fields

integer

required

Use 1.

string[]

required

One or more explicit websites, all inside the reusable key’s domain ceiling.

string[]

required

The exact capability classes this task may exercise.

string[]

Additional immutable task confirmation requirements.

integer

Optional bound on side-effecting operations.

Capability classes

Ordinary browsing

read, navigate, click, fill, select

Elevated effects

communication, publish, destructive, authentication, payment, account_security, state_change

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

Idempotency

Every POST /v1/tasks request requires Idempotency-Key.

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

Same key + same request
Same key + different request

BrowserPair returns the original task.

Read current state

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

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

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.

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

Remote MCP

Use the same capabilities through MCP tools.

Task semantics

Understand durable state and safe retries.

Permissions

See how agent-key and task authority interact.

Get Started

Use BrowserPair

Agent APIs

Concepts

BrowserPair REST API for Durable Browser Automation

Base URL

Authentication

Create safely

Agent endpoints

Create a task

Task contract

Capability classes

Ordinary browsing

Elevated effects

Idempotency

Read current state

Delegate a Reflex subgoal

Request an observation

Respond to the task

Remote MCP

Task semantics

Permissions

Base URL

Authentication

Create safely

​Agent endpoints

​Create a task

​Task contract

​Capability classes

Ordinary browsing

Elevated effects

​Idempotency

​Read current state

​Delegate a Reflex subgoal

​Request an observation

​Respond to the task

Remote MCP

Task semantics

Permissions

Agent endpoints

Create a task

Task contract

Capability classes

Idempotency

Read current state

Delegate a Reflex subgoal

Request an observation

Respond to the task