The Hyperbeam profile API allows you to persist session state including bookmarks, history, passwords, and cookies which can be loaded into another session at a later time. This allows you to resume sessions without requiring the user to open up web pages or authenticate again.

Want to jump into the code? See our persistence example.

​
Basic Usage

In order to save a session, the profile parameter must be set to true when starting a Chromium session.

​
Example Request

curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": true
}'

After the session is created, the response object will contain a session_id property that you must save in order to load the session state again afterwards.

​
Example Response

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

In order to load and update a previous session, the profile parameter must be set to the session_id you would like to resume when starting a Chromium session.

curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": <session_id>
}'

This will load the profile associated with <session_id> and update its contents when the new session is terminated. Below is a code snippet that showcases a simple profile integration:

app.get("/computer", async (req, res) => {
  // Get the session ID from a query parameter
  // In a real application you want to authenticate the user retrieve the session ID from your database
  let { session_id } = req.query; 
  let profile = true; // profile = true will create a new profile
  if (session_id) {
    try {
      await db.get(session_id);
      profile = session_id; // if session_id is valid, load and update the profile tied to that id
    } catch (e) {
      res.status(400);
      return;
    }
  }
  const settings = {
    profile,
    timeout: {
      offline: 10,
    },
    ublock: true,
  };
  const headers = {
    Authorization: `Bearer ${process.env.HB_API_KEY}`,
  };
  let resp;
  try {
    resp = await axios.post("https://engine.hyperbeam.com/v0/vm", settings, {
      headers,
    });
  } catch (e) {
    console.error(e);
    res.status(501);
    res.send({ message: e.message });
    return;
  }
  const computer = resp.data;
  // if session_id was not defined, then a new profile was created and we want to store the session id tied to the new profile
  // otherwise use the old session id
  session_id = session_id || computer.session_id; 
  await db.put(session_id, {
    session_id,
    sites: [],
  });
  res.send(computer);
});

​
Advanced Usage

For more granular control, you can specify separate profiles to load and overwrite. This is useful if you wish to create a new profile from an existing profile, without altering the original.

curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": {
  "save": <session_id_1>,
  "load": <session_id_2>
 }
}'

​
How Do We Persist Sessions?

When profile is set to true, we encrypt and store the Chrome profile of the session in Amazon S3.

This Chrome profile is associated with the session_id that was returned to you on session creation.

When profile is set to a session ID, we look for a stored Chrome profile that corresponds to that session_id, and decrypt and load the Chrome profile if there is a match.

This results in bookmarks, history, cookies, and passwords being persisted.

Looking for more detailed examples? See our persistence example.

TimeoutsAuthenticating Participants