Starting a Chromium Session
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{
"session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
"embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
"admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}
Dispatch API
Starting a Chromium Session
Initiate a Chromium browser using Hyperbeam
POST
/
v0
/
vm
Starting a Chromium Session
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{
"session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
"embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
"admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}
Parameters
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
boolean
default:false
Flag to enable kiosk mode, which hides the browser navigation UI
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
Show child attributes
number
The amount of time (in seconds) since creation, after which the session will terminate.
number
The amount of time (in seconds) since the last user input, after which the session will terminate.
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.
number
default:60
The amount of time (in seconds) before the session is terminated due to another timeout.
object
Enables touch gestures, such as pinch to zoom for touch screen devices
Show child attributes
Show child attributes
boolean
default:false
Enables switch gestures, which enables features such as swipe left or right for browser history navigation.
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" />string
Custom ID provided for keeping track of usage on a per-tenant basis. See Get Usage for more information.
boolean
default:false
If true, users cannot control the browser by default, and need to be manually
granted access by an admin user
string
default:"NA"
The server region:
NA → North America, EU → Europe, AS → Asiaboolean | 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
Show child attributes
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).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.boolean
default:false
Flag to install an adblock extension on the cloud browser
boolean
default:false
deprecated
Deprecated. See the
adblock flag. Flag to install an adblock extension on the cloud browserboolean
default:false
Flag to install a drawing and annotation extension on the cloud browser
object
Used to install custom Chrome extensions.
(Max Size 1MB).
Show child attributes
Show child attributes
string
Contains the path to your custom Chrome extension.
boolean
default:false
Enables WebGL. Some games and interactive activities require WebGL
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.
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.
number
default:24
Integer frame rate of the browser. Must be in the range [24, 60]
boolean
default:false
Hides the system cursor. Useful if you want to implement a multi-cursor user
interface.
string | object
default:"duckduckgo"
Sets the default search engine that Chromium uses:
“duckduckgo” | “ecosia” | “google” | “startpage” | “brave”How to use custom search engine
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}” }string
Sets the user agent to a preset value. Currently only
"chrome_android" is supported.boolean
default:false
Enables dark mode
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.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
Show child attributes
string
default:"smooth"
Possible values are
"sharp", "smooth", and "blocky".
Enabling sharp mode triples the required bandwidth. You can view our bandwidth recommendations in the Streaming FAQ.
object
Set the browser’s locale and country.
Show child attributes
Show child attributes
string
A comma-delimited list of languages, see the Accept-Language header.
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.
{
"session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
"embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
"admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}
Response
string
The ID of the cloud computer session
string
A URL you can load into the web client on your
website
string
A token that grants access to an exclusive subset of the client-side web SDK.
Needed for setting permissions and programmatic navigation