Starting a Chromium Session

POST

curl --request POST \
  --url https://engine.hyperbeam.com/v0/vm \
  --header 'Authorization: Bearer <token>' \
  --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.

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

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".

Enabling sharp mode triples the required bandwidth. You can view our bandwidth recommendations in the Streaming FAQ.

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.

{
  "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

Dispatch Endpoints Starting a Android Emulator

curl --request POST \
  --url https://engine.hyperbeam.com/v0/vm \
  --header 'Authorization: Bearer <token>' \
  --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"
}

Home

Guides

REST API

Client SDKs

Starting a Chromium Session

Parameters

Response

Home

Guides

REST API

Client SDKs

​Parameters

​Response

Parameters

Response