Live API Documentation

Table of Contents

Using the API

Using the API is a simple three-step process:

  • Step 1: Request a session token (server-side).
  • Step 2: Use the token to start a browser (client-side).
  • Step 3: Embed the the browser in your application (client-side).

You can also try the Live API Demo and see Live API introduction (with a demo video).

Session tokens

Every browser session requires a session token. You should request the access token server-side and use it on the client-side. Every session token can only be used once.

You can request a session token by sending a GET request to https://www.browserling.com/liveapi_v1_session with the Browserling-Api-Key header set to your API key. This endpoint always returns a JSON object.

Request a session from command line with curl:


$ curl -H "Browserling-Api-Key: YOUR_API_KEY" https://www.browserling.com/liveapi_v1_session

Request a session from PHP using libcurl:


$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://www.browserling.com/liveapi_v1_session");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["Browserling-Api-Key" => "YOUR_API_KEY"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
echo $response;

Request a session from Python using urllib:


import urllib.request
req = urllib.request.Request("https://www.browserling.com/liveapi_v1_session")
req.add_header("Browserling-Api-Key", "YOUR_API_KEY")
response = urllib.request.urlopen(req).read()
print(response)

If the request succeeds, the response object will contain your session token in the session property:


{ "session": "Pt1MXZ9cSJt+Nk5JOpmVG/GwPxktcScKw..." }

If the request fails, the response object will contain the error in the error property:


{ "error": "invalid_api_key" }

Configuring the browser

Once you have the session token, you can embed the browser in your application! To do that, first include liveapi_v1.js in your code:


<script src="https://www.browserling.com/js/liveapi_v1.js"></script>

This library exports just one function called BrowserlingIframe. Create a new BrowserlingIframe object with the desired options:


var browserling = new BrowserlingIframe({
    session: "Pt1MXZ9cSJt+Nk5JOpmVG/GwPxktcScKw...",
    platform: "win/10",
    browser: "chrome/127",
    url: "https://example.org"
});

Here are all the available options:

Session

The session option must be set to the session token string you have requested earlier from your backend. You can create and embed as many browsers as you'd like but each browser requires its own token.

Platform

The platform option is a string in platform/version format that affects which platform you will get. We currently support Windows and Android platforms, but we're soon adding macOS, iOS and Linux.

Valid platforms are:

Browser

The browser option is a string in browser/version format that affects which browser will be launched. Each platform can have different browsers installed.

Valid browser name for on is .

URL

The url option is a string that affects which URL the browser will open. It is passed to the browser as-is, without modifications.

Clipboard

The clipboard option is a boolean that allows turning off automatic clipboard sharing. By default, whenever new text appears in your clipboard, it will be written into the remote browser (and the other way around). If this functionality is not desired, you can set the clipboard option to false to prevent this.

Embedding the browser in your application

You can embed Browserling's browsers anywhere in your application through an iframe. Add an HTML element to your page where you want the browser to be:


<!-- your app -->
<div id="my-browser-container"></div>

Initialize the BrowserlingIframe object and set an onload callback, then get the iframe and append it to your element.


var browserling = new BrowserlingIframe({
    session: "Pt1MXZ9cSJt+Nk5JOpmVG/GwPxktcScKw...",
    platform: "win/10",
    browser: "chrome/127",
    url: "https://example.org"
});

browserling.onload = function() {
    // Runs when browser is available
};

var iframe = browserling.iframe();

var div = document.getElementById("my-browser-container");
div.appendChild(iframe);

This will append the iframe to your div and start loading the browser. After it's loaded, your onload callback will be called and you can interact with the browser.

Once the browser has loaded, you can navigate to a new URL by using the navigate function. It will close the current browser, clean up the session and restart the same browser with the new URL: 


browserling.navigate("https://example.org");

If you want to launch a different browser, you can specify it as a second parameter to navigate function:


browserling.navigate("https://example.org", "firefox/100");

Some browser versions may not be available in your session. To find out which browsers can be launched, you can read the browsers array:


browserling.onload = function() {
    // List all browser versions
    console.log(browserling.browsers);

    // Launch a random browser
    var browser = browserling.browsers[Math.floor(Math.random() * browserling.browsers.length)];
    browserling.navigate("https://random.org", browser);
};

If you want to launch a browser on a different platform, you will need to request a new session.

Controlling the mouse

You can control the mouse through the API. You can left click, right click, drag, drag and drop, and move the mouse while left or right buttons are clicked.

Note that all APIs that interact with the browser may only be used after the browser has loaded:


var browserling = new BrowserlingIframe({
    session: "Pt1MXZ9cSJt+Nk5JOpmVG/GwPxktcScKw...",
    platform: "win/10",
    browser: "chrome/127",
    url: "https://example.org"
});

// Error: Cannot call 'moveMouse' before BrowserlingIframe is loaded
browserling.moveMouse(10, 10);

browserling.onload = function() {
    // Success!
    browserling.moveMouse(10, 10);
};

Move mouse


browserling.mouseMove(x, y);

Left click:


browserling.leftClick(x, y);

Right click:


browserling.rightClick(x, y);

Mouse wheel click:


browserling.wheelClick(x, y);

Click any mouse button:


browserling.click(x, y, button);

Available mouse buttons are:


browserling.MOUSE_LEFT
browserling.MOUSE_MIDDLE
browserling.MOUSE_RIGHT
browserling.MOUSE_WHEEL_UP
browserling.MOUSE_WHEEL_DOWN

Press a button (and don't release it):


browserling.mouseDown(x, y, button)

Release button:


browserling.mouseUp(x, y)

Drag mouse:


browserling.dragMouse(x1, y1, x2, y2, button)

Presses button and drags mouse from (x1, y1) to (x2, y2).

Inserting a delay between actions:


browserling.delay(milliseconds)

For example:


browserling.mouseMove(400, 100); // Move mouse to 400, 100
browserling.delay(100); // Delay 100ms
browserling.leftClick(400, 100); // Left click at 400, 100
browserling.delay(100); // Delay 100ms
browserling.leftClick(400, 110); // Left click at 400, 110
browserling.delay(100); // Delay 100ms
browserling.drag(400, 120, 400, 130); // Drag from 400, 120 to 400, 130
browserling.delay(100); // Delay 100ms

Controlling the keyboard

You can also type text, and send keyboard keys to interact with the browser through the API.

Type text:


browserling.typeText(text)

For example:


browserling.typeText("login");

Press and release a key:


browserling.keyPress(key)

For example:


browserling.typeText("login");
browserling.keyPress(browserling.KEY_TAB);
browserling.typeText("password");
browserling.keyPress(browserling.KEY_ENTER);

Another example:


browserling.keyPress("a"); // Types "a"
browserling.keyPress("B"); // Types "B"
browserling.keyPress("c"); // Types "c"

Press a key (but don't release it):


browserling.keyDown(key)

For example:


browserling.keyDown(browserling.KEY_SHIFT); // Press Shift
browserling.typeText("hello"); // Types "HELLO" because Shift is down

Another example:


browserling.keyDown(browserling.KEY_CTRL); // Press Control
browserling.keyPress("a"); // Presses Ctrl+A
browserling.keyUp(browserling.KEY_CTRL); // Release Control

Release a key:


browserling.keyUp(key)

For example:


browserling.keyUp(browserling.KEY_SHIFT); // Release Shift

All the functions that take a key can take special keys available on any BrowserlingIframe instance. These keys include the following:


browserling.KEY_BACKSPACE
browserling.KEY_TAB
browserling.KEY_ENTER
browserling.KEY_SHIFT
browserling.KEY_CTRL
browserling.KEY_ALT
browserling.KEY_ESC
browserling.KEY_SPACE
browserling.KEY_PAGE_UP
browserling.KEY_PAGE_DOWN
browserling.KEY_END
browserling.KEY_HOME
browserling.KEY_LEFT
browserling.KEY_UP
browserling.KEY_RIGHT
browserling.KEY_DOWN
browserling.KEY_DELETE
browserling.KEY_SUPER
browserling.KEY_F1
browserling.KEY_F2
browserling.KEY_F3
browserling.KEY_F4
browserling.KEY_F5
browserling.KEY_F6
browserling.KEY_F7
browserling.KEY_F8
browserling.KEY_F9
browserling.KEY_F10
browserling.KEY_F11
browserling.KEY_F12

Controlling screen resolution

You can change the display resolution of the remote browser with setResolution. Note that a resolution change request may be ignored if the platform is not able to change resolutions or the display mode is not supported.


browserling.setResolution(800, 600); // Changes display size to 800x600 if possible

Interacting with clipboard

By default, your clipboard is shared with the remote browser automatically if your browser supports it, but you can also read and write the remote browser's clipboard using the onclipboard callback and setClipboard function:


browserling.onclipboard = function(text) {
    console.log("Remote browser clipboard was updated: " + text);
};

browserling.onload = function() {
    browserling.setClipboard("Text to send to remote browser");
};

This functionality works even if your browser does not have clipboard access or you have disabled automatic sharing with the clipboard option.

Ending your session

When you are done with the browser, you can call the end function to end your session. This is more efficient than simply disconnecting or waiting for idle timeout as it releases the session immediately and decreases your usage limits.


browserling.end();

Support

Please contact us at or use the support forum if you've any issues with the API or have any questions!

Sales

For all sales inquiries, please contact us at or use the contact form.