Documentation

API V7 Documentation

Create browser VMs with a single server-side call and get a shareable link back

Author

BROWSER.LOL

Published at March 20, 2026

6 min read

To use the API, you need an API key. Contact us to discuss the available options.

The API simplifies workspace creation to a single server-side call. You authenticate with your API key, create the workspace, and receive a share link in the response. The end-user simply opens the share link in their browser and is automatically connected to the workspace.

Authentication

Pass your API key as a Bearer token in the Authorization header. The API key is the session ID associated with your account (with API access enabled).

Authorization: Bearer YOUR_API_KEY

Important: Keep your API key secret. All API calls must be made from your server, never from client-side code.

POST/v7/vm/create

Creates a new virtual browser VM and returns a share link that can be given to end-users.

Request Body (JSON):

browser (required): The browser image to use.

url (optional): The URL to open in the virtual browser.

language (optional): Browser language code (e.g. en, de). Falls back to account default or en.

layout (optional): Keyboard layout code (e.g. us, de). Falls back to account default or us.

country (optional): Two-letter ISO country code for VPN location (e.g. us, de, gb).

Response Body on Success:

{
  "status": "ok",
  "vmId": "brl-v-v7-abc123...",
  "shareUrl": "https://browser.lol/s?LINK_ID",
  "shareUrlPath": "/s?LINK_ID",
  "quota": {
    "credits_total": 1000,
    "credits_used": 143,
    "credits_available": 857,
    "concurrency_total": 10,
    "concurrency_used": 4,
    "concurrency_available": 6,
    "cycle_start": "2026-03-01",
    "cycle_end": "2026-03-31"
  }
}

The quota object reflects usage after the newly created VM is counted. See GET /v7/user/quota below for field descriptions.

Example Request:

curl -X POST https://api.browser.lol/v7/vm/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"browser": "chrome", "url": "https://example.com"}'

Accessing the Workspace

Share the shareUrl from the response with the end-user. When they open the link in their browser, they are automatically connected to the virtual browser session. No additional steps are required.

Share links are tied to the VM. When the VM is deleted, the share link becomes invalid.

GET/v7/user/api

Returns API access status, browser quota usage, and a full quota meter for the authenticated user.

Response Body on Success:

{
  "status": "ok",
  "contact": "user@example.com",
  "api_enabled": true,
  "cycle_start": "2026-03-01",
  "browser_quota": 1000,
  "browser_used": 142,
  "browser_remaining": 858,
  "quota": {
    "credits_total": 1000,
    "credits_used": 142,
    "credits_available": 858,
    "concurrency_total": 10,
    "concurrency_used": 3,
    "concurrency_available": 7,
    "cycle_start": "2026-03-01",
    "cycle_end": "2026-03-31"
  }
}

Quota Fields:

credits_total: Total browser credits for the billing cycle, or null for unlimited plans.

credits_used: Number of browser credits consumed in the current cycle.

credits_available: Remaining credits (credits_total - credits_used), or null for unlimited plans.

concurrency_total: Maximum number of concurrent browsers allowed.

concurrency_used: Number of currently active (running) browsers.

concurrency_available: Remaining concurrency slots (concurrency_total - concurrency_used).

cycle_start: Billing cycle start date (YYYY-MM-DD).

cycle_end: Billing cycle end date (YYYY-MM-DD), one calendar month after cycle_start (same day, next month).

Example Request:

curl https://api.browser.lol/v7/user/api \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v7/user/quota

Returns only the quota meter for the authenticated user. This is a lightweight endpoint for checking credit and concurrency usage without the additional API metadata.

Response Body on Success:

{
  "status": "ok",
  "credits_total": 1000,
  "credits_used": 142,
  "credits_available": 858,
  "concurrency_total": 10,
  "concurrency_used": 3,
  "concurrency_available": 7,
  "cycle_start": "2026-03-01",
  "cycle_end": "2026-03-31"
}

Example Request:

curl https://api.browser.lol/v7/user/quota \
  -H "Authorization: Bearer YOUR_API_KEY"

For unlimited plans, credits_total and credits_available will be null, meaning no cap is enforced.

Possible Errors/v7/*

All error responses follow the same format with a status field and a human-readable message.

Access Denied (invalid API key, API not enabled, or quota exceeded):

{"status": "denied", "message": "The API key you provided is invalid..."}

Security Check Failed (rate limited or insecure request):

{"status": "insecure", "message": "..."}

Server Error:

{"status": "error", "message": "Something went wrong..."}