Integrations / Automation libraries / Local REST API

A REST API for browser profiles.

Everything the Browz app does is on a local REST API. Any language that can send HTTP can create a profile, start it, open a page, take a screenshot and stop it, without a browser library.

Set it up Download Browz

Terminalexport BROWZ_TOKEN="$(cat ~/.browz/api-token)"

Setup

Set it up.

Install Browz and open it
Download Browz. The API listens on 127.0.0.1 only, port 50333 by default.
Load the token
Every request needs the app’s bearer token, from the api-token file in the Browz data folder. Rotate it from the app’s API & MCP screen to cut every client off at once.
Terminalexport BROWZ_TOKEN="$(cat ~/.browz/api-token)"
Create a profile
Every field is optional; the answer has the new profile’s id.
TerminalID=$(curl -s -X POST http://127.0.0.1:50333/api/v1/profile/create -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" \ -d '{"name":"api-demo"}' | jq -r .data.id)
Start it, open a page, screenshot
Terminalcurl -s -X POST http://127.0.0.1:50333/api/v1/browser/start -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\",\"headless\":true}" curl -s -X POST http://127.0.0.1:50333/api/v1/browser/navigate -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\",\"url\":\"https://example.com\"}" curl -s -X POST http://127.0.0.1:50333/api/v1/browser/screenshot -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\"}" \ | jq -r .data.base64 | base64 --decode > page.png
Stop and remove it
Delete moves the profile to the trash; purge empties it.
Terminalcurl -s -X POST http://127.0.0.1:50333/api/v1/browser/stop -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\"}" curl -s -X POST http://127.0.0.1:50333/api/v1/profile/delete -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\"}" curl -s -X POST http://127.0.0.1:50333/api/v1/profile/purge -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\"}"

Example

Read the page without a browser library.

The API can also run an expression in the page and return the value, or return the page as a snapshot of roles and names with element refs.

Terminal

curl -s -X POST http://127.0.0.1:50333/api/v1/browser/evaluate -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" \
  -d "{\"id\":\"$ID\",\"expression\":\"document.title\"}" | jq -r .data.value
curl -s -X POST http://127.0.0.1:50333/api/v1/browser/snapshot -H "Authorization: Bearer $BROWZ_TOKEN" -H "Content-Type: application/json" -d "{\"id\":\"$ID\"}" | jq .data

Every route, with its request and answer schemas, is in the OpenAPI 3.1 spec (also as YAML), which you can load into any OpenAPI client generator.

Good to know

Notes and tips.

A request answers HTTP 200 with "code": 0 on success. A refusal carries "code": -1 and a message saying why, sometimes with a 200 status, so check code as well as the status.
The examples need jq. On Windows, use the same requests from PowerShell or any HTTP client.
Attach to the browser Browz started; never let the library launch its own. A library-launched browser is a stock one with none of the profile’s fingerprint, proxy or cookies.
A person completes sign-ins, 2FA codes and CAPTCHAs in the profile’s window; your script can wait for the page that follows. Browz never solves or bypasses CAPTCHAs.
Automate only where each site’s terms allow it. Our acceptable use policy applies to scripts the same as to people.
The local API, CDP and the SDKs are on every plan, Free included (5 profiles), and are not metered.

FAQ

Local REST API and Browz.

Is the API reachable from other computers?

No. It listens on 127.0.0.1 only, so run your code on the computer with Browz.

Is there a typed client?

Yes: @browz/sdk on npm for TypeScript, and the browz package inside browz-mcp on PyPI for Python. Both are thin clients over these same routes.

Can I give a script less than full access?

Yes. Create a local agent key with browz agent-token create, limited to some scopes, profiles and sites, and send it as the bearer token instead of the app’s token.

Get started

Download Browz. Every task, its own browser.

Download Browz See pricing

Then, on macOS or Linux, put the MCP server on your PATHcurl -fsSL https://gobrowz.com/agents/install.sh | sh

For Mac, Windows and Linux. Free for 5 profiles. Paid plans from $4.99 a month, with a 14-day refund on your first payment.

A REST API for browser profiles.

Set it up.

Install Browz and open it

Load the token

Create a profile

Start it, open a page, screenshot

Stop and remove it

Read the page without a browser library.

Notes and tips.

Local REST API and Browz.

More guides.

All automation libraries

browz CLI

Raw CDP

Playwright

Download Browz. Every task, its own browser.