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 macOS, Windows and Android platforms, but we're soon adding 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 click left, right, middle, back and forward buttons, drag, drag and drop, and move the mouse while any of the 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);

Click any mouse button:


browserling.click(x, y, button);

All methods that use mouse buttons accept any of these 5 buttons:


browserling.MOUSE_LEFT
browserling.MOUSE_MIDDLE // Same as clicking the mouse wheel
browserling.MOUSE_RIGHT
browserling.MOUSE_BACK // Also known as the "Mouse 4 button"
browserling.MOUSE_FORWARD // Also known as the "Mouse 5 button"

You can also use these aliases for left click, right click or middle click (also known as wheel click):


browserling.leftClick(x, y);
browserling.rightClick(x, y);
browserling.wheelClick(x, y);

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


browserling.mouseDown(x, y, button)

Release button:


browserling.mouseUp(x, y)

Scroll mouse wheel:

You can specify the scroll amount in pixels both the vertically (dy) and horizontally (dx). A single increment of the wheel is usually 100 pixels but it can be smaller on more precise devices that allow scrolling, such as touchpads and trackpoints.


browserling.mouseWheel(x, y, dx, dy)

You can also use these aliases to scroll up, down, left or right:


browserling.wheelUp(x, y); // Same as browserling.mouseWheel(x, y, 0, -100)
browserling.wheelDown(x, y); // Same as browserling.mouseWheel(x, y, 0, 100)
browserling.wheelLeft(x, y); // Same as browserling.mouseWheel(x, y, -100, 0)
browserling.wheelRight(x, y); // Same as browserling.mouseWheel(x, y, 100, 0)

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:

The typeText method presses keys that are needed to produce the specified text, assuming a US English layout.


browserling.typeText("MyPa$sw0rd!"); // Adds Shift presses before capital letters and special characters

You can use any characters from any language and even type emojis:


browserling.typeText("✅🐎🔋📎");

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(browserling.KEY_A); // Types "a"
browserling.keyPress(browserling.KEY_1); // Types "1"
browserling.keyPress(browserling.KEY_B); // Types "b"

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


browserling.keyDown(key)

For example:


browserling.keyDown(browserling.KEY_CTRL); // Press left control
browserling.keyPress(browserling.KEY_A); // Presses Ctrl+A
browserling.keyUp(browserling.KEY_CTRL); // Release left control

Release a key:


browserling.keyUp(key)

For example:


browserling.keyUp(browserling.KEY_META_LEFT); // Release left meta
browserling.keyUp(browserling.KEY_ALT_RIGHT); // Release right alt

You can use both left-handed and right-handed modifier keys. Modifier keys are Control, Alt ("option key" on Mac), Shift and Meta ("command key" on Mac, "windows logo key" on Windows).

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


browserling.KEY_F1..KEY_F32 // Function keys from F1 to F32
browserling.KEY_0..KEY_9 // Digit keys from 0 to 9
browserling.KEY_A..KEY_Z // Letter keys from A to Z
browserling.KEY_BACKSPACE
browserling.KEY_TAB
browserling.KEY_CLEAR
browserling.KEY_ENTER
browserling.KEY_PAUSE
browserling.KEY_ESCAPE
browserling.KEY_SPACE
browserling.KEY_PAGE_UP
browserling.KEY_PAGE_DOWN
browserling.KEY_END
browserling.KEY_HOME
browserling.KEY_LEFT // Arrow keys
browserling.KEY_UP
browserling.KEY_RIGHT
browserling.KEY_DOWN
browserling.KEY_PRINT_SCREEN // Same as KEY_SYSRQ
browserling.KEY_DELETE
browserling.KEY_MENU // Context menu key
browserling.KEY_SEMICOLON
browserling.KEY_EQUAL
browserling.KEY_COMMA
browserling.KEY_MINUS
browserling.KEY_PERIOD
browserling.KEY_SLASH
browserling.KEY_BACKQUOTE
browserling.KEY_BRACKET_LEFT
browserling.KEY_BACKSLASH
browserling.KEY_BRACKET_RIGHT
browserling.KEY_QUOTE
browserling.KEY_SHIFT_LEFT // Same as KEY_SHIFT
browserling.KEY_SHIFT_RIGHT
browserling.KEY_CTRL_LEFT // Same as KEY_CTRL
browserling.KEY_CTRL_RIGHT
browserling.KEY_ALT_LEFT // Same as KEY_ALT
browserling.KEY_ALT_RIGHT
browserling.KEY_META_LEFT // Same as KEY_META
browserling.KEY_META_RIGHT
browserling.KEY_CAPS_LOCK
browserling.KEY_NUM_LOCK
browserling.KEY_SCROLL_LOCK
browserling.KEY_NUMPAD_CLEAR
browserling.KEY_NUMPAD_ENTER
browserling.KEY_NUMPAD_MULTIPLY
browserling.KEY_NUMPAD_ADD
browserling.KEY_NUMPAD_SUBTRACT
browserling.KEY_NUMPAD_DECIMAL
browserling.KEY_NUMPAD_DIVIDE
browserling.KEY_NUMPAD_EQUAL
browserling.KEY_NUMPAD_COMMA
browserling.KEY_NUMPAD_0..KEY_NUMPAD_9 // Numpad digit keys from 0 to 9

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.