API documentation

JustBrowser local REST API

The desktop app serves a REST API on your own machine, on by default: with an active subscription or trial it listens on 127.0.0.1 from the moment the app starts. It can be switched off, stopped or moved to another port from the AI page in the app, and it does not start at all on a team seat or without an entitlement, so a refused connection is the first thing to check there. Use it to create profiles, assign proxies, start browsers and drive them from Playwright, Puppeteer or Selenium over CDP. This page is generated from the OpenAPI document the app itself serves, version 2.2.0: 108 operations across 15 groups. Download the OpenAPI JSON.

Local only

The API is bound to 127.0.0.1 on port 36542 (configurable in the app). Base URL:

http://127.0.0.1:36542/api/v1

There is no hosted API. The only server is the one the desktop app starts on your machine, so the app must be running, and there is nothing to call at api.justbrowser.app. The request itself never leaves 127.0.0.1, but the operation can, exactly as the same action in the app does: creating a profile while signed in asks justbrowser.app to generate the fingerprint (a local draw is used when signed out or offline), sync uploads the profile to cloud storage, teams, shares, licence refresh and the proxy catalogue call justbrowser.app, and a proxy test connects through the proxy. Nothing extra is sent because you used the API.

Authentication

Every request under /api/v1 carries Authorization: Bearer <token> (the scheme in any case). The token is shown on the AI page in the app, which also writes a plain-text briefing of this API for pasting into an agent. A missing or wrong token returns 401.

One route needs no token: GET /health at the server root (http://127.0.0.1:36542/health, outside /api/v1; HEAD and a query string work too) answers {"status": "ok", "version": …, "timestamp": …} while the app runs with its API on, for a monitor.

A website cannot read the API's answers: only a page served from this computer (an origin on 127.0.0.1, localhost or [::1]) gets the browser's permission (CORS). Call the API from a script, an agent or a server process.

The API is available on an active subscription and during the trial. Team seats can run shared profiles but have no API access of their own.

Profiles start headless by default

POST /profiles/{id}/start with no body launches a headless browser. Send {"headless": false} as JSON when you want a window. The response carries cdp_url, a ws://127.0.0.1:PORT/devtools/browser/… endpoint. Headless or not, a start takes the profile's cloud lock, and its session uploads when it stops.

Responses and errors

Every endpoint under /api/v1 wraps its result in {"data": …}, except GET /docs, which returns the OpenAPI document itself. Errors come back with a non-2xx status and {"error": {"code", "message"}}. Branch on code, not the message, which varies by layer. details is an array of issues for VALIDATION_ERROR and SETTING_NOT_WRITABLE, and an object for other errors that carry one (heldBy, sameDevice, limitBytes…). Bodies are JSON; send Content-Type: application/json. JSON types are not converted: a number sent for a text field is refused. A body may be up to 3 MiB; a larger one answers 413: send it in smaller parts, for example fewer cookies in each import.

Each operation below lists its own answers. Any route can also answer 401 (the token), 403 SUBSCRIPTION_REQUIRED (the account no longer includes the API), 503 PLAN_CHECK_PENDING (the plan is not confirmed yet; retry after Retry-After), 404 ROUTE_NOT_FOUND, 400 INVALID_JSON, 415 (not JSON), 500 (an unexpected failure) and 504 SHELL_RPC_TIMEOUT (the app did not answer in time: the change may still have gone through, so check before trying again). Under each operation, “Also, as any route” lists the ones that apply to it: 401, 403, 500 and 503 everywhere, and 400, 413 and 415 where a body is sent (POST, PUT, PATCH).

Quickstart

Four calls: create a profile, start it, connect over CDP, stop it. The start call is the one people get wrong.

Start a profile with a visible window (curl)

curl -s -X POST http://127.0.0.1:36542/api/v1/profiles/$PROFILE_ID/start \
  -H "Authorization: Bearer $JB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"headless": false}'

# {"data": {"profile_id": "…", "status": "running",
#           "cdp_url": "ws://127.0.0.1:41287/devtools/browser/…",
#           "launched_at": "2026-09-22T09:14:02Z"}}

Python with Playwright

import os, requests
from playwright.sync_api import sync_playwright

BASE = "http://127.0.0.1:36542/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['JB_TOKEN']}"}

# 1. Create a profile. Its fingerprint is generated with it.
profile = requests.post(f"{BASE}/profiles", json={"name": "shop-eu-1"}, headers=HEADERS).json()["data"]

# 2. Start it. The API starts profiles HEADLESS unless you say otherwise.
r = requests.post(f"{BASE}/profiles/{profile['id']}/start", json={"headless": False}, headers=HEADERS).json()
if "error" in r:
    raise RuntimeError(f"{r['error']['code']}: {r['error']['message']}")
cdp_url = r["data"]["cdp_url"]

# 3. Drive it over CDP. Use the profile's own context — never new_context().
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp_url)
    context = browser.contexts[0]
    page = context.pages[0] if context.pages else context.new_page()
    page.goto("https://example.com")
    browser.close()   # disconnects only; the profile keeps running

# 4. Stop it when you are done.
requests.post(f"{BASE}/profiles/{profile['id']}/stop", headers=HEADERS)

Node with Playwright

import { chromium } from "playwright";

const BASE = "http://127.0.0.1:36542/api/v1";
const headers = { Authorization: `Bearer ${process.env.JB_TOKEN}`, "Content-Type": "application/json" };

const { data: profile } = await (await fetch(`${BASE}/profiles`, { method: "POST", headers, body: JSON.stringify({ name: "shop-eu-1" }) })).json();
const started = await (await fetch(`${BASE}/profiles/${profile.id}/start`, { method: "POST", headers, body: JSON.stringify({ headless: false }) })).json();
if (started.error) throw new Error(`${started.error.code}: ${started.error.message}`);

const browser = await chromium.connectOverCDP(started.data.cdp_url);
const context = browser.contexts()[0];            // the profile's own context — never browser.newContext()
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
await browser.close();                            // disconnects only; the profile keeps running

await fetch(`${BASE}/profiles/${profile.id}/stop`, { method: "POST", headers });

Selenium

# GET /profiles/{id}/selenium returns the debugger address of a RUNNING profile:
# {"data": {"selenium": {"debugger_address": "127.0.0.1:41287", "capabilities": {...}}}}
#
# ChromeDriver must match the profile's Chromium major. Selenium Manager picks a
# driver for the Chrome installed on your machine, not for JustBrowser, so pin it —
# an unpinned driver fails with "This version of ChromeDriver only supports Chrome
# version N". GET /profiles/{id}/chromium tells you which core the profile runs.
from selenium import webdriver
opts = webdriver.ChromeOptions()
opts.browser_version = "152"                                            # or Service(executable_path=".../chromedriver-152")
opts.add_experimental_option("debuggerAddress", "127.0.0.1:41287")   # from the response above
driver = webdriver.Chrome(options=opts)                                 # attaches; does not launch a browser
# driver.quit() only disconnects — call POST /profiles/{id}/stop to end the session.
# Stock ChromeDriver adds its own window.cdc_* globals to every page it drives;
# Playwright and Puppeteer avoid that.

Error shape

{"error": {"code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [{"instancePath": "/name", "keyword": "minLength", "message": "must NOT have fewer than 1 characters"}]}}   // 400 — details is an array; the message varies by layer
{"error": {"code": "INVALID_JSON", "message": "Request body is not valid JSON"}}   // 400
{"error": {"code": "UNAUTHORIZED", "message": "Missing Authorization header. Include: Authorization: Bearer <token>"}}   // 401
{"error": {"code": "NOT_FOUND", "message": "Profile with id 'x' not found"}}   // 404
{"error": {"code": "PROFILE_IN_USE", "message": "Profile is currently locked by another device (in use by <user> on <device>).", "details": {"heldBy": {…}}}}   // 409
{"error": {"code": "FST_ERR_CTP_BODY_TOO_LARGE", "message": "The request body is larger than the local API accepts (3 MiB). Send it in smaller parts, for example fewer cookies in each import.", "details": {"limitBytes": 3145728}}}   // 413

Rules that save an afternoon

  • Use the profile's own context. After connectOverCDP, work in contexts()[0]. Calling newContext() opens an incognito context inside the same browser process: it keeps the profile's fingerprint and proxy, which are set process-wide at launch, but starts with none of its cookies or storage, and nothing done in it is saved to the profile.
  • Closing your client does not stop the profile, in Playwright and Selenium. Playwright's browser.close() on a connectOverCDP browser only disconnects, and Selenium's driver.quit() leaves the browser running. Puppeteer is the exception: browser.close() on a connected browser sends Browser.close and shuts the profile down; use browser.disconnect() to detach. Call POST /profiles/{id}/stop to end a session.
  • A second client can attach while the app holds its own connection. On a headless start (the default) the app keeps its own CDP session open for the life of the profile and yours attaches alongside it on the same cdp_url. With {"headless": false} the app detaches right after launch, so your client is the only one attached.
  • Headless is not headed. A headless session has no real window, so screen and viewport geometry follow headless defaults rather than a desktop. Attaching a CDP client does not by itself change what pages see: navigator.bluetooth, getBattery, mediaDevices and keyboard are all present with a debugger attached, and navigator.webdriver is false either way. Send {"headless": false} when you need a real window and desktop screen geometry.
  • Bulk creation, not CSV. POST /profiles/bulk creates up to 100 profiles per call from a naming pattern; POST /profiles/import restores an encrypted archive. There is no CSV importer.
  • Every start takes the profile's cloud lock, headless or not. A synced profile that is open on another device answers 409 PROFILE_IN_USE (the holder is in details.heldBy) until that device closes it, or its lock goes stale after 60 seconds without a heartbeat; another copy of this computer's app data gets the same answer after about a minute, with details.sameDevice. DELETE /profiles/{id}/lock releases it: owner-only, for a profile left in use by a computer that crashed or went offline; the device that held it closes the profile without uploading its session. A profile with no cloud copy answers {"forced": false}.

Reference

All paths are relative to http://127.0.0.1:36542/api/v1.

PROFILES

Create, list, update and delete profiles. Every profile is generated with a complete set of device settings.

List profiles

The profiles on this computer, as the app lists them (its database), filtered and sorted. Without filters every profile is listed.

Parameters

searchquery · stringPart of the profile's name, in any case
statusquery · stringOnly profiles with this runtime statusone of "stopped", "running", "error", "launching", "syncing"
folder_idquery · stringOnly the profiles in this folder
tag_idsquery · stringTag ids, comma-separated: the profiles that carry any of them
sort_byquery · stringSort fieldone of "name", "status", "last_used_at", "detection_score", "created_at", "display_index"default "created_at"
sort_directionquery · stringSort directionone of "asc", "desc"default "desc"

Responses

  • 200The profiles that match

    Response body

    data*object
    profiles*array of Profile
    total*integerHow many profiles match (the length of profiles)
    filters*objectThe filters this answer applied
    searchstring | null
    statusstring | null
    folder_idstring | null
    tag_idsarray of string | null
    sort_bystring
    sort_directionstring
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. An unknown status, sort_by or sort_direction is refused, naming the allowed values.
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Create a profile

Creates a profile and generates its fingerprint (justbrowser.app's population data when signed in, a local draw otherwise). os, browser, locale and device_type steer the fingerprint; leave them out for the defaults (windows, chrome, en-US, desktop). Nothing is left behind when the fingerprint cannot be made.

Request body (JSON, required)

name*string
folder_idstring | nullThe folder to put it in (null or absent: none)
notesstring
osstringThe fingerprint's operating system (default windows)one of "", "windows", "macos", "linux"
browserstringThe fingerprint's browser (default chrome)one of "", "chrome", "firefox"
localestringThe fingerprint's language and region, for example de-DE (default en-US)
device_typestringdesktop (default), or mobile for a phone (Android)one of "", "desktop", "mobile"

Responses

  • 201The profile, with fingerprint_generated

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 402The plan's profile limit is reached, or the account has not started its trial (PLAN_LIMIT_REACHED, TRIAL_REQUIRED).
  • 404The folder_id names no folder (NOT_FOUND); nothing was created.
  • 422The fingerprint could not be generated (FINGERPRINT_GENERATION_FAILED); nothing was created.
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds).
  • Also, as any route: 401, 403, 413, 415, 500 (Responses and errors)

Create up to 100 profiles from a naming pattern

Creates count profiles, each with its own generated fingerprint, as the app's Bulk create does. naming_pattern's {n} is the number (" {n}" is added when the pattern has none). With proxy_id, each profile gets the proxy, and the time zone and language of where it exits (from its last successful test) replace locale and the drawn time zone. With template_id, the fingerprints follow the template. A profile that could not be made is a failed line; the call itself succeeds.

Request body (JSON, required)

count*integer
naming_patternstring{n} is replaced by the number ("Profile {n}" by default)
template_idstringFingerprints of this template's shape
osstringone of "windows", "macos", "linux"
browserstringone of "chrome", "firefox"
localestringDefault en-US; with proxy_id, the proxy's exit language replaces it
device_typestringone of "desktop", "mobile"
proxy_idstringGive each profile this proxy, and its exit's time zone and language
folder_idstring
tag_idsarray of string

Responses

  • 200One line per profile

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 402The plan's profile limit (PLAN_LIMIT_REACHED, TRIAL_REQUIRED).
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds).
  • Also, as any route: 401, 403, 413, 415, 500 (Responses and errors)

Get a profile

Parameters

id*path · string

Responses

  • 200The profile

    Response body

    data*Profile
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Update a profile

Changes name, folder_id, notes, automatic_timezone. The answer is the profile as written. Other fields are read-only: sent with the value the profile has (a GET → edit → PUT round trip) they are ignored; status, chromium_version or extra_params sent with another value is a 400 (status changes with POST /profiles/{id}/start and /stop, the engine with POST /profiles/{id}/chromium). The edit reaches the account's other computers with cloud sync on.

Parameters

id*path · string

Request body (JSON)

namestring
folder_idstring | nullA folder id, or null for no folder
notesstring
automatic_timezonebooleanMatch the profile's time zone and location to where its proxy exits, at each launch

Responses

  • 200The profile as written

    Response body

    data*Profile
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also a read-only field sent with another value; details.editable lists the fields this call changes. Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND). Or the folder_id names no folder (NOT_FOUND); nothing was written.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete a profile

Deletes the profile, its browser data on this computer and its cloud copy. Refused with 409 while the profile is in use: its browser is running or still launching, or an upload of it is in flight (after a stop, an edit, auto-sync or POST /profiles/{id}/sync). Stop the browser first. A script that stops, edits or syncs a profile and then deletes it straight away should retry the delete after a 409 until the upload is done.

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*string
    notestringSet when the app's background service had no such profile and only this computer's list had it: it is gone from both now
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409Profile in use (error.code PROFILE_RUNNING). error.details.reason says why: running, launching, or pushing (an upload of it is in flight: after a stop, an edit, auto-sync or POST /profiles/{id}/sync). Retry once it has finished.
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Get profile runtime status

Whether its browser runs here, its CDP address, and its proxy.

Parameters

id*path · string

Responses

  • 200Profile status

    Response body

    data*object
    id*string
    name*string
    status*stringone of "stopped", "running", "error", "launching", "syncing"
    consistency_scorenumber | null
    detection_scorenumber | null
    last_used_atstring | null
    proxy*object
    configuredbooleanWhether the profile has a proxy
    statusstring | nullThe proxy's last test resultone of "untested", "connected", "failed", null
    browser*object
    runningbooleanWhether its browser runs on this computer now
    cdp_urlstring | nullThe CDP WebSocket URL while it runs
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

RUNNING A BROWSER

Launch a profile, get its CDP endpoint for Playwright, Puppeteer or Selenium, and stop it.

Start a profile browser

Launch a browser instance for a profile and return the CDP WebSocket URL for automation. Headless or not, a start of a profile in your cloud takes its cloud lock (another device cannot open it meanwhile), downloads a newer cloud version first when nothing made here is unsent, and uploads the session when the profile stops (with cloud sync on). A start answers once the browser is up: seconds, longer when it first waits for an upload of the profile (up to 120 s), downloads the profile or its engine, or waits for its cloud lock. Headless or not, the session is in the profile's activity in the app like one started there: opened (through the local API, in the background when headless) and closed, and a start that failed.

Parameters

id*path · string

Request body (JSON)

headlessbooleanLaunch in headless mode (default: true for API); false opens a windowdefault true

Responses

  • 200Browser launched

    Response body

    data*object
    profile_id*string
    status*stringone of "running"
    cdp_url*stringCDP WebSocket URL — use with Playwright connectOverCDP() or Puppeteer connect()
    launched_at*string (date-time)When the browser started (as GET /profiles/{id}/cdp reports it)
  • 400The body is not {"headless": true|false} (VALIDATION_ERROR), or the profile has no fingerprint (NO_FINGERPRINT: POST /profiles/{id}/fingerprint makes one). Or the body is not JSON (INVALID_JSON).
  • 402This account has not started its trial yet (error.code TRIAL_REQUIRED). Or this account has no active plan (its plan ended or is paused, or it holds only a team seat) and the profile is not one of its 5 own profiles used most recently, a profile open now counting as used now (error.code PROFILE_OVER_PLAN_LIMIT; error.details.limit is the number): nothing was opened.
  • 403The cloud refused this account the profile (error.code PROFILE_ACCESS_DENIED) when its cloud lock is taken. For example, a team profile while the team owner's subscription is paused. The share checks refuse headless starts too: a profile a team shares with you whose every team refused its proxy login (and that is not also shared with you directly), a profile shared with you directly to view only, or a conflicted copy of a profile shared with you whose share no longer lets you in. error.message says why; error.details has syncProfileId and status. Or this account holds neither a plan nor a team seat, and the profile is shared with it (PROFILE_ACCESS_DENIED, refused before the cloud is asked). A profile saved by a newer version of JustBrowser (error.code APP_UPDATE_REQUIRED): update JustBrowser on this computer. Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404Profile not found on this computer (error.code NOT_FOUND). With error.code PROFILE_ACCESS_DENIED, the profile is still here but its cloud copy is gone for this account: deleted, or no longer shared (when its cloud lock is taken; at any start, headless too, for a profile shared with you directly whose share was stopped and that no team of yours shares, and for a conflicted copy of a profile shared with you).
  • 409Profile already running or starting (error.code ALREADY_RUNNING; also while its folder is being kept as a conflicted copy, replaced with the cloud version or kept as a new profile, error.details.folderHeld ('conflicted-copy', 'cloud-version' or 'keep-as-new'), and when an upload of it was still running after 120 s, error.details.closing: a start first waits for an upload of the profile, the one its last close started, an edit, auto-sync or POST /profiles/{id}/sync), its data is not on this computer yet (NOT_DOWNLOADED: a cloud profile never opened here, or a profile shared with you whose changes here were just kept as a separate profile because its cloud version is newer; a headless launch does not download it, start it once with headless: false), it is open on another device (PROFILE_IN_USE: error.details.heldBy names the person and the device; it is also the answer, after about a minute, for another copy of this computer's app data (a copied app data folder or a cloned virtual machine), with error.details.sameDevice true, and while the owner prepares it for sharing on another device), or a profile shared with you has changes here that the team's newer copy doesn't have and that could not be kept as a separate profile first (LOCAL_COPY_NOT_KEPT; nothing was downloaded), or it is a profile shared with you that its owner's app has not prepared yet (SHARE_NOT_PREPARED), or whose saved sign-ins no key opens on this computer (BROWSER_DATA_UNREADABLE).
  • 429Max concurrent profiles reached: 50 browsers at once (MAX_CONCURRENT_REACHED).
  • 500The browser did not start (LAUNCH_FAILED: for example it did not report its DevTools address within 45 s, which a busy computer can cause on the first start of a new profile; the browser it started is closed again; try again), the profile could not be downloaded from the cloud (CLOUD_DOWNLOAD_FAILED), or no engine was found (NO_BROWSER). Or its cookies and saved passwords could not be prepared for this computer (BROWSER_DATA_NOT_CONVERTED), or could not be set aside before the launch (BROWSER_DATA_NOT_SET_ASIDE): nothing was opened. Or an unexpected failure (INTERNAL_ERROR, UNKNOWN_ERROR).
  • 503Couldn't reach JustBrowser's server (error.code CLOUD_LOCK_UNAVAILABLE): to take the profile's cloud lock, or to check that a conflicted copy of a profile shared with you is still shared. No session, a server error or no answer. Or the profile's proxy couldn't be read from its database (PROXY_UNREADABLE): nothing was opened, since the browser would have connected without its proxy. Or the engine it is pinned to couldn't be installed (PINNED_ENGINE_UNAVAILABLE). Try again. Or JustBrowser couldn't reach justbrowser.app for the key that opens its saved sign-ins (BROWSER_KEY_UNAVAILABLE): try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds). Or JustBrowser is quitting (APP_QUITTING): nothing was opened. Only a call already running when the quit began gets this answer: the local API takes no new call once the quit begins, and ends the calls still running about 5 seconds into it.
  • Also, as any route: 401, 413, 415 (Responses and errors)

Stop a profile browser

Stop a running browser instance for a profile. Answers once the browser is down. With cloud sync on, its upload continues: GET /profiles/{id} reads running until it lands, and a start meanwhile waits for it (up to 120 s).

Parameters

id*path · string

Responses

  • 200Browser stopped

    Response body

    data*object
    profile_id*string
    status*stringone of "stopped"
    stopped_at*string (date-time)
  • 404The profile is not running here, or there is no such profile (NOT_FOUND).
  • Also, as any route: 400, 401, 403, 413, 415, 500, 503 (Responses and errors)

Get CDP WebSocket URL

Get the Chrome DevTools Protocol WebSocket URL for a running profile. Use this URL with Playwright chromium.connectOverCDP() or Puppeteer puppeteer.connect().

Parameters

id*path · string

Responses

  • 200CDP connection info

    Response body

    data*object
    profile_id*string
    cdp_url*string
    browser*object
    runningboolean
    pidnumber
    launched_atstring (date-time) | nullnull for a browser opened before JustBrowser restarted whose start time was not recorded
  • 404The profile is not running here (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Get Selenium connection info

Get Selenium RemoteWebDriver-compatible connection info for a running profile. Returns the debugger address and Chrome capabilities needed for Selenium integration. ChromeDriver must match the profile's Chromium major (GET /profiles/{id}/chromium): pin it, as the Selenium sample on this page does.

Parameters

id*path · string

Responses

  • 200Selenium connection info

    Response body

    data*object
    profile_id*string
    cdp_url*string
    selenium*object
    remote_urlstringThe DevTools HTTP endpoint (http://127.0.0.1:PORT), not a Selenium Grid / RemoteWebDriver URL — attach with the debuggerAddress capability
    debugger_addressstringChrome debugger address (host:port)
    capabilitiesobjectChrome capabilities for WebDriver
    browserNamestringone of "chrome"
    goog:chromeOptionsobject
    browser*object
    runningboolean
    pidnumber
    launched_atstring (date-time) | nullnull for a browser opened before JustBrowser restarted whose start time was not recorded
  • 404The profile is not running here (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

PROFILE CONFIG

Which Chromium core a profile runs, its DNS-over-HTTPS settings, and matching its time zone and language to where its proxy exits.

The engines (Chromium cores) in the registry

Every engine a profile can be pinned to, newest first by registry order, with whether it is on this computer (a launch of a profile pinned to one that is not downloads it first) and what is known to be wrong with it ("Fixed in <version>" names the build that fixes it).

Responses

  • 200The registry

    Response body

    data*object
    latest*stringThe engine new profiles get
    versions*array of object
    version*string
    notestring | null
    released_atstring
    supported_untilstring | null
    is_latest*boolean
    installed*boolean | nullWhether it is on this computer; null when that could not be read
    known_issues*array of string
    deprecatedobject | null
    reasonstring
    fixed_instringA build that fixes the reason
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Which engine a profile runs

Parameters

id*path · string

Responses

  • 200Its pin

    Response body

    data*object
    profile_id*string
    pinned_versionstring | nullThe pin; null on a profile that predates pinning
    effective_version*stringThe engine a launch would run
    latest_version*string
    upgrade_available*boolean
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Upgrade a profile's engine (stop the profile first)

Pins the profile to another engine of the registry, the same build or a newer one, as the app's engine update does; the user agent and client hints of its fingerprint follow it. A lower major and an older build of the same major are refused: the profile's browser data only moves forward. The change reaches the account's other computers; a profile shared with you stays on its owner's engine.

Parameters

id*path · string

Request body (JSON, required)

version*string

Responses

  • 200The profile and the change

    Response body

    data*object
    profile*Profile
    previousVersionstring | null
    newVersion*string
  • 400Not a registry version (CHROMIUM_VERSION_UNKNOWN), the version it already has (CHROMIUM_VERSION_UNCHANGED), an older engine (CHROMIUM_DOWNGRADE_REFUSED), a Firefox profile (FINGERPRINT_NOT_CHROMIUM), or the body is invalid (VALIDATION_ERROR). Or the body is not JSON (INVALID_JSON).
  • 403A profile shared with you stays on its owner's engine (SHARED_PROFILE_ENGINE). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such profile, or it has no fingerprint (NOT_FOUND, FINGERPRINT_NOT_FOUND).
  • 409The profile is open or starting (PROFILE_RUNNING): stop it first.
  • Also, as any route: 401, 413, 415, 500, 503 (Responses and errors)

A profile's DNS-over-HTTPS settings

Parameters

id*path · string

Responses

  • 200Its settings

    Response body

  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Change a profile's DNS-over-HTTPS settings

custom_url is used with provider custom only, and is required with it. Applies at the next launch.

Parameters

id*path · string

Request body (JSON)

providerstringone of "cloudflare", "google", "quad9", "custom", "disabled"
modestringone of "automatic", "secure", "off"
custom_urlstring | null

Responses

  • 200Its settings now

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also provider custom without a valid https custom_url. Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Where a proxy exits

From the proxy's last successful test (POST /proxies/{id}/test): its exit address, country, city and time zone, and whether the time zone was measured or guessed from the country.

Parameters

id*path · string

Responses

  • 200Where it exits

    Response body

    data*GeoData
  • 404No such proxy (NOT_FOUND).
  • 409The proxy has not passed a test yet, so where it exits is not known (PROXY_GEO_UNKNOWN): POST /proxies/{id}/test tests it, and says why a test fails.
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Match a profile's time zone and language to a proxy's exit

Compares the profile's fingerprint time zone and locale with where the proxy exits and suggests the ones that agree. apply true writes them into the fingerprint (refused while the profile is open); it is never applied when the two geo lookups disagree on the country (geoData.countryConflict).

Parameters

id*path · string

Request body (JSON, required)

proxy_id*string
applyboolean

Responses

  • 200The suggestion, and whether it was applied

    Response body

    data*object
    geoData*GeoData
    suggested*object
    timezonestring
    localestring
    languagestring
    current*object
    timezonestring
    localestring
    hasChanges*boolean
    applied*boolean
    skippedReasonstringWhy an apply true was not done (the two geo lookups disagree on the country)
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such profile or proxy (NOT_FOUND).
  • 409The proxy has not passed a test yet (PROXY_GEO_UNKNOWN), or apply true while the profile is open (PROFILE_RUNNING).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

FINGERPRINT

Read, regenerate, validate and repair a profile's device settings, and reuse them as templates.

Get a profile fingerprint

The profile's fingerprint as stored: platform, screen, hardware, WebGL, fonts, timezone, locale. A launch applies it, except the Chrome version: the profile's engine sets that in the user agent and client hints (GET /profiles/{id}/chromium), whatever browser_version and user_agent say.

Parameters

id*path · string

Responses

  • 200The fingerprint

    Response body

  • 404No such profile, or it has no fingerprint (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Regenerate a fingerprint

Replaces the profile fingerprint with a freshly generated one (new canvas, WebGL and audio noise included). Every field is optional: the defaults are windows, chrome, en-US, desktop. Refused while the profile is open.

Parameters

id*path · string

Request body (JSON)

osstringone of "windows", "macos", "linux"
browserstringone of "chrome", "firefox"
localestring
device_typestringone of "desktop", "mobile"

Responses

  • 200The new fingerprint

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409The profile is open or starting here (PROFILE_RUNNING, details.reason running or launching): stop it first. Its browser keeps the fingerprint it started with until it closes.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Check fingerprint consistency

Runs the consistency rules and returns a 0-100 score plus the failing rules, each with whether POST /profiles/{id}/fingerprint/fix fixes it. Worth calling after any fingerprint edit.

Parameters

id*path · string

Responses

Auto-fix fingerprint issues

Applies the automatic fix of every fixable rule GET …/validate reports, and answers the fingerprint and a new validation. Nothing to fix answers the same, unchanged. Refused while the profile is open.

Parameters

id*path · string

Responses

  • 200The fingerprint after the fixes, and its validation

    Response body

    data*object
    fingerprint*Fingerprint
    validationResult*FingerprintValidation
  • 400The profile has no fingerprint (VALIDATION_ERROR). Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409The profile is open or starting here (PROFILE_RUNNING, details.reason running or launching): stop it first. Its browser keeps the fingerprint it started with until it closes.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Saved fingerprint templates and presets

templates lists every template: the built-in presets (is_preset true) and the ones saved from profiles. presets lists the presets alone.

Responses

Get a template

Parameters

id*path · string

Responses

  • 200The template; config is the fingerprint shape it gives

    Response body

  • 404No such template (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Apply a template

Gives the profile the template's fingerprint shape (OS, screen, locale, time zone…), with its own noise. Refused while the profile is open.

Parameters

id*path · string

Request body (JSON, required)

template_id*string

Responses

  • 200The profile's new fingerprint

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such profile or template (NOT_FOUND).
  • 409The profile is open or starting here (PROFILE_RUNNING, details.reason running or launching): stop it first. Its browser keeps the fingerprint it started with until it closes.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Save a profile's fingerprint as a template

Names may repeat: each save makes a new template.

Parameters

id*path · string

Request body (JSON, required)

name*string
descriptionstring
categorystring

Responses

  • 201The template

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such profile, or it has no fingerprint (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

PROXIES

Manage proxies (HTTP, HTTPS, SOCKS5 with authentication), test them, and assign one per profile.

Create a proxy

Credentials are encrypted on write and never read back over this API. The proxy reaches the account's other computers.

Request body (JSON, required)

namestring
protocol*stringone of "http", "https", "socks5"
host*string
port*integer
usernamestring
passwordstring

Responses

  • 201The proxy

    Response body

    data*Proxy
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Update a proxy

Every field is optional. The edit reaches the account's other computers.

Parameters

id*path · string

Request body (JSON)

namestring
protocolstringone of "http", "https", "socks5"
hoststring
portinteger
usernamestring
passwordstring

Responses

  • 200The proxy as written

    Response body

    data*Proxy
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such proxy (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete a proxy

Every profile that used it goes direct (no proxy) at its next launch. The delete reaches the account's other computers.

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe proxy's id
  • 404No such proxy (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Test a proxy

Live connectivity check through the proxy: latency, the address and place it exits from, and that address's reputation. A failed test is an answer, not an error: success false with errorCode and a sentence in errorMessage. The result is stored on the proxy (its last_* and geo_* fields).

Parameters

id*path · string

Responses

Get a profile's proxy

Parameters

id*path · string

Responses

  • 200The proxy, or null for a profile with none (it goes direct)

    Response body

    data*object
    profile_id*string
    proxy*Proxy | null
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Assign a proxy to a profile, or take it off

proxy_id null takes the proxy off: the profile goes direct at its next launch (as "No proxy" in the app). The change applies at the next launch and reaches the account's other computers.

Parameters

id*path · string

Request body (JSON, required)

proxy_id*string | nullA proxy's id, or null to take the profile's proxy off

Responses

  • 200The profile's proxy now

    Response body

    data*object
    profile_id*string
    proxy*Proxy | null
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. proxy_id is required: a proxy's id, or null. Or the body is not JSON (INVALID_JSON).
  • 404No such profile or proxy (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

BATCH

The same operations across many profiles in one call, with per-profile results.

Start several profiles

Launch a set of profiles in one call, one after the other, as the app's bulk Start does; a profile already running is skipped. Prefer this over N calls to /profiles/{id}/start. One line per profile sent, in order. A profile this computer does not have is a failed line (error "Profile not found", code NOT_FOUND); the others are processed. A start that failed carries the start's code (ALREADY_RUNNING, PROFILE_IN_USE, …) on its line; without an active plan, one of the account's own profiles outside the 5 it used most recently is such a line (PROFILE_OVER_PLAN_LIMIT), as POST /profiles/{id}/start answers it. If JustBrowser quits during the batch, no further profile starts (its line says APP_QUITTING) and a call still running about 5 seconds into the quit ends without an answer.

Request body (JSON, required)

profile_ids*array of string
headlessboolean

Responses

  • 200Per-profile launch results

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds). The plan is asked once, before the first start: the whole batch is refused, no profile started.
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500 (Responses and errors)

Stop several profiles

Closes each running profile; one not running is skipped. One line per profile sent, in order. A profile this computer does not have is a failed line (error "Profile not found", code NOT_FOUND); the others are processed.

Request body (JSON, required)

profile_ids*array of string

Responses

  • 200Per-profile stop results

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete several profiles

Deletes each profile with its browser data and cloud copy. Unlike DELETE /profiles/{id}, which refuses a running profile, a running one is closed first and its upload waited for; one still uploading after that wait is skipped (not deleted mid-upload). A profile this computer does not have is a failed line (error "Profile not found").

Request body (JSON, required)

profile_ids*array of string

Responses

  • 200Per-profile results

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Add or remove one tag across several profiles

action add or remove; a profile that already has (or lacks) the tag is skipped. A tag that does not exist fails every line ("Tag with id … not found"). One line per profile sent, in order. A profile this computer does not have is a failed line (error "Profile not found", code NOT_FOUND); the others are processed.

Request body (JSON, required)

profile_ids*array of string
tag_id*string
action*stringone of "add", "remove"

Responses

  • 200Per-profile results

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Move several profiles into a folder

folder_id null moves them out of any folder. One line per profile sent, in order. A profile this computer does not have is a failed line (error "Profile not found", code NOT_FOUND); the others are processed.

Request body (JSON, required)

profile_ids*array of string
folder_idstring | null

Responses

  • 200Per-profile results

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404The folder does not exist (NOT_FOUND); nothing was moved.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Spread a proxy pool across several profiles

Assigns the proxies in turn (round-robin, the default) or at random. oversubscribed names proxies given to more profiles than they can be expected to carry, and warning says so in a sentence. One line per profile sent, in order. A profile this computer does not have is a failed line (error "Profile not found", code NOT_FOUND); the others are processed.

Request body (JSON, required)

profile_ids*array of string
proxy_ids*array of string
strategystringone of "round-robin", "random"

Responses

  • 200One assignment per profile

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404A proxy in proxy_ids does not exist (NOT_FOUND); nothing was assigned.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

DETECTION

Run a profile check, read the profile's past results and health, and auto-fix what the check finds.

Run the profile check

Runs the profile check: the profile opens in a background (headless) launch for up to about a minute and its result is stored. Answers the result. A profile check takes no cloud lock and uploads nothing. It runs on a throwaway copy of the profile's data (without its sign-ins and open tabs), removed when it ends, so nothing it does reaches the profile's own folder; a profile shared with you is checked on a copy of its folder as it is, and nothing in that folder is moved or claimed. It never changes the profile's "Last used" and never becomes a cloud version by itself: its score is stored on the profile and goes up with the profile's next upload.

Parameters

id*path · string

Responses

  • 200The check's result

    Response body

  • 400The profile is running here (error.code VALIDATION_ERROR): stop it first. Or the body is not JSON (INVALID_JSON).
  • 402This account has not started its trial yet (error.code TRIAL_REQUIRED). Or this account has no active plan (its plan ended or is paused, or it holds only a team seat) and the profile is not one of its 5 own profiles used most recently, a profile open now counting as used now (error.code PROFILE_OVER_PLAN_LIMIT; error.details.limit is the number): nothing was opened.
  • 403A profile shared with you that the share no longer lets in (error.code PROFILE_ACCESS_DENIED), or a copy kept for such a share. Or this account holds neither a plan nor a team seat, and the profile is shared with it (PROFILE_ACCESS_DENIED, refused before the cloud is asked). A profile saved by a newer version of JustBrowser (error.code APP_UPDATE_REQUIRED): update JustBrowser on this computer. Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such profile, or it has no fingerprint yet (error.code NOT_FOUND). With error.code PROFILE_ACCESS_DENIED, the profile is still here but no longer shared with you: a profile shared with you directly whose share was stopped and that no team of yours shares, or a conflicted copy of a profile shared with you.
  • 409Its data is not on this computer yet (NOT_DOWNLOADED: open it once), it is already running or starting (ALREADY_RUNNING), it is a profile shared with you that a browser of another JustBrowser account on this computer still has open (LOCAL_COPY_NOT_KEPT: close that window first; nothing was copied, moved or ended), or it is a profile shared with you that its owner's app has not prepared yet (SHARE_NOT_PREPARED), or whose saved sign-ins no key opens on this computer (BROWSER_DATA_UNREADABLE).
  • 429Max concurrent profiles reached (MAX_CONCURRENT_REACHED)
  • 500The copy of the profile's data the check runs on could not be made (error.code PROFILE_CHECK_COPY_FAILED): nothing was opened and the profile wasn't touched. Check the disk's free space, then try again. Or the browser did not start (LAUNCH_FAILED), or no engine was found (NO_BROWSER). Or its cookies and saved passwords could not be prepared for this computer (BROWSER_DATA_NOT_CONVERTED), or could not be set aside before the launch (BROWSER_DATA_NOT_SET_ASIDE): nothing was opened. Or an unexpected failure (INTERNAL_ERROR, UNKNOWN_ERROR).
  • 503The engine it is pinned to couldn't be installed (PINNED_ENGINE_UNAVAILABLE), or its proxy couldn't be read (PROXY_UNREADABLE): nothing was opened. Or JustBrowser's server couldn't be reached to check that a conflicted copy of a profile shared with you is still shared (CLOUD_LOCK_UNAVAILABLE). Or JustBrowser couldn't reach justbrowser.app for the key that opens its saved sign-ins (BROWSER_KEY_UNAVAILABLE): try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds). Or JustBrowser is quitting (APP_QUITTING): nothing was opened. Only a call already running when the quit began gets this answer: the local API takes no new call once the quit begins, and ends the calls still running about 5 seconds into it.
  • 504No answer in time (error.code SHELL_RPC_TIMEOUT): the check goes on in the background; read GET /profiles/{id}/detection later.
  • Also, as any route: 401, 413, 415 (Responses and errors)

Previous profile check results

Parameters

id*path · string
limitquery · integerHow many, newest first (default 10). A value that is not a number is ignored.

Responses

Auto-fix every fixable check

Fixes what the checks measure that a fingerprint change can fix: the consistency rules, then new noise for each of the canvas, audio and WebGL checks whose latest result is not a pass (a fail or a warning, in the profile's latest profile check). A check that passed keeps its noise, and so does every check of a profile never checked: run POST /profiles/{id}/detection first. fixedVectors names what changed: a consistency check only when its rule was failing and no longer is, and canvas, audio and WebGL when their noise was renewed; renewedNoise names the renewed noise alone; skippedVectors says, for each check it does not change, why and what to do instead. It does not run a new check. Refused while the profile is open.

Parameters

id*path · string

Responses

  • 200What was fixed and what was not

    Response body

    data*object
    fixedVectors*array of string
    skippedVectors*array of object
    vectorstringone of "canvas", "webgl", "audio", "webrtc", "dns", "timezone", "fonts", "clientHints", "navigator", "toString", "propertyDescriptor", "screen", "hardware", "webglVendor", "speechVoices", "intlLocale", "proxyIp", "geolocation"
    reasonstring
    renewedNoise*array of stringThe checks whose noise this fix renewed: those whose latest result was not a pass, in canvas, audio, WebGL order. Empty when none was.
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409The profile is open or starting here (PROFILE_RUNNING, details.reason running or launching): stop it first. Its browser keeps the fingerprint it started with until it closes.
  • Also, as any route: 400, 401, 403, 413, 415, 500, 503 (Responses and errors)

Auto-fix one check

Fixes one check. Canvas and audio get new noise, and WebGL new noise after its renderer fix, only when the check's latest result is not a pass: a check that passed, or a profile never checked, keeps its noise. fixed false comes with the reason: nothing to fix, or what to do instead (a check a fingerprint change cannot fix, a profile to check first). Refused while the profile is open.

Parameters

id*path · string
vector*path · stringThe check: canvas, webgl, audio, webrtc, dns, timezone, fonts, clientHints, navigator, toString, propertyDescriptor, screen, hardware, webglVendor, speechVoices, intlLocale, proxyIp, geolocationone of "canvas", "webgl", "audio", "webrtc", "dns", "timezone", "fonts", "clientHints", "navigator", "toString", "propertyDescriptor", "screen", "hardware", "webglVendor", "speechVoices", "intlLocale", "proxyIp", "geolocation"

Responses

  • 200Whether it was fixed

    Response body

    data*object
    fixed*boolean
    reasonstringWhy not, when fixed is false
  • 400An unknown vector (VALIDATION_ERROR): the vectors are canvas, webgl, audio, webrtc, dns, timezone, fonts, clientHints, navigator, toString, propertyDescriptor, screen, hardware, webglVendor, speechVoices, intlLocale, proxyIp, geolocation. Or the body is not JSON (INVALID_JSON).
  • 404No such profile, or it has no fingerprint (NOT_FOUND).
  • 409The profile is open or starting here (PROFILE_RUNNING, details.reason running or launching): stop it first. Its browser keeps the fingerprint it started with until it closes.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Composite health score (notOnDevice: true for a profile only in the cloud, not scored)

The profile's health score 0-100 from its fingerprint consistency, proxy, cookies and last profile check, with each check that went into it. A profile whose data is not on this computer is not scored: notOnDevice true, overallScore 0, no checks.

Parameters

id*path · string

Responses

  • 200The score and its checks

    Response body

  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

COOKIES

Import cookies into a profile or export what it holds.

Export a profile's cookies

The profile's cookies with their values (it can be read while the profile runs). unreadable counts cookies this computer cannot read (saved with another computer's key), so a short list is never taken for the whole jar.

Parameters

id*path · string

Responses

  • 200The cookies

    Response body

    data*object
    profile_id*string
    exported*integer
    unreadableintegerCookies this computer could not read
    cookies*array of Cookie
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Import cookies into a profile

Send cookies (a list of cookie objects) or content (the text of an exported cookie file: JSON or Netscape, format auto-detected). A cookie that cannot be stored is counted in skipped, never lost silently. Refused while the profile runs: stop it first.

Parameters

id*path · string

Request body (JSON)

cookiesarray of object
contentstring
formatstringone of "json", "netscape", "auto"

Responses

  • 200How many were imported

    Response body

    data*object
    profile_id*string
    writtenintegerCookies sent to the profile
    imported*integerCookies stored
    skipped*integerCookies that could not be stored (incomplete, expired…)
    parse_errors*array of stringLines of content that could not be read
  • 400Neither a non-empty cookies list nor a content text with a cookie in it (VALIDATION_ERROR; details has the parse errors), an invalid format, or the profile is running (VALIDATION_ERROR, details.reason running). Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

WARMUP

Auto-browse: the profile visits a list of common sites, through its proxy if it has one.

Progress of an Auto-browse run

null when no run is going (a finished run's result is the answer to its POST).

Parameters

id*path · string

Responses

Start Auto-browse

Opens the profile in a visible window and visits common sites (through its proxy if it has one), so it carries ordinary browsing history and cookies. The call answers with the run's result once the window has closed: minutes, up to about an hour for the default 50 sites. A run that went wrong is a result too: status error with a reason. So is a profile the account's plan does not let it open (without an active plan, only its 5 own profiles used most recently open): its reason says why, and nothing was opened. If JustBrowser quits during the run, the run is stopped and the call ends without an answer about 5 seconds into the quit. Every config field is optional.

Parameters

id*path · string

Request body (JSON)

categoriesarray of stringSite categories to visit (default: all six)
maxSitesintegerSites to visit (default 50)
minDelayintegerShortest wait between pages, ms (default 2000)
maxDelayintegerLongest wait between pages, ms (default 8000)
maxPageTimeintegerLongest time on a page, ms (default 15000)
scrollPagesbooleanScroll each page (default true)
clickLinksbooleanClick links on the pages (default true)
maxClicksPerPageintegerLink clicks per page (default 2)

Responses

  • 200The run's result

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. The message names each config field that is out of range. Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409Auto-browse is already running for this profile (WARMUP_RUNNING): GET /profiles/{id}/warmup reports its progress, and its result is the answer to the call that started it.
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500 (Responses and errors)

Stop an Auto-browse run

The run ends with status stopped, which its POST answers.

Parameters

id*path · string

Responses

  • 200Stopped

    Response body

    data*object
    profile_id*string
    stopped*boolean
  • 404No such profile, or Auto-browse is not running for it (NOT_FOUND, "Auto-browse is not running for this profile.").
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

LOGINS

Saved logins per profile. Passwords are never returned.

A profile's saved logins (no passwords)

Parameters

id*path · string

Responses

  • 200Its logins

    Response body

    data*object
    profile_id*string
    logins*array of Login
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Save a login

The password is encrypted and never answered: has_password says one is saved.

Parameters

id*path · string

Request body (JSON, required)

site_url*string
username*string
password*string
notesstring

Responses

  • 201The login

    Response body

    data*Login
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Update a login

Every field is optional.

Parameters

id*path · string

Request body (JSON)

site_urlstring
usernamestring
passwordstring
notesstring

Responses

  • 200The login

    Response body

    data*Login
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such login (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete a login

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe login's id
  • 404No such login (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Remove a profile's 2FA seed

Reading the seed is not offered over this API.

Parameters

id*path · string

Responses

  • 200Removed

    Response body

    data*object
    profile_id*string
    totp_configured*boolean
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

BACKUP

Encrypted export and restore of a single profile.

Export a profile to an encrypted archive

Writes the profile (settings, fingerprint, proxy, tags, logins, and with include_user_data its browser data) to file_path, encrypted with the passphrase. The passphrase is never stored: without it the archive cannot be opened.

Parameters

id*path · string

Request body (JSON, required)

file_path*stringAbsolute path of the archive to write (any folder this computer lets the app write)
passphrase*string
include_user_databooleanInclude the browser data (cookies, history, storage); false writes the profile's settings and fingerprint onlydefault true

Responses

  • 200Where it was written and how large it is

    Response body

  • 400A relative file_path, a passphrase under 4 characters, or a folder that cannot be written (VALIDATION_ERROR). Or the body is not JSON (INVALID_JSON).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Import a profile from an encrypted archive

Creates a profile from an archive POST /profiles/{id}/export wrote. new_name names it (default: the archive's name).

Request body (JSON, required)

file_path*stringAbsolute path of a .jbbackup archive
passphrase*string
new_namestring

Responses

  • 201The new profile and what came with it

    Response body

  • 400A relative file_path, a file that cannot be read, a wrong passphrase or not an archive (VALIDATION_ERROR). Or the body is not JSON (INVALID_JSON).
  • 402The plan's profile limit is reached (PLAN_LIMIT_REACHED, TRIAL_REQUIRED).
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 403, 413, 415, 500 (Responses and errors)

SYNC

Cloud sync status and settings, and the cross-device lock.

Push it to the cloud now (status 'skipped', with the reason in error, while it is open, starting or closing here, or while cloud sync is off)

Uploads the profile now (a large profile takes minutes; the call waits). status synced with the new version, up-to-date when the cloud already has it, skipped with the reason in error while it is open, starting or closing here (its session uploads when it closes), error with the reason otherwise. While cloud sync is off (the app's Settings, or PUT /sync/settings with enabled false) nothing is uploaded: status skipped, with the reason in error, as the app's own Sync now is off then; a profile shared with you still saves to the team's copy, which this account's cloud sync does not govern. Two pushes at once run one after the other.

Parameters

id*path · string

Responses

  • 200The outcome

    Response body

  • 404No profile with this id on this computer (NOT_FOUND).
  • 504No answer in time (SHELL_RPC_TIMEOUT): the upload goes on in the background; GET /profiles/{id}/sync reports when it has landed.
  • Also, as any route: 400, 401, 403, 413, 415, 500, 503 (Responses and errors)

Change cloud sync settings

Every field is optional; enabled is the master switch (as in the app's Settings). A field the settings do not have is refused, naming it.

Request body (JSON)

enabledbooleanCloud sync on or off: the app's master switch
autoSyncbooleanUpload changed profiles on a timer, besides the upload when a profile closes
syncIntervalMinutesnumberMinutes between automatic uploads
syncOnProfileClosebooleanKept until the app restarts and not used yet: with cloud sync on, a profile always uploads its session when it closes
bandwidthLimitKbpsnumberKept until the app restarts and not used yet: uploads are not throttled

Responses

  • 200The settings now

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also an interval outside 5-1440 minutes, or a field the settings do not have. Or the body is not JSON (INVALID_JSON).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Force-release a cross-device lock (the device holding it closes the profile without uploading)

The recovery for a profile left "in use" by a computer that crashed or went offline: the lock is released at once (released true; false when a session or a close on this computer holds it), and the device that held it closes the profile without uploading its session. Owner only. A profile of this computer that has no cloud copy answers forced false with the reason.

Parameters

id*path · string

Responses

  • 200Released, or why there is no lock to release

    Response body

    data*object
    profile_id*string
    forced*booleanWhether the lock was forced (false: the profile has no cloud copy)
    releasedbooleanWhether the lock is free now
    reasonstringWhy forced is false
  • 403Only the owner can force the lock (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 409The owner is preparing the profile for sharing on another device (PROFILE_BEING_PREPARED, details.deviceName): try again once it is done.
  • 503Couldn't read the cloud manifest to find the lock (CLOUD_UNREACHABLE): nothing was changed. Retry. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 401, 500 (Responses and errors)

TEAMS

Teams, members, roles, shared profiles, invitations, direct shares and notifications.

List teams

The teams this account owns or is in, each with this account's role.

Responses

  • 200Teams

    Response body

    data*object
    teams*array of Team
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)
post/teams

Create a team

A name is 1-100 characters, without HTML markers or line breaks. Creating a team needs an active subscription or trial on this account.

Request body (JSON, required)

name*string
descriptionstring

Responses

  • 201The team

    Response body

    data*Team
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 402This account has no active subscription or trial of its own (PAYMENT_REQUIRED): the message says why (its subscription ended or is paused, it is on a team seat, or it never subscribed). The teams it already has are not touched.
  • 403justbrowser.app refused it for a reason other than the subscription (FORBIDDEN); the message says why. Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 413, 415, 500 (Responses and errors)

Rename a team, or change its description

Parameters

id*path · string

Request body (JSON)

namestring

Responses

  • 200The team

    Response body

    data*Team
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 413, 415, 500 (Responses and errors)

Delete a team

Its members are told by e-mail; the profiles shared with it stop being shared.

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe team's id
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

A team's members

Parameters

id*path · string

Responses

  • 200Its members

    Response body

    data*object
    team_id*string
    members*array of TeamMember
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

Invite someone to a team by e-mail

role MEMBER (default), ADMIN or VIEWER, in any case. A team has one admin, chosen by the owner. The person gets an e-mail with a link; inviting the same address again sends a new one.

Parameters

id*path · string

Request body (JSON, required)

email*stringWho to invite
rolestringIn any case (member = MEMBER)one of "MEMBER", "ADMIN", "VIEWER"default "MEMBER"

Responses

  • 201The invitation

    Response body

    data*object
    id*string
    email*string
    role*string
    expiresAtstring
    createdAtstring
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also an address that is not an e-mail, or an unknown role. Or the body is not JSON (INVALID_JSON).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 413, 415, 500 (Responses and errors)

Change a member's role

role ADMIN, MEMBER or VIEWER, in any case. The owner alone changes roles, and keeps their own; a team has one admin. The member is told by e-mail.

Parameters

id*path · string
memberId*path · string

Request body (JSON, required)

role*stringIn any case (admin = ADMIN)one of "MEMBER", "ADMIN", "VIEWER"

Responses

  • 200The member

    Response body

  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also an unknown role, or the owner's role. Or the body is not JSON (INVALID_JSON).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team or member (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 413, 415, 500 (Responses and errors)

Remove a member

Parameters

id*path · string
memberId*path · string

Responses

  • 200Removed

    Response body

    data*object
    removed*boolean
    team_id*string
    member_id*string
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team or member (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

Profiles shared with a team

Parameters

id*path · string

Responses

  • 200The shared profiles

    Response body

    data*object
    team_id*string
    profiles*array of TeamSharedProfile
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

Share a profile with a team (push it first)

profile_id is the profile's id on this computer; it must have been pushed to the cloud. profile_name is the name the team sees (default: the profile's). Sharing the same profile again keeps one share.

Parameters

id*path · string

Request body (JSON, required)

profile_id*string
profile_namestring

Responses

  • 201The share

    Response body

    data*object
    id*string
    teamId*string
    profileNamestring
    syncProfileId*string
    sharedBystring
    createdAtstring
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or no such profile on this computer (NOT_FOUND).
  • 409The profile has never been pushed to the cloud (PROFILE_NOT_SYNCED): POST /profiles/{id}/sync first.
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app, to check the profile's cloud copy or to share it (CLOUD_UNREACHABLE, UPSTREAM_UNREACHABLE): nothing was shared. Retry. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 413, 415, 500 (Responses and errors)

Stop sharing a profile with a team

Parameters

id*path · string
sharedId*path · stringThe share's id (GET /teams/{id}/profiles), not the profile's

Responses

  • 200Unshared

    Response body

    data*object
    unshared*boolean
    team_id*string
    shared_profile_id*string
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team or share (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

A team's pending invitations

Parameters

id*path · string

Responses

  • 200Pending invitations

    Response body

    data*object
    team_id*string
    invitations*array of Invitation
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or this account is not in it (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

Cancel an invitation

Parameters

id*path · string
invitationId*path · string

Responses

  • 200Cancelled

    Response body

    data*object
    cancelled*boolean
    team_id*string
    invitation_id*string
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team or invitation (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

A team's activity, newest first

Parameters

id*path · string
limitquery · integerHow many entries (1-200, default 50). A value that is not a number is ignored.
beforequery · stringThe previous page's nextBefore: the next older page. An opaque cursor.

Responses

  • 200A page of entries; nextBefore is null on the last page

    Response body

  • 400A limit outside 1-200 (VALIDATION_ERROR).
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 403This account's role in the team does not allow it (FORBIDDEN). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such team, or none this account can see the activity of (TEAM_ACTIVITY_UNAVAILABLE).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 500 (Responses and errors)

Profiles shared directly with one person, in and out

outgoing: profiles of this account shared with someone; incoming: profiles shared with this account. A share never carries the profile's stored settings, logins or storage keys. A profile its owner deleted from the cloud: outgoing still lists each of its shares, with syncProfile.deletedAt set and the names blank, until it is stopped (DELETE /shares/{id}); incoming lists none.

Responses

  • 200Shares

    Response body

    data*object
    outgoing*array of Share
    incoming*array of Share
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 403, 500 (Responses and errors)

Stop sharing a profile with one person

Parameters

id*path · string

Responses

  • 200Revoked

    Response body

    data*object
    revoked*boolean
    id*string
  • 401JustBrowser is not signed in to an account, or its session expired (ACCOUNT_SIGNED_OUT): sign in in the app. Or no token, or a wrong one (UNAUTHORIZED).
  • 404No such outgoing share, or it was revoked already (NOT_FOUND).
  • 502justbrowser.app answered with an error (UPSTREAM_ERROR). Try again later.
  • 503Couldn't reach justbrowser.app (UPSTREAM_UNREACHABLE). Try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 403, 500 (Responses and errors)

In-app notifications and the unread count

The notifications the app shows in its bell, newest first: data.notifications.items, with data.notifications.unreadCount (also data.unread_count).

Responses

Mark a notification read

Parameters

id*path · string

Responses

  • 200Read

    Response body

    data*object
    id*string
    read*boolean
  • 404No such notification (NOT_FOUND).
  • Also, as any route: 400, 401, 403, 413, 415, 500, 503 (Responses and errors)

ORGANISATION

Folders, tags, templates and duplication.

Delete a template

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe template's id
  • 400A built-in preset cannot be deleted (VALIDATION_ERROR).
  • 404No such template, or it was deleted already (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)
post/tags

Create a tag

color is a #RRGGBB colour (default #6C5CE7). Tag names are unique.

Request body (JSON, required)

name*string
colorstring

Responses

  • 201The tag

    Response body

    data*Tag
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also a name another tag has. Or the body is not JSON (INVALID_JSON).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Get a profile's tags

Parameters

id*path · string

Responses

  • 200The profile's tags

    Response body

    data*object
    profile_id*string
    tags*array of Tag
  • 404No profile with this id on this computer (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Replace a profile's tags

Sets the complete tag list: tags left out are removed, [] removes them all.

Parameters

id*path · string

Request body (JSON, required)

tag_ids*array of string

Responses

  • 200The resulting tag list

    Response body

    data*object
    profile_id*string
    tags*array of Tag
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Or the body is not JSON (INVALID_JSON).
  • 404No such profile or tag (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Rename or recolour a tag

Parameters

id*path · string

Request body (JSON)

namestring
colorstring

Responses

  • 200The tag

    Response body

    data*Tag
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also a name another tag has. Or the body is not JSON (INVALID_JSON).
  • 404No such tag (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete a tag

It is taken off every profile.

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe tag's id
  • 404No such tag (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Create a folder

parent_id puts it inside another folder. Folder names are unique.

Request body (JSON, required)

name*string
parent_idstring | null

Responses

  • 201The folder

    Response body

    data*Folder
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also a name another folder has. Or the body is not JSON (INVALID_JSON).
  • 404The parent folder does not exist (NOT_FOUND); nothing was created.
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Rename or move a folder

parent_id null moves it to the top level. A folder cannot be its own parent.

Parameters

id*path · string

Request body (JSON)

namestring
parent_idstring | null
sort_orderinteger

Responses

  • 200The folder

    Response body

    data*Folder
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also a folder made its own parent. Or the body is not JSON (INVALID_JSON).
  • 404No such folder, or the new parent does not exist (NOT_FOUND).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Delete a folder

Its profiles move out of any folder; none is deleted.

Parameters

id*path · string

Responses

  • 200Deleted

    Response body

    data*object
    deleted*boolean
    id*stringThe folder's id
  • 404No such folder (NOT_FOUND).
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Duplicate a profile

Makes a copy on the same engine, in the same folder, with the source's tags and notes. The copy keeps the source's device settings with new canvas, WebGL and audio noise (regenerate_fingerprint true draws a wholly new device), and gets its proxy unless copy_proxy is false. It starts with an empty browser: none of the source's cookies, history or saved logins, and no 2FA seed. copy_user_data true is refused: to carry a profile with its browser data, export it with POST /profiles/{id}/export and import the archive.

Parameters

id*path · string

Request body (JSON)

namestringName of the copy (default: "<source name> (Copy N)")
copy_user_databooleanOnly false is accepted: a copy starts with an empty browser, none of the source's cookies, history or storage
copy_proxybooleanGive the copy the source's proxydefault true
regenerate_fingerprintbooleanA wholly new device. Without it the copy keeps the source's device settings with new canvas, WebGL and audio noisedefault false

Responses

  • 201The copy

    Response body

    data*Profile
  • 400The body or a parameter is not valid (VALIDATION_ERROR): details lists each problem. JSON types are not converted: a number sent for a text field is refused. Also copy_user_data true. Or the body is not JSON (INVALID_JSON).
  • 402The plan's profile limit is reached (PLAN_LIMIT_REACHED, TRIAL_REQUIRED).
  • 403A profile shared with you, or a copy kept for such a share, cannot be duplicated (DUPLICATE_REFUSED). Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No profile with this id on this computer (NOT_FOUND).
  • 503This account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds).
  • Also, as any route: 401, 413, 415, 500 (Responses and errors)

META

Account, licence, settings, diagnostics and this document.

Run the fingerprint benchmark

Opens the profile in a background (headless) launch, measures whether its fingerprint values can be told apart from a real browser (function source, property descriptors, worker and iframe agreement…) and answers the result. Refused while the profile runs.

Parameters

id*path · string

Responses

  • 200The benchmark result

    Response body

  • 400The profile is running here (VALIDATION_ERROR): stop it first. Or the body is not JSON (INVALID_JSON).
  • 402This account has not started its trial yet (error.code TRIAL_REQUIRED). Or this account has no active plan (its plan ended or is paused, or it holds only a team seat) and the profile is not one of its 5 own profiles used most recently, a profile open now counting as used now (error.code PROFILE_OVER_PLAN_LIMIT; error.details.limit is the number): nothing was opened.
  • 403A profile shared with you that the share no longer lets in (error.code PROFILE_ACCESS_DENIED), or a copy kept for such a share. Or this account holds neither a plan nor a team seat, and the profile is shared with it (PROFILE_ACCESS_DENIED, refused before the cloud is asked). A profile saved by a newer version of JustBrowser (error.code APP_UPDATE_REQUIRED): update JustBrowser on this computer. Or the account no longer includes the API (SUBSCRIPTION_REQUIRED).
  • 404No such profile, or it has no fingerprint yet (error.code NOT_FOUND). With error.code PROFILE_ACCESS_DENIED, the profile is still here but no longer shared with you: a profile shared with you directly whose share was stopped and that no team of yours shares, or a conflicted copy of a profile shared with you.
  • 409Its data is not on this computer yet (NOT_DOWNLOADED: open it once), it is already running or starting (ALREADY_RUNNING), it is a profile shared with you that a browser of another JustBrowser account on this computer still has open (LOCAL_COPY_NOT_KEPT: close that window first; nothing was copied, moved or ended), or it is a profile shared with you that its owner's app has not prepared yet (SHARE_NOT_PREPARED), or whose saved sign-ins no key opens on this computer (BROWSER_DATA_UNREADABLE).
  • 429Max concurrent profiles reached (MAX_CONCURRENT_REACHED)
  • 500The copy of the profile's data the check runs on could not be made (error.code PROFILE_CHECK_COPY_FAILED): nothing was opened and the profile wasn't touched. Check the disk's free space, then try again. Or the browser did not start (LAUNCH_FAILED), or no engine was found (NO_BROWSER). Or its cookies and saved passwords could not be prepared for this computer (BROWSER_DATA_NOT_CONVERTED), or could not be set aside before the launch (BROWSER_DATA_NOT_SET_ASIDE): nothing was opened. Or the benchmark failed in the browser (UNKNOWN_ERROR, "Stealth benchmark failed: …"). Or an unexpected failure (INTERNAL_ERROR, UNKNOWN_ERROR).
  • 503The engine it is pinned to couldn't be installed (PINNED_ENGINE_UNAVAILABLE), or its proxy couldn't be read (PROXY_UNREADABLE): nothing was opened. Or JustBrowser's server couldn't be reached to check that a conflicted copy of a profile shared with you is still shared (CLOUD_LOCK_UNAVAILABLE). Or JustBrowser couldn't reach justbrowser.app for the key that opens its saved sign-ins (BROWSER_KEY_UNAVAILABLE): try again. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING): the app waited up to 8 seconds for justbrowser.app's licence check without an answer, and did nothing. Try again after Retry-After (5 seconds). Or JustBrowser is quitting (APP_QUITTING): nothing was opened. Only a call already running when the quit began gets this answer: the local API takes no new call once the quit begins, and ends the calls still running about 5 seconds into it.
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 401, 413, 415 (Responses and errors)

System status

The API server, the profile counts on this computer and the app version.

Responses

  • 200System status

    Response body

    data*object
    running*boolean
    port*integer
    uptime*integerSeconds the API server has been up
    version*stringThe API versionone of "v1"
    profiles*object
    total*integer
    running*integer
    app*object
    version*string
    platform*stringdarwin or win32
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

API documentation

Returns this OpenAPI document itself, not wrapped in {"data": …}, with this computer's port in servers.

Responses

  • 200This OpenAPI document

    Response body: object

  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Signed-in user and sign-in status

Who the app is signed in as. Nothing here can be used to act as them.

Responses

  • 200The account

    Response body

    data*object
    status*object
    status*stringone of "logged-in", "logged-out", "refreshing", "error"
    userobject | nullThe user: id, email, name, avatarUrl, createdAt, updatedAt
    isAuthenticated*boolean
    errorstring | null
    user*object | nullnull when signed out
    idstring
    emailstring
    namestring | null
    avatarUrlstring | null
    createdAtstring
    updatedAtstring
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Plan, profile limit, feature flags

The account's plan as this computer last checked it (POST /account/license/refresh checks again).

Responses

Re-check the plan

Asks justbrowser.app again (a round trip), for example right after a plan change, so a script that hit the profile limit can go on without the app restarting.

Responses

App settings (secrets redacted)

The settings table: a key holding a token or secret reads "<redacted>" (null when unset).

Responses

  • 200Settings, key to text value

    Response body

    data*object
    api_portstring
    api_tokenstring | null"<redacted>"
    api_enabledstring"true" or "false"
    themestringone of "dark", "light"
    languagestring
    update_channelstringone of "stable", "beta"
    profile_storage_pathstring
    cloud_sync_enabledstring"true" or "false"; absent while it follows the plan
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Change app settings

Merges the settings sent; the others stay. Writable: theme, language, update_channel, profile_storage_path, cloud_sync_enabled. The API server's own settings (api_enabled, api_port, api_token) are refused, since changing them strands the caller; sync settings change with PUT /sync/settings; any other key is refused, naming it.

Request body (JSON, required)

themestringone of "dark", "light"
languagestring
update_channelstringone of "stable", "beta"
profile_storage_pathstring
cloud_sync_enabledstringThe master cloud sync switch, as textone of "true", "false"

Responses

  • 200Settings after the change, as GET /settings

    Response body

    data*object
  • 400A key this API does not write (SETTING_NOT_WRITABLE: details lists the keys; nothing was written), an invalid value, or an empty body (VALIDATION_ERROR). Or the body is not JSON (INVALID_JSON).
  • Also, as any route: 401, 403, 413, 415, 500, 503 (Responses and errors)

Engine, fingerprint data and page-script checks

One call for "is this install healthy". Each part is its value, or {error} when it could not be read; the engine check (chromium_valid) starts the legacy engine binary.

Responses

  • 200The parts

    Response body

    data*object
    chromium*objectThe engine build: buildStatus (available, validated, versionInfo), automation markers, privacy report
    chromium_valid*boolean | objectWhether the legacy engine binary ran, or {error}
    chromium_cores*array of object | objectEach installed engine: tag, the version its payload reports, known issues; or {error}
    fingerprint_data*objectThe generator's population data: version, lastUpdated, source
    fingerprint_generator*objectWhether the generator uses that data (usingRemoteData)
    stealth_plugins*array of object | objectThe page-script plugins, or {error}
  • Also, as any route: 401, 403, 500, 503 (Responses and errors)

Pull the generator's newest population data

Asks justbrowser.app for the newest data. refreshed false: it could not be read (error says why) and the data in use is unchanged; notModified true: what is here is already the newest.

Responses

  • 200The data now, and what came of the refresh

    Response body

    data*object
    version*integer
    lastUpdatedstring
    source*stringWhere it came from: remote, cache or bundled
    refreshed*booleanWhether the newest data was read
    notModifiedbooleanThe server said the data here is already its newest
    errorstringWhy it was not refreshed, when refreshed is false
  • 504No answer in time (SHELL_RPC_TIMEOUT): the operation may still complete in the background; check before trying again.
  • Also, as any route: 400, 401, 403, 413, 415, 500, 503 (Responses and errors)

Proxy plans on sale (browse only)

The proxy plans JustBrowser sells. available false (with products []) means nothing is on sale yet. Buying is done in the app.

Responses

  • 200The catalogue

    Response body

    data*object
    available*boolean
    products*array of object
    idstring
    skustring
    displayNamestring
    descriptionstring | null
    productTypestringone of "residential", "mobile", "datacenter", "isp"
    unitstringone of "gb", "ip-month"
    priceUsdCentsinteger
    countriesarray of string
    countriesUnrestrictedboolean
  • 503Couldn't read the proxy market from JustBrowser's server (PROXY_MARKET_UNAVAILABLE, details.reason). Try again later. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 401, 403, 500 (Responses and errors)

Proxy plans this account bought

Each plan with its endpoints. An endpoint's login is never answered (has_credentials): import and use the endpoints from the app's Buy proxies page.

Responses

  • 200The plans

    Response body

    data*array of object
    idstring
    productobject
    skustring
    displayNamestring
    productTypestring
    unitstring
    remainingUnitsnumber
    totalUnitsnumber
    expiresAtstring | null
    endpointsarray of object
    idstring
    hoststring
    portinteger
    protocolstringone of "http", "https", "socks5"
    countrystring | null
    sessionTypestring | nullone of "rotating", "sticky", null
    expiresAtstring | null
    has_credentialsboolean
  • 503Couldn't read the proxy market from JustBrowser's server (PROXY_MARKET_UNAVAILABLE, details.reason). Try again later. Or this account's plan is not confirmed yet (PLAN_CHECK_PENDING; Retry-After: 5).
  • Also, as any route: 401, 403, 500 (Responses and errors)

Schemas

Error

Fields

error*object
code*stringBranch on this, not on the message: the message is a sentence for a person
message*string
detailsanyArray of issue objects for VALIDATION_ERROR and SETTING_NOT_WRITABLE; an object for other errors that carry context (for example heldBy, sameDevice, limitBytes, rpcMethod)

Profile

A profile as every /profiles answer gives it. Its 2FA seed is never answered: totp_configured says whether it has one.

Fields

id*string
name*string
folder_id*string | nullThe folder it is in, null for none
notes*string
status*stringRuntime status on this computer. 'running' lasts until the upload of a closed session has landed (cloud sync on)one of "stopped", "running", "error", "launching", "syncing"
consistency_scorenumber | nullFingerprint consistency 0-100 (GET /profiles/{id}/fingerprint/validate)
detection_scorenumber | nullScore of the last profile check 0-100
last_used_atstring | nullWhen it was last opened
user_data_path*stringThe browser's data folder on this computer
totp_labelstring | nullName of the profile's 2FA seed (the seed itself is never answered)
totp_configured*booleanWhether the profile has a 2FA seed
needs_warmupinteger1 while the profile waits for a completed Auto-browse runone of 0, 1
display_indexinteger | nullThe "#N" the app shows
data_downloadedinteger0 for a cloud profile whose data is not on this computer yet (a visible start downloads it), else 1one of 0, 1
chromium_versionstringThe engine it is pinned to (GET /chromium/versions)
extra_paramsstringThe app's own launch settings, as JSON text
automatic_timezonebooleanMatch the profile's time zone and location to where its proxy exits, at each launch
created_at*string
updated_at*string

CreatedProfile

A profile just created, as POST /profiles answers it

Fields

id*string
name*string
folder_id*string | nullThe folder it is in, null for none
notes*string
status*stringRuntime status on this computer. 'running' lasts until the upload of a closed session has landed (cloud sync on)one of "stopped", "running", "error", "launching", "syncing"
consistency_scorenumber | nullFingerprint consistency 0-100 (GET /profiles/{id}/fingerprint/validate)
detection_scorenumber | nullScore of the last profile check 0-100
last_used_atstring | nullWhen it was last opened
user_data_path*stringThe browser's data folder on this computer
totp_labelstring | nullName of the profile's 2FA seed (the seed itself is never answered)
totp_configured*booleanWhether the profile has a 2FA seed
needs_warmupinteger1 while the profile waits for a completed Auto-browse runone of 0, 1
display_indexinteger | nullThe "#N" the app shows
data_downloadedinteger0 for a cloud profile whose data is not on this computer yet (a visible start downloads it), else 1one of 0, 1
chromium_versionstringThe engine it is pinned to (GET /chromium/versions)
extra_paramsstringThe app's own launch settings, as JSON text
automatic_timezonebooleanMatch the profile's time zone and location to where its proxy exits, at each launch
created_at*string
updated_at*string
fingerprint_generated*booleanWhether its fingerprint was made (true: a failure is the 422, and nothing is created)

Proxy

Credentials are never returned: `has_credentials` says whether the proxy authenticates, `has_password` whether a password is saved.

Fields

id*string
name*string
protocol*stringone of "http", "https", "socks5"
host*string
port*number
country_code*string | null
geo_country*string | null
geo_city*string | null
geo_region*string | null
geo_isp*string | null
geo_org*string | null
geo_lat*number | null
geo_lng*number | null
geo_timezone*string | null
geo_external_ip*string | null
geo_sourcestring | null
geo_country_conflictstring | null
reputation_scorenumber | null
reputation_levelstring | nullone of "clean", "low", "medium", "high", "unknown", null
reputation_blacklists_checkedboolean | null
reputation_coveragestring | nullone of "full", "partial", "none", null
reputation_is_proxyboolean | null
reputation_is_hostingboolean | null
reputation_is_mobileboolean | null
reputation_blacklistsarray of string | null
reputation_reasonsarray of string | null
reputation_checked_atstring | null
geo_agreementstring | null
last_tested_at*string | null
last_latency_ms*number | null
last_status*stringone of "untested", "connected", "failed"
assigned_profile_count*number
created_at*string
updated_at*string
has_password*booleanWhether a password is saved (it is never answered)
has_credentials*booleanWhether the proxy authenticates: it has a username (never answered)

ProxyTestResult

Fields

proxyId*string
success*boolean
status*stringone of "untested", "connected", "failed"
latencyMs*number | null
externalIp*string | null
countryCodestring | null
geoSourcestring | null
geoCountryConflictstring | null
geoInfoobject | null
ip*string
countryCodestring
country*string
city*string
region*string
isp*string
org*string
lat*number
lng*number
timezone*string
reputationScorenumber | null
reputationLevelstring | nullone of "clean", "low", "medium", "high", "unknown", null
reputationBlacklistsCheckedboolean | null
reputationCoveragestring | nullone of "full", "partial", "none", null
reputationIsProxyboolean | null
reputationIsHostingboolean | null
reputationIsMobileboolean | null
reputationBlacklistsarray of string | null
reputationReasonsarray of string | null
geoAgreementstring | null
errorMessage*string | null
errorCode*string | nullone of "TIMEOUT", "AUTH_FAILED", "CONNECTION_REFUSED", "DNS_RESOLUTION_FAILED", "PROTOCOL_ERROR", "UNKNOWN_ERROR", null
testedAt*string

Fingerprint

A profile's fingerprint as stored. A launch sets the Chrome version in the user agent and client hints from the profile's engine (GET /profiles/{id}/chromium), whatever browser_version says. A phone (device_type mobile) presents Chrome on Android: its user agent and client hints say Android and its fonts are Android's, while os and os_version keep the computer system it was made beside.

Fields

id*string
profile_id*string
os*stringone of "windows", "macos", "linux"
os_version*string
browser*stringone of "chrome", "firefox"
browser_version*string
device_type*stringone of "desktop", "mobile"default "desktop"
user_agent*string
platform*string
locale*string
timezone*string
screen_width*integer
screen_height*integer
color_depth*integer
pixel_ratio*numberGreater than 0
canvas_noise_seed*string
webgl_vendor*string
webgl_renderer*string
webgl_noise_seed*string
webgl_extensions*array of stringdefault []
audio_context_noise_seed*string
fonts_list*array of string
media_devices*array of object
kind*stringone of "audioinput", "audiooutput", "videoinput"
deviceId*string
groupId*string
label*string
webrtc_mode*stringone of "real", "proxy", "disabled"
hardware_concurrency*integer
device_memory*numberGreater than 0
max_touch_points*integer
connection_typestringone of "auto", "wifi", "cellular", "cellular-nr"
do_not_track*string | null
client_hints*object
brands*array of object
brand*string
version*string
mobile*boolean
platform*string
platformVersion*string
architecture*string
bitness*string
model*string
fullVersionList*array of object
brand*string
version*string
speech_voices*array of object
name*string
lang*string
localService*boolean
default*boolean
voiceURI*string
battery_api*object
charging*boolean
chargingTime*number
dischargingTime*number
level*number
navigator_plugins*array of object
name*string
description*string
filename*string
extra_params*object
created_at*string
updated_at*string

FingerprintValidation

Fields

score*integer
issues*array of object
ruleId*string
severity*stringone of "critical", "warning", "info"
message*string
affectedFields*array of string
suggestion*string
fixableboolean
validatedAt*string

Template

Fields

id*string
name*string
description*string
is_preset*boolean
category*string
config*object
created_at*string
updated_at*string

Tag

Fields

id*string
name*string
color*string
created_at*string

TagListItem

A tag as GET /tags lists it

Fields

id*string
name*string
color*string
created_at*string
profileCountintegerProfiles that carry it

Folder

Fields

id*string
name*string
parent_id*string | null
sort_order*number
created_at*string
updated_at*string

FolderNode

Fields

idstring
namestring
parent_idstring | null
sort_ordernumber
profileCountintegerProfiles directly in this folder
childrenarray of FolderNode

Login

A saved login. The password is never answered.

Fields

idstring
profile_idstring
site_urlstring
usernamestring
has_passwordbooleanWhether a password is saved (it is never answered)
notesstring | null
created_atstring
updated_atstring

DetectionResult

Fields

id*string
profileId*string
overallScore*integer
results*array of object
vector*stringone of "canvas", "webgl", "audio", "webrtc", "dns", "timezone", "fonts", "clientHints", "navigator", "toString", "propertyDescriptor", "screen", "hardware", "webglVendor", "speechVoices", "intlLocale", "proxyIp", "geolocation"
status*stringone of "pass", "fail", "warning"
message*string
detailsobject
testedAt*string

HealthScore

Fields

profileId*string
overallScore*integer
checks*array of object
name*string
category*stringone of "fingerprint", "proxy", "dns", "session", "browser", "fonts", "cookies"
status*stringone of "pass", "warn", "fail"
message*string
weight*number
categories*array of object
category*stringone of "fingerprint", "proxy", "dns", "session", "browser", "fonts", "cookies"
score*integer
passCount*integer
warnCount*integer
failCount*integer
totalChecks*integer
totalChecks*integer
passCount*integer
warnCount*integer
failCount*integer
calculatedAt*string
notOnDevicebooleanTrue for a profile whose data is not on this computer (a cloud profile never opened here): it is not scored, overallScore 0 and no checks

StealthBenchmarkResult

Fields

id*string
profileId*string
overallScore*integer
results*array of object
vector*stringone of "toStringLeak", "prototypeDescriptor", "chromeRuntime", "iframeIsolation", "workerIsolation", "errorStackLeak", "permissionsApi", "automationMarkers"
status*stringone of "pass", "fail", "warning"
message*string
detailsobject
testedAt*string

DnsConfig

Fields

profile_id*string
provider*stringone of "cloudflare", "google", "quad9", "custom", "disabled"default "disabled"
mode*stringone of "automatic", "secure", "off"default "secure"
custom_url*string (uri) | stringdefault ""
created_atstring
updated_atstring

GeoData

Where a proxy exits, from its last successful test (POST /proxies/{id}/test)

Fields

ipstringThe exit address the last successful test measured
countryCodestring
countrystring
citystring | null
regionstring | null
timezonestring
timezoneSourcestring'measured': the test resolved this exit address; 'country-default': a guess from the country aloneone of "measured", "country-default"
sourcestring | nullThe lookup the geo came from
countryConflictstring | nullThe other lookup's country, when the two disagreed

SyncStatus

Fields

profileId*string
syncStatus*stringone of "idle", "syncing", "up-to-date", "conflict", "error", "disabled"
lastSyncedAt*string | null
localVersion*number
remoteVersion*number | null
pendingChanges*numberdefault 0
pushedFromThisDevice*booleandefault false
lastSkipReason*string | nullone of "profile-open", nulldefault null
unpushedSince*string | nulldefault null

SyncResult

A push's outcome. status skipped: nothing was uploaded, error says why (the profile is open, starting or closing here)

Fields

status*stringone of "synced", "up-to-date", "conflict", "error", "skipped"
filesChanged*number
bytesTransferred*numberdefault 0
versionnumber
manifestHashstring
chromiumKeyVersioninteger
chromiumDataOsstring | nullone of "darwin", "win32", null
conflictedCopyobject
profileId*string
name*string
errorstring

SyncSettings

This computer's cloud sync settings

Fields

enabledbooleanCloud sync on or off: the app's master switch
autoSyncbooleanUpload changed profiles on a timer, besides the upload when a profile closes
autoSyncRunningbooleanWhether that timer is armed now
syncIntervalMinutesnumberMinutes between automatic uploads
syncOnProfileClosebooleanNot used yet: with cloud sync on, a profile always uploads its session when it closes
bandwidthLimitKbpsnumberNot used yet: uploads are not throttled

License

The account's plan as this computer last checked it

Fields

plan*stringone of "free", "pro"
maxProfiles*number
maxSeats*numberdefault 1
features*object
cloudSync*booleandefault false
teamWorkspace*booleandefault false
prioritySupport*booleandefault false
advancedStealth*booleandefault false
restApi*booleandefault true
customChromium*booleandefault false
profileKeyV2boolean
expiresAt*string | null
subscriptionStatus*stringone of "active", "past_due", "canceled", "trialing", "none"default "none"
syncStorageBytes*numberdefault 0
syncStorageLimitBytes*numberdefault 0
cloudProfileCount*numberdefault 0
teamCount*numberdefault 0
tokenCount*numberdefault 0
cancelAtPeriodEnd*booleandefault false
entitlementstringone of "full", "seat", "none"
trialEndsAt*string | nulldefault null
isTrialing*booleandefault false
trialDaysRemaining*number | nulldefault null
everSubscribedboolean
trialAvailableboolean

Team

Fields

id*string
name*string
ownerId*string
plan*stringdefault "team"
memberCount*numberdefault 0
profileCount*numberdefault 0
createdAt*string
updatedAt*string
rolestringThis account's role in the team (GET /teams)one of "OWNER", "ADMIN", "MEMBER", "VIEWER"
joinedAtstring | null
ownerobjectThe owner: id, name, email

TeamMember

Fields

id*string
teamId*string
userId*string
email*string (email)
name*string | null
avatarUrl*string (uri) | null
role*stringTheir role in the team, as the website answers itone of "OWNER", "ADMIN", "MEMBER", "VIEWER"
invitedAt*string
acceptedAt*string | null

Invitation

A pending invitation to a team

Fields

idstring
teamIdstring
emailstring
rolestringThe role it offersone of "ADMIN", "MEMBER", "VIEWER"
invitedByIdstring
invitedByobjectWho invited: id, name, email
invitedAtstring
expiresAtstring
acceptedAtstring | null
cancelledAtstring | null

TeamSharedProfile

Fields

id*string
profileId*string
profileName*string
teamId*string
sharedBy*string
sharedByName*string | null
syncVersion*number
lastSyncedAt*string
sizeBytes*number
accountsSetbooleanWhether saved logins and 2FA go with the share
chromiumKeyVersioninteger | null
sharedAtstring | null

TeamActivityPage

Fields

activity*array of object
id*string
teamId*string
userId*string | null
userName*string | null
action*string
detailsobject
createdAt*string
nextBefore*string | nulldefault null

BatchResult

One line per profile sent, in order. A failed line has success false and error; skipped means nothing needed doing (already running, already stopped, tag already there).

Fields

operation*stringone of "batch-start", "batch-stop", "batch-delete", "batch-tag", "batch-move"
totalCount*number
successCount*number
failureCount*number
skippedCount*number
results*array of object
profileId*string
profileName*string
success*boolean
skippedboolean
errorstring
codestringWhy it failed, when it says: NOT_FOUND for a profile this computer does not have, a launch code (ALREADY_RUNNING, PROFILE_IN_USE, …) for a start

BulkCreateResult

Fields

totalProfiles*number
successCount*number
failureCount*number
results*array of object
profileId*string
profileName*string
success*boolean
consistencyScorenumber
errorstring

BulkProxyResult

Fields

totalAssignments*number
successCount*number
failureCount*number
assignments*array of object
profileId*string
profileName*string
proxyId*string | null
proxyName*string | null
success*boolean
errorstring
codestringNOT_FOUND for a profile this computer does not have
oversubscribedarray of object
proxyId*string
proxyName*string
profileCount*number
warningstring

WarmupResult

A run's result

Fields

profileId*string
status*stringone of "not_started", "in_progress", "completed", "stopped", "error"
sitesVisited*number
sitesFailednumber
cookiesCollected*number
cookiesBeforenumber | null
cookiesAfternumber | null
duration*number
reasonstring
errorsarray of string

WarmupProgress

A run in progress

Fields

profileId*string
status*stringone of "not_started", "in_progress", "completed", "stopped", "error"
currentSitestring
sitesVisited*number
sitesFailednumber
totalSites*number
cookiesCollected*number
startedAtstring
errorstring
warningstring
reasonstring
phase*stringstarting until its first visit begins (the browser opening), visiting while a site is open (currentSite), waiting between two sites, finishing once the last site is done (the browser closes, the cookies are counted)one of "starting", "visiting", "waiting", "finishing"
lastSitestringThe site it visited last, from the end of its first visit

ExportResult

Fields

filePath*string
sizeBytes*number
profileName*string
unreadableCookiesinteger
cookieStoreProblemobject
reason*stringone of "no-key", "in-use", "unfinished", "damaged", "unreadable"
cookies*integer | null
message*string

ImportResult

Fields

profileId*string
profileName*string
hasFingerprint*boolean
hasProxy*boolean
hasCookies*boolean
hasUserData*boolean
tagCount*number
unreadableCookiesinteger
cookieRestoreProblemobject
reason*stringone of "no-key", "in-use", "unfinished", "damaged", "unreadable"
message*string

Notification

An in-app notification, as the app shows it in its bell

Fields

idstring
userIdstring
typestringWhat happened, for example team_member_joined, team_changed, share_received
titlestring
bodystring
payloadobjectWhat the notification is about (team, share, profile ids and names)
readAtstring | null
createdAtstring

Share

A profile shared directly with one person

Fields

idstring
ownerUserIdstring
targetUserIdstring
syncProfileIdstring
profileNamestring
permissionstringLAUNCH: the person opens it; VIEW: they see it onlyone of "LAUNCH", "VIEW"
createdAtstring
targetobjectWho it is shared with: id, email, name
ownerobjectWho shares it (an incoming share): id, email, name
syncProfileobjectThe profile's cloud copy, these fields only. Its stored settings, logins, storage keys and encryption details are never answered.
idstring
userIdstring
localProfileIdstring
profileNamestring
sizeBytesnumber
versioninteger
lastSyncedAtstring | null
deletedAtstring | nullWhen the owner deleted the profile from the cloud; null while it is there. outgoing still lists a share of a deleted profile, its names blank, until it is stopped (DELETE /shares/{id}); incoming never does
proxyLoginSetbooleanWhether the proxy login goes with the share
accountsSetbooleanWhether saved logins and 2FA go with the share

This reference is generated from the app's route definitions and committed with the code; a test in the repository fails whenever the routes and this file disagree, so it stays in step with the source. Your installed app serves its own copy at GET http://127.0.0.1:36542/api/v1/docs, the authoritative document for the version you are running (this page was generated from 2.2.0). The AI page in the app offers a plain-text briefing for agents, built from the same endpoint catalogue with your port and token filled in. Questions or a gap you hit: support@justbrowser.app.

We'd like to use Google Analytics, a Google service, to understand how our website is used. It sets two cookies in your browser and runs only if you click Accept. You can change your choice at any time with Cookie settings. Cookie Policy

Sign-in cookies and the cookie that remembers this choice are always on; the website needs them to work.

Google Analytics, a Google service, helps us understand how our website is used. It sets two cookies, _ga and _ga_TVZHQ99TZW. It is now onoff in this browser. If your browser sends a Global Privacy Control or Do Not Track signal, it stays off. Cookie Policy