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.
Sections
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.
- 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”.
- Issue a keySettings → API keys → “Issue key” with the “read” and “start and stop” permissions. The key is shown only once.
- Check the connectionA request to /health returns {"ok": true}.
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.
| Header | Value |
|---|---|
| Authorization | Bearer ino_live_… |
| X-API-Key | ino_live_… |
| Permission | In the client | Methods |
|---|---|---|
| read | read | /v1/profiles, /v1/running |
| launch | start 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.
# 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
Responds if the local API is enabled and listening on the port. No key required.
{ "ok": true}
curl http://127.0.0.1:50380/health const res = await fetch('http://127.0.0.1:50380/health');console.log(await res.json());// { ok: true }
List profiles
Profiles the key owner has access to. If the key is restricted to categories, only profiles in those categories. Key permission: read
| Field | Type | Description |
|---|---|---|
| id | string | Profile ID |
| name | string | Name |
| engine | string | firefox, chromium or android |
| os | string | Profile OS: macos, windows, linux |
| categoryId | string | Category ID |
{ "profiles": [ { "id": "3f9a2c1e-7b4d-…", "name": "FB UA 014", "engine": "firefox", "os": "windows", "categoryId": "c7e1…" } ]}
curl http://127.0.0.1:50380/v1/profiles \ -H "Authorization: Bearer ino_live_7Qk2…"
const api = 'http://127.0.0.1:50380';const headers = { Authorization: 'Bearer ' + process.env.INO_API_KEY }; const res = await fetch(api + '/v1/profiles', { headers });const { profiles } = await res.json();
Running profiles
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
| Field | Type | Description |
|---|---|---|
| profileId | string | Profile ID |
| name | string | Name at launch time |
| engine | string | Engine |
| stage | string | Stage: queued, locking, engine, sync-down, launching, running, stopping, sync-up, stopped, error |
| source | string | ui or local-api |
| startedAt | string | Start time, ISO 8601 |
| automation | object | protocol and wsEndpoint, local-api only |
{ "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…" } } ]}
curl http://127.0.0.1:50380/v1/running \ -H "Authorization: Bearer ino_live_7Qk2…"
const api = 'http://127.0.0.1:50380';const headers = { Authorization: 'Bearer ' + process.env.INO_API_KEY }; const res = await fetch(api + '/v1/running', { headers });const { running } = await res.json();
Start a profile
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| Field | Type | Description |
|---|---|---|
| headless | boolean | Run without a window. Defaults to false |
| Field | Type | Description |
|---|---|---|
| profileId | string | Profile ID |
| protocol | string | juggler — Firefox, cdp — Chromium, adb — Android |
| wsEndpoint | string | Endpoint for connecting automation |
{ "profileId": "3f9a2c1e-7b4d-…", "protocol": "juggler", "wsEndpoint": "ws://127.0.0.1:41733/0c5e…"}
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
import { firefox, chromium } 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 { protocol, wsEndpoint } = await res.json();const browser = protocol === 'cdp' ? await chromium.connectOverCDP(wsEndpoint) : await firefox.connect(wsEndpoint);
Stop a profile
Closes the browser, uploads changes to the profile folder and releases the lock. The concurrent-launch slot is freed. Key permission: launch
{ "profileId": "3f9a2c1e-7b4d-…", "stopped": true}
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
const api = 'http://127.0.0.1:50380';const headers = { Authorization: 'Bearer ' + process.env.INO_API_KEY };const id = '3f9a2c1e-7b4d-4e8a-9c21-5d6f0a8b7e14'; await fetch(api + `/v1/profiles/${id}/stop`, { method: 'POST', headers });
Errors
Errors come with an HTTP status and a body in a single format. details holds extra information when available.
{ "error": { "code": "limit", "message": "Concurrent launch limit reached (5)" }}
| HTTP | code | When |
|---|---|---|
| 401 | unauthorized | The key is missing, invalid or revoked |
| 403 | forbidden | The key lacks the required permission, or the profile is outside its categories |
| 403 | no-access | The key owner doesn’t have “Launch” access to the profile |
| 403 | bad_host | The Host header is neither 127.0.0.1 nor localhost |
| 403 | browser_origin | The request came from a web page in a browser |
| 404 | not_found | Unknown path |
| 402 | proxy-expired | The profile’s proxy rental has expired |
| 409 | locked | The profile is open by another team member |
| 409 | already-running | The profile is already open on this computer |
| 409 | os-mismatch | The profile OS doesn’t match this computer’s OS |
| 409 | busy | The operation isn’t possible right now, a sync is in progress |
| 429 | limit | The concurrent API launch limit has been reached |
| 501 | engine-unavailable | The profile’s engine is unavailable |
| 503 | not-signed-in | No one is signed in to the client |
| 500 | internal | Other launch errors |
Example: curl
Start a profile headless and stop it from the terminal. The key lives in an environment variable.
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.
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 });
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.
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 });