API

API Documentation

Learn how to use the Browser.lol API to manage your virtual browser workspaces programmatically.

Avatar
Written by
BROWSER.LOL
23.05.2025
20 min read
Share:

API Access & Authentication

Access to the Browser.lol API requires a specific subscription plan and is not included in the standard or premium tiers. If you are interested in leveraging our API for programmatic workspace management, please contact our support team to discuss custom plans and access.

Generating an API Key

To generate an API key, follow these steps:

  1. 1Log in to your Browser.lol account.
  2. 2Navigate to your Dashboard.
  3. 3Click on "API Keys" in the left-hand sidebar menu.
  4. 4In the "Create New API Key" modal window:
    • Optionally, enter a descriptive name for your key (e.g., "My Integration").
    • Optionally, set an expiration date. If left blank, the key will not expire.
  5. 5Click "Generate API Key".
  6. 6Your new API key will be displayed only once. Make sure to copy and store it securely. You will not be able to retrieve it again.

All API requests must include the API key in the Authorization header as a Bearer token:

Authorization Header

Authorization: Bearer YOUR_API_KEY
Security Notice

To protect your credentials, all API requests using your API key (i.e., those requiring the Authorization: Bearer header) should be made from your server-side environment. Do not expose your API key in client-side code (e.g., JavaScript running in a user's browser). The /vm endpoint described below is an exception, designed for client-side use with a temporary workspace ID.

API Base URL

All API endpoints can be accessed through the base domain: api.browser.lol

For example, to access the /v7/workspace/data endpoint, you would make a request to https://api.browser.lol/v7/workspace/data

Custom API Domain

Enterprise customers can request a custom API domain (e.g., api.your-company.com) for their API integration. To set up a custom API endpoint with your own domain, please contact our support team. Custom domains provide additional branding consistency and can help with network security policies in corporate environments.

API Endpoints

GET/v7/user/api

Get API Usage Statistics

Retrieves API usage statistics and limits for the authenticated user, including quota information and current usage in the billing cycle.

Required Headers

  • AuthorizationBearer token (e.g., Bearer YOUR_API_KEY)Required

Success Response (200 OK)

Content-Type: application/json

{
  "status": "ok",
  "contact": "user@example.com",
  "api_quota": 1000,
  "api_cycle_start": "2023-10-01T00:00:00Z",
  "api_cycle_end": "2023-11-01T00:00:00Z",
  "api_used": 150,
  "api_remaining": 850,
  "api_available": true
}

Response Field Descriptions

status

"ok" when the request is successful

contact

The user's email address

api_quota

The total count of API calls allowed in the user's plan

api_cycle_start

The start date of the current billing/counting cycle

api_cycle_end

The end date of the current billing cycle

api_used

The count of API calls used in the current billing cycle

api_remaining

The number of API calls remaining in the current cycle

api_available

Boolean indicating if the API is available for use (true if remaining credits are bigger than 0)

Error Responses

Content-Type: application/json

// Example: Unauthorized
{
  "status": "error",
  "message": "Authentication failed."
}

// Example: Server or database error
{
  "status": "error",
  "message": "An internal server error occurred."
}
GET/v7/workspace/data

Get Workspace Data

Retrieves information about your current virtual browser workspaces, including their status, configuration, and usage details.

Required Headers

  • AuthorizationBearer tokenRequired

Success Response (200 OK)

Content-Type: application/json

{
  "status": "ok",
  "workspaces": [
    {
      "id": "brl-v-v7-*********XXXXXXX",
      "template_name": "Chrome",
      "status": "running",
      "created_at": "2025-05-23T10:00:00Z",
      "lastseen": "2025-05-23T10:30:00Z",
      "expires_at": "2025-05-23T12:00:00Z"
    }
  ]
}

Error Responses

Content-Type: application/json

// Example: Authentication failed
{
  "status": "error",
  "message": "Authentication failed."
}
POST/v7/workspace/create

Create Workspace

Initiates the creation of a new virtual browser workspace.

Required Headers

  • AuthorizationBearer tokenRequired
  • Content-Typeapplication/jsonRequired

Request Body (JSON)

{
  "template_name": "Chrome", // Required: Name of the workspace template (e.g., "Chrome")
  "layout": "us",           // Optional: Keyboard layout (default "us")
  "language": "en"          // Optional: Browser language (default "en")
}

Body Field Descriptions

template_nameRequired

The name of the workspace template to use. Available templates are subject to your subscription plan.

layoutOptional

The keyboard layout for the virtual browser. Defaults to "us".

languageOptional

The browser language. Defaults to "en".

Success Response (200 OK)

Note: The workspace might not be immediately ready after this response. Use the /v7/workspace/data endpoint or poll the /vm endpoint to check the status.

Content-Type: application/json

{
  "status": "ok",
  "id": "brl-v-v7-*********XXXXXXX", // Masked Workspace ID
  "message": "VM creation initiated."
}

Response Field Descriptions

status

"ok" when the creation process is initiated successfully.

id

The masked unique identifier for the new workspace.

message

A descriptive message about the initiation.

Error Responses

Content-Type: application/json

// Example: Authentication failed
{
  "status": "error",
  "message": "Authentication failed."
}

// Example: Invalid template name
{
  "status": "error",
  "message": "Invalid template name."
}

// Example: Quota exceeded
{
  "status": "error",
  "message": "VM creation quota exceeded."
}

// Example: Server or database error
{
  "status": "error",
  "message": "An internal server error occurred."
}
GET/v7/image/data

Get Workspace Screenshot

Retrieves a screenshot image of a specific virtual browser workspace. Requires the workspace id as a query parameter.

Query Parameters

idRequired

The masked unique identifier of the workspace (VM) to get the screenshot for.

Success Response (200 OK)

Content-Type: image/png

// Binary PNG image data returned as the response body

Error Responses

Content-Type: application/json

// Example: Authentication failed
{
  "status": "error",
  "message": "Authentication failed."
}
POST/v7/workspace/remove

Remove Workspace

Removes a specific virtual browser workspace. Note: This action is irreversible.

Required Headers

  • AuthorizationBearer tokenRequired
  • Content-Typeapplication/jsonRequired

Request Body (JSON)

{
  "id": "brl-v-v7-*********XXXXXXX" // Required: Masked ID of the workspace to remove
}

Body Field Descriptions

idRequired

The masked unique identifier of the workspace to remove.

Success Response (200 OK)

Content-Type: application/json

{
  "status": "ok",
  "message": "VM removal initiated."
}

Response Field Descriptions

status

"ok" when the removal process is initiated successfully.

message

A descriptive message about the initiation.

Error Responses

Content-Type: application/json

// Example: Authentication failed
{
  "status": "error",
  "message": "Authentication failed."
}

// Example: Invalid workspace ID or access denied
{
  "status": "error",
  "message": "VM not found or access denied."
}

// Example: Server or database error
{
  "status": "error",
  "message": "An internal server error occurred."
}

Latest Posts

All posts
Development

The Use of Virtual Browsers for Web Development

Virtual browsers are becoming an increasingly popular tool for web developers, and it's not hard to see why. By providing a safe, sandboxed environment for testing and development, virtual browsers offer many benefits over traditional web browsers. In this blog post, we will explore what virtual browsers are and why they are becoming a must-have tool for web developers.

02.12.2022Read more
Security

The Importance of Privacy and Security in Browsing

In today's digital age, it is crucial to understand the importance of privacy and security in browsing. With the increasing amount of personal information shared and stored online, it is becoming increasingly important to be aware of the potential dangers and to take steps to protect oneself.

02.03.2022Read more
General

5 Reasons to use Virtual Browser

To learn what exactly a virtual browser is, you've came to the correct place. In this Post, we exactly explain what a virtual Browser is and how it works. Simply put, it's a browser that runs on our server and can be viewed remotely in any regular browser. This brings many advantages. Some of them are listed below.

20.12.2021Read more