Starting a Chromium Session

Initiate a Chromium browser using Hyperbeam

POST /v0/vm

Starting a Chromium Session

cURL

curl --request POST \
  --url https://engine.hyperbeam.com/v0/vm \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_url": "<string>",
  "kiosk": true,
  "timeout": {
    "absolute": 123,
    "inactive": 123,
    "offline": 123,
    "warning": 123,
    "webhook": {
      "url": "<string>",
      "bearer": "<string>"
    }
  },
  "touch_gestures": {
    "swipe": true,
    "pinch": true
  },
  "tenant_id": "<string>",
  "control_disable_default": true,
  "region": "<string>",
  "profile": {
    "load": "<string>",
    "save": {}
  },
  "adblock": true,
  "ublock": true,
  "draw": true,
  "extension": {
    "field": "<string>"
  },
  "webgl": true,
  "width": 123,
  "height": 123,
  "fps": 123,
  "hide_cursor": true,
  "search_engine": {},
  "user_agent": "<string>",
  "dark": true,
  "tag": "<string>",
  "quality": {
    "mode": "<string>"
  },
  "locale": {
    "language": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://engine.hyperbeam.com/v0/vm"

payload = {
    "start_url": "<string>",
    "kiosk": True,
    "timeout": {
        "absolute": 123,
        "inactive": 123,
        "offline": 123,
        "warning": 123,
        "webhook": {
            "url": "<string>",
            "bearer": "<string>"
        }
    },
    "touch_gestures": {
        "swipe": True,
        "pinch": True
    },
    "tenant_id": "<string>",
    "control_disable_default": True,
    "region": "<string>",
    "profile": {
        "load": "<string>",
        "save": {}
    },
    "adblock": True,
    "ublock": True,
    "draw": True,
    "extension": { "field": "<string>" },
    "webgl": True,
    "width": 123,
    "height": 123,
    "fps": 123,
    "hide_cursor": True,
    "search_engine": {},
    "user_agent": "<string>",
    "dark": True,
    "tag": "<string>",
    "quality": { "mode": "<string>" },
    "locale": {
        "language": "<string>",
        "country": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    start_url: '<string>',
    kiosk: true,
    timeout: {
      absolute: 123,
      inactive: 123,
      offline: 123,
      warning: 123,
      webhook: {url: '<string>', bearer: '<string>'}
    },
    touch_gestures: {swipe: true, pinch: true},
    tenant_id: '<string>',
    control_disable_default: true,
    region: '<string>',
    profile: {load: '<string>', save: {}},
    adblock: true,
    ublock: true,
    draw: true,
    extension: {field: '<string>'},
    webgl: true,
    width: 123,
    height: 123,
    fps: 123,
    hide_cursor: true,
    search_engine: {},
    user_agent: '<string>',
    dark: true,
    tag: '<string>',
    quality: {mode: '<string>'},
    locale: {language: '<string>', country: '<string>'}
  })
};

fetch('https://engine.hyperbeam.com/v0/vm', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://engine.hyperbeam.com/v0/vm",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'start_url' => '<string>',
    'kiosk' => true,
    'timeout' => [
        'absolute' => 123,
        'inactive' => 123,
        'offline' => 123,
        'warning' => 123,
        'webhook' => [
                'url' => '<string>',
                'bearer' => '<string>'
        ]
    ],
    'touch_gestures' => [
        'swipe' => true,
        'pinch' => true
    ],
    'tenant_id' => '<string>',
    'control_disable_default' => true,
    'region' => '<string>',
    'profile' => [
        'load' => '<string>',
        'save' => [
                
        ]
    ],
    'adblock' => true,
    'ublock' => true,
    'draw' => true,
    'extension' => [
        'field' => '<string>'
    ],
    'webgl' => true,
    'width' => 123,
    'height' => 123,
    'fps' => 123,
    'hide_cursor' => true,
    'search_engine' => [
        
    ],
    'user_agent' => '<string>',
    'dark' => true,
    'tag' => '<string>',
    'quality' => [
        'mode' => '<string>'
    ],
    'locale' => [
        'language' => '<string>',
        'country' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://engine.hyperbeam.com/v0/vm"

	payload := strings.NewReader("{\n  \"start_url\": \"<string>\",\n  \"kiosk\": true,\n  \"timeout\": {\n    \"absolute\": 123,\n    \"inactive\": 123,\n    \"offline\": 123,\n    \"warning\": 123,\n    \"webhook\": {\n      \"url\": \"<string>\",\n      \"bearer\": \"<string>\"\n    }\n  },\n  \"touch_gestures\": {\n    \"swipe\": true,\n    \"pinch\": true\n  },\n  \"tenant_id\": \"<string>\",\n  \"control_disable_default\": true,\n  \"region\": \"<string>\",\n  \"profile\": {\n    \"load\": \"<string>\",\n    \"save\": {}\n  },\n  \"adblock\": true,\n  \"ublock\": true,\n  \"draw\": true,\n  \"extension\": {\n    \"field\": \"<string>\"\n  },\n  \"webgl\": true,\n  \"width\": 123,\n  \"height\": 123,\n  \"fps\": 123,\n  \"hide_cursor\": true,\n  \"search_engine\": {},\n  \"user_agent\": \"<string>\",\n  \"dark\": true,\n  \"tag\": \"<string>\",\n  \"quality\": {\n    \"mode\": \"<string>\"\n  },\n  \"locale\": {\n    \"language\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://engine.hyperbeam.com/v0/vm")
  .header("Content-Type", "application/json")
  .body("{\n  \"start_url\": \"<string>\",\n  \"kiosk\": true,\n  \"timeout\": {\n    \"absolute\": 123,\n    \"inactive\": 123,\n    \"offline\": 123,\n    \"warning\": 123,\n    \"webhook\": {\n      \"url\": \"<string>\",\n      \"bearer\": \"<string>\"\n    }\n  },\n  \"touch_gestures\": {\n    \"swipe\": true,\n    \"pinch\": true\n  },\n  \"tenant_id\": \"<string>\",\n  \"control_disable_default\": true,\n  \"region\": \"<string>\",\n  \"profile\": {\n    \"load\": \"<string>\",\n    \"save\": {}\n  },\n  \"adblock\": true,\n  \"ublock\": true,\n  \"draw\": true,\n  \"extension\": {\n    \"field\": \"<string>\"\n  },\n  \"webgl\": true,\n  \"width\": 123,\n  \"height\": 123,\n  \"fps\": 123,\n  \"hide_cursor\": true,\n  \"search_engine\": {},\n  \"user_agent\": \"<string>\",\n  \"dark\": true,\n  \"tag\": \"<string>\",\n  \"quality\": {\n    \"mode\": \"<string>\"\n  },\n  \"locale\": {\n    \"language\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://engine.hyperbeam.com/v0/vm")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start_url\": \"<string>\",\n  \"kiosk\": true,\n  \"timeout\": {\n    \"absolute\": 123,\n    \"inactive\": 123,\n    \"offline\": 123,\n    \"warning\": 123,\n    \"webhook\": {\n      \"url\": \"<string>\",\n      \"bearer\": \"<string>\"\n    }\n  },\n  \"touch_gestures\": {\n    \"swipe\": true,\n    \"pinch\": true\n  },\n  \"tenant_id\": \"<string>\",\n  \"control_disable_default\": true,\n  \"region\": \"<string>\",\n  \"profile\": {\n    \"load\": \"<string>\",\n    \"save\": {}\n  },\n  \"adblock\": true,\n  \"ublock\": true,\n  \"draw\": true,\n  \"extension\": {\n    \"field\": \"<string>\"\n  },\n  \"webgl\": true,\n  \"width\": 123,\n  \"height\": 123,\n  \"fps\": 123,\n  \"hide_cursor\": true,\n  \"search_engine\": {},\n  \"user_agent\": \"<string>\",\n  \"dark\": true,\n  \"tag\": \"<string>\",\n  \"quality\": {\n    \"mode\": \"<string>\"\n  },\n  \"locale\": {\n    \"language\": \"<string>\",\n    \"country\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

Example response

{
  "session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
  "embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
  "admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}

Parameters

start_url · string · default: "about:blank"

The initial URL that is set in the browser. If unset, and a profile is loaded, tabs from the profile are restored

kiosk · boolean · default: false

Flag to enable kiosk mode, which hides the browser navigation UI

timeout · object

Timeouts determine when a session will be automatically terminated. Also, when a timeout (or timeout warning) is triggered, a webhook event will be sent to the URL specified by the webhook timeout parameter.

You can reset these values for live sessions by hitting the <embed_url>/timeout endpoint. See example.

Show child attributes

absolute · number

The amount of time (in seconds) since creation, after which the session will terminate.

inactive · number

The amount of time (in seconds) since the last user input, after which the session will terminate.

offline · number · default: 3600

The amount of time (in seconds) that no users are connected, after which the session will terminate. Resets when a user connects.

warning · number · default: 60

The amount of time (in seconds) before the session is terminated due to another timeout.

webhook · object

Show child attributes

url · string

The URL to send the timeout webhook event to.

bearer · string

The Bearer Token to send with the webhook.

touch_gestures · object

Enables touch gestures, such as pinch to zoom for touch screen devices

Show child attributes

swipe · boolean · default: false

Enables switch gestures, which enables features such as swipe left or right for browser history navigation.

pinch · boolean · default: false

Enables the pinch gestures, which enables features such as pinch to zoom. The zoom can be reset on desktop by pressing the Escape key or refreshing the browser page.

You will need to disable viewport scaling to enable pinch-to-zoom on the virtual browser. Include the following meta tag in your HTML: <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />

tenant_id · string

Custom ID provided for keeping track of usage on a per-tenant basis. See Get Usage for more information.

control_disable_default · boolean · default: false

If true, users cannot control the browser by default, and need to be manually granted access by an admin user

region · string · default: "NA"

The server region: NA → North America, EU → Europe, AS → Asia

profile · boolean | string | object

Used to save and load Chrome profiles including bookmarks, history, passwords, cookies etc. true will create a new profile, while passing in a session ID of an existing profile will load and update the profile. For advanced usage, you can provide an object that specifies the session IDs of the profile you wish to load and the profile you wish to overwrite:

Show child attributes

load · string

ID of the session you want to load in the cloud browser (a profile is encrypted browser state from a previous session, with the profile ID being its session_id, see response body).

save · boolean | string · default: "false"

save = true creates a new persisted profile you can load from. If a session ID is provided, then the profile associated with the session ID will be overwritten.

adblock · boolean · default: false

Flag to install an adblock extension on the cloud browser

ublock · boolean · default: false · deprecated

Deprecated. See the adblock flag. Flag to install an adblock extension on the cloud browser

draw · boolean · default: false

Flag to install a drawing and annotation extension on the cloud browser

extension · object

Used to install custom Chrome extensions. (Max Size 1MB).

Show child attributes

field · string

Contains the path to your custom Chrome extension.

webgl · boolean · default: false

Enables WebGL. Some games and interactive activities require WebGL

width · number · default: 1280

Width of the browser in pixels. If set, height must be set as well.

The max number of pixels (width height) is capped at 1920*1080.

height · number · default: 720

Height of the browser in pixels. If set, width must be set as well.

The max number of pixels (width height) is capped at 1920*1080.

fps · number · default: 24

Integer frame rate of the browser. Must be in the range [24, 60]

hide_cursor · boolean · default: false

Hides the system cursor. Useful if you want to implement a multi-cursor user interface.

search_engine · string | object · default: "duckduckgo"

Sets the default search engine that Chromium uses: “duckduckgo” | “ecosia” | “google” | “startpage” | “brave”

How to use custom search engine

You can use a custom search engine by passing in an object as follows: { “name”: “foo”, “keyword”: “f”, “url”: “https://foo.com/search?q={searchTerms}”, “suggestions_url”: “https://foo.com/suggest?q={searchTerms}” }

user_agent · string

Sets the user agent to a preset value. Currently only "chrome_android" is supported.

dark · boolean · default: false

Enables dark mode

tag · string

The tag property enforces uniqueness. If a session with tag "A" is already running and you attempt to make another session with tag "A", the endpoint will not create a new instance and will instead return the session_id and embed_url of the existing session.

quality · object

Used to toggle between sharp, smooth, and blocky quality modes. Sharp mode is ideal for situations where reading small text is important. Smooth mode is ideal for anything involving movement (e.g. videos, dynamic activities). Blocky mode is ideal for clients with poor internet connectivity.

Show child attributes

mode · string · default: "smooth"

Possible values are "sharp", "smooth", and "blocky".

locale · object

Set the browser’s locale and country.

Show child attributes

language · string

A comma-delimited list of languages, see the Accept-Language header.

country · string

The ISO 3166 A-2 country code, e.g. US for the United States, CA for Canada. You can retrieve the user’s country by using an IP database like MaxMind GeoLite2.

Example response

{
  "session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
  "embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
  "admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}

Response

session_id · string

The ID of the cloud computer session

embed_url · string

A URL you can load into the web client on your website

admin_token · string

A token that grants access to an exclusive subset of the client-side web SDK. Needed for setting permissions and programmatic navigation