API Documentation

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

Headers

• Authorization: Bearer token (e.g., Bearer YOUR_API_KEY). (Required)

Success Response (200 OK)

{
  "status": "ok",
  "contact": "[email protected]",
  "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

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

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

Retrieves a list of workspaces (virtual machines) associated with the authenticated user, created within the last month. Optionally, provide a specific workspace id as a query parameter to retrieve data for only that workspace.

Headers

• Authorization: Bearer token. (Required)

Query Parameters

• id (String): The unique identifier of a specific workspace (VM). If provided, only data for this workspace will be returned. (Optional)

Success Response (200 OK)

The data array will contain one object if an id was specified, or multiple objects if no id was provided.

{
  "status": "ok",
  "data": [
    {
      "id": "brl-v-v7-*********XXXXXXX", // Masked ID
      "created": "2023-10-27T11:00:00Z",
      "updated": "2023-10-27T11:05:00Z",
      "server": "srv1",
      "name": "Chrome",
      "picture": "https://browser.lol/img/collection/browser/chrome.png",
      "description": "Fast Google browser with extensive extensions.",
      "lastseen": "2025-04-22T11:05:00Z",
      "status": "running",
      "layout": "us",
      "language": "en",
      "lastseen_timeout": 3600, // Time in seconds
      "renew_timeout": 7200, // Time in seconds
      "max_timeout": 86400, // Time in seconds
      "renewed": "2025-04-22T11:05:00Z"
    }
  ]
}

Error Responses

// Example: Database Error
{
  "status": "error",
  "message": "Database error occurred." // Or specific error message
}

// Example: Workspace not found (if ID provided)
{
  "status": "error",
  "message": "VM not found or access denied."
}

Creates a new virtual browser session (workspace/VM) based on the provided parameters.

Headers

• Authorization: Bearer token. (Required)
• Content-Type: application/json. (Required)

Body Parameters

{
  "browser": "chrome", // Image ID (See /image/data Endpoint) (Required)
  "url": "https://browser.lol", // Initial URL (Optional)
  "language": "en-US", // Browser interface language code (Optional)
  "layout": "us", // Keyboard layout (Optional)
}

• browser (String): ID of the browser image to use. Can be retrieved from the /image/data Endpoint (Required)
• url (String): Initial URL to load. (Optional)
• language (String): Language code (e.g., 'en-US', 'de-DE'). (Optional)
• layout (String): Keyboard layout (e.g., 'us', 'de'). (Optional)
• lang (String): Spell check language (e.g., 'en', 'de'). (Optional)

Success Response (200 OK)

{
  "status": "ok",
  "workspaceName": "brl-v-v7-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // Unique ID of the created workspace
}

Error Responses

// Example: Missing required field
{ "status": "denied", "message": "Missing required fields." }

// Example: Invalid browser ID
{ "status": "denied", "message": "Invalid browser specified." }

// Example: Rate limit exceeded or security check failed (less common for dedicated API plans)
{ "status": "insecure", "message": "Security check failed." }

// Example: Premium browser requested without permission (if applicable to API plan)
{ "status": "denied", "message": "Subscription does not allow this browser." }

// Example: Concurrent session limit reached
{
    "status": "denied",
    "message": "You have reached your limit of 1 concurrent browser sessions. Please close existing sessions or upgrade your plan."
}

// Example: Server error during creation
{ "status": "error", "message": "Failed to create workspace." }

Retrieves a list of all available browser images that can be used when creating workspaces.

Headers

• Authorization: Bearer token. (Required)

Success Response (200 OK)

{
  "status": "ok",
  "images": [
    {
      "id": "chrome",
      "name": "Chrome",
      "picture": "https://browser.lol/img/collection/browser/chrome.png",
      "description": "Fast Google browser with extensive extensions.",
      "enabled": true,
      "premium": false
    },
    {
      "id": "firefox",
      "name": "Firefox",
      "picture": "https://browser.lol/img/collection/browser/firefox.png",
      "description": "Privacy-focused Mozilla browser.",
      "enabled": true,
      "premium": false
    },
    // Additional browser images...
  ]
}

Response Field Descriptions

• status: "ok" when the request is successful
• images: Array of available browser image objects
• images[].id: Unique identifier of the browser image (used in creating workspaces)
• images[].name: Display name of the browser
• images[].picture: URL to the browser icon/logo
• images[].description: Short description of the browser
• images[].enabled: Boolean indicating if the browser is currently available
• images[].premium: Boolean indicating if the browser requires a premium subscription

Error Responses

// Example: Database Error
{
  "status": "error",
  "message": "Database error occurred."
}

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

Marks an existing workspace (virtual machine) for deletion. The actual removal is handled by a background process.

Headers

• Authorization: Bearer token. (Required)
• Content-Type: application/json. (Required)

Body Parameters

{
  "id": "brl-v-v7-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" // ID of the workspace to remove (Required)
}

• id (String): The unique identifier of the workspace (VM) to be removed. (Required)

Success Response (200 OK)

{
  "status": "ok"
}

Error Responses

// Example: Missing ID
{ "status": "error", "message": "Missing required fields." }

// Example: Workspace not found or not owned by user
{ "status": "error", "message": "VM not found or access denied." }

// Example: Database or server error during marking for deletion
{ "status": "error", "message": "Database error occurred." }

Provides client-side access to the virtual machine interface for a specific workspace. This endpoint is intended to be used in the user's browser (e.g., by redirecting the user or embedding within an iframe) after obtaining a workspace ID from the /v7/workspace/create endpoint.
Note that the base URL for this client-side endpoint differs from the server-side API base URL. If you are using the standard api.browser.lol domain for server-side calls, use https://browser.lol/vm for this endpoint. If you have a custom API domain (e.g., api.your-company.com), use that same custom domain for this endpoint (e.g., https://api.your-company.com/vm).

Note: This endpoint is designed for client-side access and does not use the Authorization: Bearer YOUR_API_KEY header. Access is granted based on the validity of the workspace ID.

Query Parameters

• id (String): The unique identifier of the workspace (VM) to access. This is the workspaceName returned by the /v7/workspace/create endpoint. (Required)
• redirectUrl (String): A URL to redirect the user to when they click the "Exit" or "Close" button within the VM interface. (Optional)
• logo (String): A URL pointing to a publicly accessible JPG or PNG image. This logo will be displayed on the loading screen while the workspace is preparing. (Optional)

Example URLs:

• Standard Domain: https://browser.lol/vm?id=...&redirectUrl=...&logo=...
• Custom Domain: https://api.your-company.com/vm?id=...&redirectUrl=...&logo=...

Response (200 OK)

This endpoint always returns an HTTP status code of 200 OK. The response body will be an HTML page containing either:

• The interactive interface for the requested virtual machine.
• An error message indicating why the workspace could not be accessed (e.g., invalid ID, expired session).

The response body is always HTML, not JSON.

Error Handling

If the workspace ID is invalid, expired, cannot be found, or if there is any other issue preventing access, the endpoint still returns a 200 OK status code. The error condition will be described within the HTML content of the response page. There are no separate HTTP error status codes (like 404 or 403) used for this endpoint.

Check the content of the returned HTML page to determine if access was successful or if an error occurred.