API V7 Documentation

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

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. Up to 10,000 characters.

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).

shareLanguage (optional): Locale segment used in the returned share URL path. Supported values: en, de, fr, es, it, pt, ja. Defaults to en.

callbackUrl (optional): HTTP or HTTPS URL the viewer redirects the end-user to when the session ends. Max 2,000 characters. If omitted, the user is returned to the browser.lol dashboard.

Response Body on Success:

{
  "status": "ok",
  "vmId": "brl-v-v7-abc123...",
  "shareUrl": "https://browser.lol/en/s?LINK_ID",
  "shareUrlPath": "/en/s?LINK_ID",
  "quota": {
    "running_session_limit": 10,
    "running_sessions_used": 4,
    "running_sessions_remaining": 6,
    "cycle_session_limit": 1000,
    "cycle_sessions_used": 143,
    "cycle_sessions_remaining": 857,
    "cycle_start": "2026-03-01"
  }
}

The response returns as soon as the session is accepted. The returned vmId starts in status starting while the browser is prepared in the background, then switches to running, usually within a few seconds. The share link shows a loading screen until the session is ready; if preparation fails on every host, the session ends in status "error".

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", "callbackUrl": "https://your-app.example.com/done"}'

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.

The share URL contains a locale segment (en) that controls the language of the viewer page. Replace it with any supported locale: de, fr, es, it, pt, ja. You can also pass shareLanguage in the request body to have the API return the URL with that locale already applied.

GET/v7/user/api

Returns programmatic access status and session usage for the authenticated user.

Response Body on Success:

{
  "status": "ok",
  "contact": "[email protected]",
  "feature_programmatic_access": true,
  "running_session_limit": 10,
  "running_sessions_used": 3,
  "running_sessions_remaining": 7,
  "cycle_session_limit": 1000,
  "cycle_sessions_used": 142,
  "cycle_sessions_remaining": 858,
  "cycle_start": "2026-03-01",
  "has_plan": true
}

Quota Fields:

cycle_session_limit: Total sessions allowed in the billing cycle, or null for unlimited plans.

cycle_sessions_used: Sessions used in the current cycle.

cycle_sessions_remaining: Remaining sessions (cycle_session_limit - cycle_sessions_used), or null for unlimited plans.

running_session_limit: Maximum number of sessions that may run concurrently.

running_sessions_used: Number of sessions currently running.

running_sessions_remaining: Number of additional sessions that may start immediately.

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

Example Request:

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

GET/v7/user/quota

Returns only the session limits and usage for the authenticated user. This is a lightweight endpoint without the additional API metadata.

Response Body on Success:

{
  "status": "ok",
  "has_plan": true,
  "running_session_limit": 10,
  "running_sessions_used": 3,
  "running_sessions_remaining": 7,
  "cycle_session_limit": 1000,
  "cycle_sessions_used": 142,
  "cycle_sessions_remaining": 858,
  "cycle_start": "2026-03-01"
}

Example Request:

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

For unlimited plans, cycle_session_limit and cycle_sessions_remaining 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..."}