Humanized REST

Simple HTTP requests for complex browser actions

Our /v1/do/* endpoints turn full browser automation into stateless REST calls. Open a browser, navigate, click, type, and extract DOMs directly from any orchestrator that speaks HTTP.

REST action flow
  1. 1POST /v1/do/open
  2. 2POST /v1/do/navigate
  3. 3POST /v1/do/markdown
  4. 4POST /v1/do/close
Where it fits

Choose the right connection

Humanized REST simplifies browser control without hiding its power. It runs on the exact same infrastructure as our MCP server and Playwright WebSockets, just exposed for HTTP-first agents.

Use REST /v1/do/* when

  • Your orchestrator speaks HTTP
  • You want one action per request
  • You need queue-friendly browser jobs

Use MCP when

  • Your agent runtime already supports tools
  • You want BrowserCity surfaced as a tool server
  • You prefer model-native tool discovery

Use Playwright WS when

  • You already have Playwright scripts
  • You need low-level browser control
  • You want to reuse existing test automation code
Verified shape

A familiar HTTP rhythm

Pass JSON in, get JSON out. Authenticate via Bearer token. Grab a sessionId from the open call, then include it on subsequent requests to keep your state alive.

humanized-rest.ts
const API_BASE = new URL('https://api.browser.city/v1/do/');const apiKey = process.env.BROWSERCITY_API_KEY;async function doAction(action: string, body: unknown) {  const url = new URL(encodeURIComponent(action), API_BASE);  const response = await fetch(url, {    method: 'POST',    headers: {      Authorization: `Bearer ${apiKey}`,      'Content-Type': 'application/json',    },    body: JSON.stringify(body),  });  if (!response.ok) {    throw new Error(['Humanized REST action failed:', response.status].join(' '));  }  return response.json();}const session = await doAction('open', { browser: 'chromium' });try {  await doAction('navigate', { sessionId: session.sessionId, url: 'https://example.com' });  const markdown = await doAction('markdown', { sessionId: session.sessionId });  console.log(markdown.result);} finally {  await doAction('close', { sessionId: session.sessionId });}
Action catalog

Composable browser steps

Our REST layer exposes the exact primitives an agent needs to explore the web, all mounted directly under /v1/do/.

Start

Create a BrowserCity session when your workflow starts and close it explicitly when the job is done.

POST /v1/do/openPOST /v1/do/close
Move

Send navigation steps as REST calls while keeping state tied to the same sessionId.

POST /v1/do/navigatePOST /v1/do/navigate_back
Read

Pull page content back as structured action results for agent memory, RAG, and workflow decisions.

POST /v1/do/markdownPOST /v1/do/htmlPOST /v1/do/snapshotPOST /v1/do/search_snapshot
Act

Drive normal browser interactions through named REST actions instead of keeping a WebSocket client open.

POST /v1/do/clickPOST /v1/do/typePOST /v1/do/fill_formPOST /v1/do/select_option
Discovery

Built for model-native tool discovery

Building a dynamic agent? Call GET /v1/do/tools to fetch a JSON schema of all available actions, ready to drop directly into your LLM's tool array.

Representative verified actions

opennavigatemarkdownhtmlsnapshotsearch_snapshotclicktypefill_formtake_screenshotpdf_saveclose
[ 06 / 06 ] — Get Started

Give your AI agents the web.

Start for free. No credit card required. Private sessions by default.