Ghost Browser API

The Ghost Browser API is primarily designed for extension developers and AI tools to interact with Ghost Browser's special features, such as Identities.

Ghost Browser's API offers a function called openTab that lets your extension or tool open a new browser tab with customized settings. To control how the tab behaves, you provide an object—named OpenTabParams —that contains a range of optional properties. This approach gives you full control over where and how the new tab appears, especially useful when working with Ghost Browser's special feature of Identities.


Additionally, as of v 2.4.1.1, we extend several parts of the Chrome Extensions API to work seamlessly with Ghost Browser’s Identity system. Notably, the chrome.cookies API now supports per-Identity cookie access, enabling cookie operations that are scoped to a specific Identity.

OpenTabParams

chrome.ghostPublicAPI.openTab(OpenTabParams, callback)

The OpenTabParams object supports the following optional properties:

  • url

    URL to open.

    identity

    The ID of the Identity in which the tab should be opened.

    • The Identity ID can be found in the Identity Manager (see the section below) or in the "Getting IDs Programmatically" section.
    • An empty string value equals the Default Identity identifier.
    • There are 2 named constants in the ghostPublicAPI scope:
      • NEW_TEMPORARY_IDENTITY: Opens a tab in a new Temporary Identity.

      • DEFAULT_IDENTITY: Opens a tab in the Default Identity.

        Note: Please use the DEFAULT_IDENTITY constant instead of an empty string when referring to the Default Identity.

        index

        Insert the tab at a specific index in the active window (if possible) to control its position.

    • Use "0" to set it as the first tab, "1" to set it after the first tab, etc.

      active

      Controls whether the tab opens as the active tab.

    • "true" opens the tab as active (default).
    • "false" opens the tab as inactive/background.

  • pinned

    Opens the tab in a pinned state.

  • callback

    A function that returns the tab_id as an argument when the call is successful. This tab_id can then be used to access and control the tab via the standard extensions API.

Note on the 'index' Parameter with Pinned Tabs

  • The index parameter counts tabs from left to right and positions your tab accordingly.
  • However, pinned tabs are always placed before unpinned tabs.
    • For example, if you have 5 pinned tabs open and you set a new tab with pinned=false and an index of 2, the new unpinned tab will be forced to a position to the right of all pinned tabs rather than immediately after the 2nd tab.

chrome.cookies

Ghost Browser extends the standard chrome.cookies API so that cookie operations can be scoped to a specific Identity. The following functions now accept an additional identity parameter:

  • chrome.cookies.get
  • chrome.cookies.set
  • chrome.cookies.getAll
  • chrome.cookies.remove

🔸 Usage

The identity parameter should be set to a valid Identity ID. You can obtain this programmatically from any tab using tab.ghostPublicAPI.identity_id .

Note: If no identity is passed, the call behaves as in Chrome, operating on the Default Identity.

Please scroll down for examples of how to use the extended chrome.cookies API.

Finding the ID of Your Identities

  • Manual Method:

    Open the Identity Manager. The Identity ID is displayed at the top of the screen where you can edit your Identity.

Getting Identity IDs Programmatically

Since there is no UI to view or copy Temporary Identity IDs (due to their dynamic nature and dependency on Workspaces), Ghost Browser extends Chrome’s Tab object with the ghostPublicAPI property. This property includes:

  • ghostPublicAPI.workspace_id [string]

    The Workspace ID where the tab was opened.

    ghostPublicAPI.identity_id [string]

    The Identity ID to which the tab belongs.

    • If a tab is opened in the Default Identity, its identity_id equals the ghostPublicAPI.DEFAULT_IDENTITY constant.

  • ghostPublicAPI.is_temporary_identity [boolean]

    true if the tab is in a Temporary Identity, false otherwise.

Please refer to the API Example 3 at the end of the article.


Checking Your Extension Executes in Ghost Browser

For cross-browser extensions, you can verify if your code is running in Ghost Browser. For example, when executing the openTab function, your extension can include a check specific to Ghost Browser.

typeof chrome.ghostPublicAPI !== 'undefined'

For example, execution of openTab function may look like this:

if (typeof chrome.ghostPublicAPI !== 'undefined') {
    chrome.ghostPublicAPI.openTab(OpenTabParams, callback);
}

API Examples

Example 1

Open a new tab in MyIdentity (using its ID) at 3rd position and in background mode.

chrome.ghostPublicAPI.openTab(
  { url: "http://somesite",
    index: 2, 
    active: false, 
    identity: "<MyIdentity_ID>"},
  function(tab_id) {
      console.log(tab_id)
  }
)

Example 2

Open some site in a new tab with a new Temporary Identity.

chrome.ghostPublicAPI.openTab(
  { url: "http://somesite",
    identity: chrome.ghostPublicAPI.NEW_TEMPORARY_IDENTITY}
)

Example 3

Display Identity ID for active tab of current window

chrome.tabs.query({active: true, currentWindow: true},  function(tabs) {
     if (tabs[0].ghostPublicAPI.is_temporary_identity) {
         alert("Tab opened in a Temporary Identity with ID: " + tabs[0].ghostPublicAPI.identity_id)
     } else {
         alert("Tab opened in a Permanent Identity with ID: " + tabs[0].ghostPublicAPI.identity_id);
     }
 })

Example 4

Print all cookies for the Identity of the Active Tab

chrome.tabs.query({ active: true, lastFocusedWindow: true }, ([tab]) => { 
  const identity = tab.ghostPublicAPI.identity_id;
  chrome.cookies.getAll({ identity }, (cookies) => {
    console.log(cookies);
  });
});