Skip to main content
POST
https://engine.hyperbeam.com
/
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>"
  }
}
'
{
  "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.
​
touch_gestures
object
Enables touch gestures, such as pinch to zoom for touch screen devices
​
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:
​
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).
​
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”
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.
​
locale
object
Set the browser’s locale and country.
{
  "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