Local API

Launch profiles from your own scripts and attach Playwright or Puppeteer to the running browser — with the profile’s fingerprint, proxy and cookies.

http://127.0.0.1:50380JSONBearer keyJuggler · CDP

Quick start

The API runs inside the inoBrowser desktop client and listens on 127.0.0.1 only. The client must be open and you must be signed in.

  1. Enable the APIIn the client: Settings → Local API. The default port is 50380; you can pick any port from 1024 to 65535. Since version 0.1.17 the default port is 50380 (previously 50325, which clashed with the AdsPower Local API): after the update the client switches the old default port automatically; a port set manually stays as is. If the port is taken by another program, settings show the error “Port N is used by another program”.
  2. Issue a keySettings → API keys → “Issue key” with the “read” and “start and stop” permissions. The key is shown only once.
  3. Check the connectionA request to /health returns {"ok": true}.
First run
curl http://127.0.0.1:50380/health curl http://127.0.0.1:50380/v1/profiles \  -H "Authorization: Bearer ino_live_7Qk2…"

Authentication

Every request except /health carries an ino_live_… API key in one of these headers. A key never grants more rights than the team member who issued it has.

HeaderValue
AuthorizationBearer ino_live_…
X-API-Keyino_live_…
Key permissions
PermissionIn the clientMethods
readread/v1/profiles, /v1/running
launchstart and stop…/start, …/stop

Keys are verified on the inoBrowser server and the result is cached for a minute, so a revoked key stops working within a minute.

Headers
# Bearercurl http://127.0.0.1:50380/v1/profiles \  -H "Authorization: Bearer ino_live_7Qk2…" # or X-API-Keycurl http://127.0.0.1:50380/v1/profiles \  -H "X-API-Key: ino_live_7Qk2…"

Security and limits

  • The server listens on 127.0.0.1 only — it can’t be reached from other computers
  • The Host header must be 127.0.0.1 or localhost
  • Requests from web pages in a browser are rejected — call the API from scripts, not from web pages
  • The limit on concurrent API launches is set in Settings, 5 by default; profiles opened from the app don’t count toward it
  • A key restricted to certain categories can only see and start profiles in those categories

Health check

GET/health

Responds if the local API is enabled and listening on the port. No key required.

Response200
application/json
{  "ok": true}
Request
curl http://127.0.0.1:50380/health

List profiles

GET/v1/profiles

Profiles the key owner has access to. If the key is restricted to categories, only profiles in those categories. Key permission: read

FieldTypeDescription
idstringProfile ID
namestringName
enginestringfirefox, chromium or android
osstringProfile OS: macos, windows, linux
categoryIdstringCategory ID
Response200
application/json
{  "profiles": [    {      "id": "3f9a2c1e-7b4d-…",      "name": "FB UA 014",      "engine": "firefox",      "os": "windows",      "categoryId": "c7e1…"    }  ]}
Request
curl http://127.0.0.1:50380/v1/profiles \  -H "Authorization: Bearer ino_live_7Qk2…"

Running profiles

GET/v1/running

Profiles open on this computer — from the app and via the API. The connection endpoint is returned only for profiles started via the API. Key permission: read

FieldTypeDescription
profileIdstringProfile ID
namestringName at launch time
enginestringEngine
stagestringStage: queued, locking, engine, sync-down, launching, running, stopping, sync-up, stopped, error
sourcestringui or local-api
startedAtstringStart time, ISO 8601
automationobjectprotocol and wsEndpoint, local-api only
Response200
application/json
{  "running": [    {      "profileId": "3f9a2c1e-7b4d-…",      "name": "FB UA 014",      "engine": "firefox",      "stage": "running",      "source": "local-api",      "startedAt": "2026-11-18T09:41:07.512Z",      "automation": {        "protocol": "juggler",        "wsEndpoint": "ws://127.0.0.1:41733/0c5e…"      }    }  ]}
Request
curl http://127.0.0.1:50380/v1/running \  -H "Authorization: Bearer ino_live_7Qk2…"

Start a profile

POST/v1/profiles/{id}/start

Takes the profile, assembles its folder, launches the browser with the profile’s fingerprint and proxy, and returns an endpoint for Playwright or Puppeteer. The response arrives once the window is already open. Key permission: launch

Request body · optional
FieldTypeDescription
headlessbooleanRun without a window. Defaults to false
Response
FieldTypeDescription
profileIdstringProfile ID
protocolstringjuggler — Firefox, cdp — Chromium, adb — Android
wsEndpointstringEndpoint for connecting automation
Response200
application/json
{  "profileId": "3f9a2c1e-7b4d-…",  "protocol": "juggler",  "wsEndpoint": "ws://127.0.0.1:41733/0c5e…"}
Request
ID=3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14 curl -X POST \  -H "Authorization: Bearer ino_live_7Qk2…" \  -H "Content-Type: application/json" \  -d '{"headless": false}' \  http://127.0.0.1:50380/v1/profiles/$ID/start

Stop a profile

POST/v1/profiles/{id}/stop

Closes the browser, uploads changes to the profile folder and releases the lock. The concurrent-launch slot is freed. Key permission: launch

Response200
application/json
{  "profileId": "3f9a2c1e-7b4d-…",  "stopped": true}
Request
ID=3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14 curl -X POST \  -H "Authorization: Bearer ino_live_7Qk2…" \  http://127.0.0.1:50380/v1/profiles/$ID/stop

Errors

Errors come with an HTTP status and a body in a single format. details holds extra information when available.

HTTP 429
{  "error": {    "code": "limit",    "message": "Concurrent launch limit reached (5)"  }}
HTTPcodeWhen
401unauthorizedThe key is missing, invalid or revoked
403forbiddenThe key lacks the required permission, or the profile is outside its categories
403no-accessThe key owner doesn’t have “Launch” access to the profile
403bad_hostThe Host header is neither 127.0.0.1 nor localhost
403browser_originThe request came from a web page in a browser
404not_foundUnknown path
402proxy-expiredThe profile’s proxy rental has expired
409lockedThe profile is open by another team member
409already-runningThe profile is already open on this computer
409os-mismatchThe profile OS doesn’t match this computer’s OS
409busyThe operation isn’t possible right now, a sync is in progress
429limitThe concurrent API launch limit has been reached
501engine-unavailableThe profile’s engine is unavailable
503not-signed-inNo one is signed in to the client
500internalOther launch errors

Example: curl

Start a profile headless and stop it from the terminal. The key lives in an environment variable.

start-stop.sh
ID=3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14 # start the profile headlesscurl -X POST \  -H "Authorization: Bearer $INO_API_KEY" \  -H "Content-Type: application/json" \  -d '{"headless": true}' \  http://127.0.0.1:50380/v1/profiles/$ID/start # stop itcurl -X POST \  -H "Authorization: Bearer $INO_API_KEY" \  http://127.0.0.1:50380/v1/profiles/$ID/stop

Example: Playwright

Firefox profiles return a Juggler endpoint — connect with firefox.connect. Chromium profiles return CDP — use chromium.connectOverCDP.

firefox.mjs
import { firefox } from 'playwright'; const api = 'http://127.0.0.1:50380';const headers = { Authorization: 'Bearer ' + process.env.INO_API_KEY };const id = '3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14'; const res = await fetch(api + `/v1/profiles/${id}/start`, { method: 'POST', headers });const { wsEndpoint } = await res.json(); const browser = await firefox.connect(wsEndpoint);const context = browser.contexts()[0]; // the profile's context: cookies, tabsconst page = await context.newPage();await page.goto('https://www.browserscan.net'); await fetch(api + `/v1/profiles/${id}/stop`, { method: 'POST', headers });
chromium.mjs
import { chromium } from 'playwright'; const browser = await chromium.connectOverCDP(wsEndpoint);const context = browser.contexts()[0];const page = context.pages()[0] ?? await context.newPage();await page.goto('https://pixelscan.net');

Example: Puppeteer

For Chromium profiles: protocol in the response is cdp.

puppeteer.mjs
import puppeteer from 'puppeteer-core'; const api = 'http://127.0.0.1:50380';const headers = { Authorization: 'Bearer ' + process.env.INO_API_KEY };const id = '3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14'; const res = await fetch(api + `/v1/profiles/${id}/start`, { method: 'POST', headers });const { protocol, wsEndpoint } = await res.json(); // protocol === 'cdp' const browser = await puppeteer.connect({ browserWSEndpoint: wsEndpoint });const [page] = await browser.pages();await page.goto('https://abrahamjuliot.github.io/creepjs/'); await browser.disconnect();await fetch(api + `/v1/profiles/${id}/stop`, { method: 'POST', headers });

Launch a profile from your own script

© 2026 inoBrowserinobrowser.run