Scroll to navigate sections

Overview

The Browserize API lets you programmatically create, manage, and control headless (or headed) browser instances. Every browser spins up on our edge network and is ready to use within seconds — no infrastructure to manage.

Each browser supports VNC for live viewing, CDP for Playwright/Puppeteer integration, and MCP for AI agent tool use. You pay only for the compute hours consumed.

!

Base URL

All API requests should be made to: https://browserize.com/api/v1

Authentication

All API requests require an API key sent via the Authorization header. You can generate API keys from your project dashboard.

Header
Authorization: Bearer sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to a single project. A key grants full access to all browser operations within that project. Keep your keys secure — do not share them in client-side code or version control.

Base URL

bash
https://browserize.com/api/v1

All endpoints below are relative to this base URL. Responses are always JSON. Successful responses include success: true and the relevant data field.

API Endpoints

Seven endpoints cover the full browser lifecycle — listing, creating, reading, updating, deleting, starting, and stopping.

GET/browsers

Returns a paginated list of all browsers in your project. Non-deleted browsers only.

Query Parameters

limit
No
Number of browsers to return (max 100).
offset
No
Number of browsers to skip for pagination.

Response

200 OK
{
  "success": true,
  "data": [
    {
      "id": "abc123def456",
      "name": "scraper-prod-01",
      "status": "Running",
      "uptime": "3h 42m",
      "cpuLimit": 1,
      "memoryLimit": 1024,
      "vncEnabled": true,
      "mcpEnabled": true,
      "cdpEnabled": true,
      "novnc_url": "https://proxy.browserize.com/abc123/novnc",
      "debug_url": "https://proxy.browserize.com/abc123/cdp",
      "createdAt": 1700000000000
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
POST/browsers

Creates a new browser instance and immediately launches it. The browser transitions through Starting → Running automatically.

Request Body

name
Yes
A human-friendly label for the browser instance.
cpuLimit
No
CPU cores (0.5, 1, 2, or 4).
memoryLimit
No
Memory in MB (512, 1024, 2048, or 4096).
vncEnabled
No
Enable the web-based VNC viewer.
mcpEnabled
No
Expose browser via Model Context Protocol.
cdpEnabled
No
Enable Chrome DevTools Protocol.

Example Request

curl
curl -X POST https://browserize.com/api/v1/browsers \
  -H "Authorization: Bearer sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "scraper-prod-01",
    "cpuLimit": 2,
    "memoryLimit": 2048,
    "vncEnabled": true,
    "mcpEnabled": true,
    "cdpEnabled": true
  }'

Response

201 Created
{
  "success": true,
  "data": {
    "browserId": "abc123def456"
  }
}
GET/browsers/:id

Returns a single browser instance by its ID.

Path Parameters

id
Yes
The unique identifier of the browser.

Response

200 OK
{
  "success": true,
  "data": {
    "id": "abc123def456",
    "name": "scraper-prod-01",
    "status": "Running",
    "uptime": "1h 23m",
    "cpuLimit": 2,
    "memoryLimit": 2048,
    "vncEnabled": true,
    "mcpEnabled": true,
    "cdpEnabled": true,
    "flyMachineId": "e7d8e9f0a1b2",
    "novnc_url": "https://proxy.browserize.com/abc123/novnc",
    "debug_url": "https://proxy.browserize.com/abc123/cdp",
    "createdAt": 1700000000000
  }
}
PUT/browsers/:id

Update the name and/or resource limits of an existing browser. Only provided fields are changed.

Request Body

name
No
A new name for the browser instance.
cpuLimit
No
New CPU limit (0.5, 1, 2, or 4).
memoryLimit
No
New memory limit in MB.

Response

200 OK
{
  "success": true
}
DELETE/browsers/:id

Permanently deletes a browser instance. Destroys the underlying Fly machine and stops billing. This action cannot be undone.

Response

200 OK
{
  "success": true
}
PUT/browsers/:id/start

Starts a previously stopped browser. The Fly machine boots and the browser becomes accessible within seconds.

Response

200 OK
{
  "success": true
}
$

Billing

Starting a browser resumes billing. Usage is tracked per-second and deducted from your account balance.

PUT/browsers/:id/stop

Stops a running browser. The Fly machine is shut down and billing is stopped.

Response

200 OK
{
  "success": true
}

Pagination

The GET /browsers endpoint returns paginated results. Use the limit and offset query parameters to navigate through pages.

Example
# First page (default)
GET /api/v1/browsers

# Next page
GET /api/v1/browsers?limit=50&offset=50

# Custom page size
GET /api/v1/browsers?limit=20&offset=40
limit
No
Results per page. Minimum 1, maximum 100.
offset
No
Number of results to skip.

The response includes a pagination object with total, limit, offset, and hasMore fields so you can determine when you've reached the last page.

Error Codes

The API uses standard HTTP status codes. Errors return a JSON body with an error field describing the issue.

400
No
Missing or invalid parameters.
401
No
Missing, expired, or invalid API key.
402
No
Insufficient balance. Purchase more compute hours.
404
No
Browser with the given ID does not exist.
409
No
Action cannot be performed in the current state (e.g. no machine to start).
429
No
Rate limit exceeded. Slow down.
500
No
Something went wrong on our end.
Example Error
{
  "error": "Insufficient balance. Please purchase more compute hours."
}

Code Examples

Quick-start examples for creating and managing browsers in popular languages.

Python

browserize.py
import requests

API_KEY = "sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://browserize.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Create and launch a browser
res = requests.post(
    f"{BASE_URL}/browsers",
    headers=HEADERS,
    json={
        "name": "my-browser",
        "cpuLimit": 2,
        "memoryLimit": 2048,
    },
)
browser_id = res.json()["data"]["browserId"]
print(f"Created: {browser_id}")

# List all browsers
res = requests.get(f"{BASE_URL}/browsers", headers=HEADERS)
for b in res.json()["data"]:
    print(f"  {b['name']} — {b['status']}")

# Stop when done
requests.put(f"{BASE_URL}/browsers/{browser_id}/stop", headers=HEADERS)

Node.js

browserize.mjs
const API_KEY = "sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const BASE = "https://browserize.com/api/v1";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// Create and launch
const { data } = await fetch(`${BASE}/browsers`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "my-browser" }),
}).then((r) => r.json());

console.log("Browser ID:", data.browserId);

// List all
const { data: browsers } = await fetch(
  `${BASE}/browsers?limit=10`,
  { headers },
).then((r) => r.json());

browsers.forEach((b) =>
  console.log(`${b.name} — ${b.status}`)
);

Go

main.go
package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  apiKey := "sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  base := "https://browserize.com/api/v1"

  body, _ := json.Marshal(map[string]any{
    "name": "my-browser",
  })

  req, _ := http.NewRequest("POST",
    base+"/browsers",
    bytes.NewReader(body),
  )
  req.Header.Set("Authorization", "Bearer "+apiKey)
  req.Header.Set("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()

  var result map[string]any
  json.NewDecoder(res.Body).Decode(&result)
  fmt.Println(result)
}

cURL

terminal
# Create a browser
curl -X POST https://browserize.com/api/v1/browsers \
  -H "Authorization: Bearer sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-browser"}'

# List browsers (first page)
curl https://browserize.com/api/v1/browsers \
  -H "Authorization: Bearer sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Stop a browser
curl -X PUT https://browserize.com/api/v1/browsers/BROWSER_ID/stop \
  -H "Authorization: Bearer sk-brz-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rate Limits

API keys are rate-limited to protect the platform. Limits are applied per-key and scale with your plan:

Free
No
Exploration and testing.
Pro
No
Production workloads.
Enterprise
No
Contact us for dedicated limits.

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in all API responses.