The local API lets a script on your computer manage MultiSession profiles: list, create, change, clone and delete them, start and stop them (one at a time or many at once, with or without a window), manage proxies, tags and cookies, and attach Playwright, Puppeteer or Selenium to a running browser.
The API is served by the desktop app on your own computer. Nothing is
exposed to the network, and the web version of MultiSession does not have
it. This is the whole reference. The same endpoints are also described as an
OpenAPI file, docs/local-api.openapi.json, which you can import into
Postman. The running app serves it too, at GET /v1/openapi.json.
The API listens on http://127.0.0.1:45100 from that moment, and again
every time the app starts, until you revoke the token. It also answers on
http://[::1]:45100 where the computer has an IPv6 loopback, so
localhost works on machines that resolve it to IPv6. With no token the
port is closed. Creating a new token replaces the old one. Revoking it turns
the API off. MULTISESSION_LOCAL_API_PORT overrides the default port.
Five steps. Replace YOUR_TOKEN with your token.
Authorization: Bearer YOUR_TOKEN.
Check it with curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:45100/v1/status.GET /v1/profiles.POST /v1/profiles/PROFILE_ID/start. The answer holds
the address to attach to.POST /v1/profiles/PROFILE_ID/stop. This saves the
profile's data and releases it.import { chromium } from "playwright";
const api = "http://127.0.0.1:45100/v1";
const headers = { Authorization: "Bearer YOUR_TOKEN" };
const started = await fetch(`${api}/profiles/PROFILE_ID/start`, { method: "POST", headers }).then((r) => r.json());
const browser = await chromium.connectOverCDP(started.cdp.http);
const page = await browser.contexts()[0].newPage();
await page.goto("https://example.com");
await browser.close();
await fetch(`${api}/profiles/PROFILE_ID/stop`, { method: "POST", headers });
On a browser reached with connectOverCDP, browser.close() only
disconnects. Use browser.contexts()[0], the profile's own context; a new
context would not have the profile's cookies.
import puppeteer from "puppeteer-core";
const api = "http://127.0.0.1:45100/v1";
const headers = { Authorization: "Bearer YOUR_TOKEN" };
const started = await fetch(`${api}/profiles/PROFILE_ID/start`, { method: "POST", headers }).then((r) => r.json());
const browser = await puppeteer.connect({ browserURL: started.cdp.http, defaultViewport: null });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.disconnect();
await fetch(`${api}/profiles/PROFILE_ID/stop`, { method: "POST", headers });
defaultViewport: null matters. Without it Puppeteer resizes every page to
800x600.
import requests
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
api = "http://127.0.0.1:45100/v1"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
started = requests.post(f"{api}/profiles/PROFILE_ID/start", headers=headers, json={"selenium": True}).json()
options = webdriver.ChromeOptions()
options.debugger_address = started["cdp"]["debuggerAddress"]
driver = webdriver.Chrome(service=Service(started["chromedriver"]["path"]), options=options)
driver.get("https://example.com")
driver.quit()
requests.post(f"{api}/profiles/PROFILE_ID/stop", headers=headers)
With debugger_address set, driver.quit() ends the Selenium session and
leaves the browser running. Stop the profile through the API afterwards.
curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:45100/v1/profiles
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:45100/v1/profiles/PROFILE_ID/start
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:45100/v1/profiles/PROFILE_ID/stop
http://127.0.0.1:45100. Every path starts with /v1.Authorization: Bearer <token> on every request. The
request must be addressed to 127.0.0.1, [::1] or localhost, and must
not come from a web page (Origin header).application/json (or a +json type), with no Content-Type, or
with the defaults of fetch (text/plain) and curl -d
(application/x-www-form-urlencoded). Any other content type is refused
with 415. An endpoint that takes no body ignores one if it is sent.
A body is at most 64 KB; the cookie import takes up to 2 MB.{ "code": "…", "message": "…", "details": { … } }.
details is there only when there is more to say. message is in English
whatever language the app is in; match on code, which does not change.
PROFILE_LOCKED, LAUNCH_BLOCKED and LAUNCH_FAILED also carry their
extra fields at the top level, as they always have.{ "items": [], "page": 1, "pageSize": 50, "total": 0 }.
Send page (from 1, default 1) and pageSize (1 to 100, default 50).
total counts every match on all pages.X-RateLimit-Limit (600), X-RateLimit-Remaining (requests left in
the current minute) and X-RateLimit-Reset (when the oldest request in the
window stops counting, in epoch seconds). Past the limit the answer is
429 RATE_LIMITED with Retry-After in seconds. The token keeps working;
wait and retry. GET /v1/status, GET /v1/openapi.json and
GET /v1/profiles/running are not counted.X-Request-Id. Quote it when you
write to support about a request.{ "profileId", "ok": true, "data": … } or
{ "profileId", "ok": false, "error": { "code", "message", "details" } }.
The error's extra fields, such as who holds a lock, are nested under
details.Every endpoint can also answer 401 UNAUTHORIZED, 403 FORBIDDEN_HOST,
403 FORBIDDEN_ORIGIN, 405 METHOD_NOT_ALLOWED, 429 RATE_LIMITED, and,
where it needs the app window, 503 APP_NOT_READY (the window is closed,
loading or signed out), 504 APP_TIMEOUT and 502 APP_ERROR. Endpoints with
a body can answer 415 UNSUPPORTED_MEDIA_TYPE. A refusal from the
MultiSession service is passed on as 400 INVALID_REQUEST, 403 FORBIDDEN,
403 PLAN_LIMIT (your plan's limit), 403 INSUFFICIENT_BALANCE,
404 NOT_FOUND, 409 CONFLICT or 429 RATE_LIMITED. The endpoint sections
below list only what is specific to them.
GET /v1/status{
"app": "MultiSession",
"version": "1.0.62",
"api": "v1",
"signedIn": true,
"account": { "email": "[email protected]" },
"engine": { "name": "Chromium", "version": "155.0.8059.84" },
"limits": { "requestsPerMinute": 600 }
}
It answers even while the app window is closed or signed out, with
signedIn: false and account: null. Wait for signedIn: true before
starting profiles. It waits at most two seconds for the app window, so it
works as a health probe. Not counted against the rate limit.
GET /v1/openapi.jsonThe OpenAPI 3.1 description of this API. Not counted against the rate limit.
GET /v1/workspacesQuery: page, pageSize. Lists the workspaces your account belongs to.
{ "items": [ { "id": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b", "name": "Main", "role": "OWNER", "isDefault": true } ],
"page": 1, "pageSize": 50, "total": 1 }
role is OWNER, ADMIN, MEMBER, VIEWER, or null when the service
does not report it. Errors: INVALID_PAGE, INVALID_PAGE_SIZE.
A profile object:
| Field | Type | Notes |
|---|---|---|
id |
string (uuid) | |
name |
string | |
workspaceId |
string (uuid) | The workspace your account reaches the profile through |
workspaceName |
string or null | |
os |
string | WINDOWS, MACOS or LINUX; empty when unknown |
browser |
string | CHROME, EDGE or OPERA; empty when unknown |
running |
boolean | true in every state but stopped |
state |
string | stopped, starting, running, stopping or syncing (saving its data after the browser closed), on this computer |
notes |
string or null | Free-text notes |
startUrl |
string or null | |
proxyId |
string (uuid) or null | |
tags |
string[] | Tag names |
createdAt |
string | ISO date-time |
state is about this computer. A profile a teammate has open elsewhere shows
stopped here and answers PROFILE_LOCKED when you start it.
GET /v1/profilesLists the profiles your account can see. All query parameters are optional:
| Parameter | Meaning |
|---|---|
workspaceId |
uuid. Profiles owned by, shared to, or reached through this workspace. |
search |
Name contains this text, case-insensitive, up to 100 characters. |
tag |
A tag name, exact, case-insensitive, up to 100 characters. |
state |
stopped, starting, running, stopping or syncing. |
page, pageSize |
Paging, as above. |
curl -H "Authorization: Bearer YOUR_TOKEN" "http://127.0.0.1:45100/v1/profiles?tag=ads&state=stopped&pageSize=2"
{
"items": [
{ "id": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "name": "Ads US", "workspaceId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"workspaceName": "Main", "os": "MACOS", "browser": "CHROME", "running": false, "state": "stopped",
"notes": null, "startUrl": null, "proxyId": null, "tags": ["ads"], "createdAt": "2026-11-01T10:00:00.000Z" }
],
"page": 1, "pageSize": 2, "total": 1,
"profiles": [ "every match, unpaged" ]
}
The profiles array is deprecated in favour of items. It still holds
every profile that matches the filters, unpaged, so an old script with more
than 50 profiles keeps seeing all of them. New scripts should page through
items. Errors: INVALID_PAGE, INVALID_PAGE_SIZE, INVALID_QUERY (a bad
workspaceId or state, or a search or tag over 100 characters).
GET /v1/profiles/{id}Returns one profile object. Errors: INVALID_PROFILE_ID, PROFILE_NOT_FOUND.
POST /v1/profilesCreates a profile. With name alone it is a quick profile: a random device
and the app's defaults, in your default workspace (the first one where you
are not a viewer). Unknown fields are refused.
| Field | Type and limits | Notes |
|---|---|---|
name |
required, string, 1 to 100 | |
workspaceId |
uuid | Default: your default workspace |
os |
windows, macos or linux |
Random when absent |
browser |
chrome, edge or opera |
Random when absent, among the browsers the OS offers. edge is not offered on linux. |
proxyId |
uuid | A proxy of the same workspace |
tags |
up to 20 strings, each 1 to 50 after trimming | Tag names; spaces around a name are cut and a repeated name is kept once |
notes |
string, up to 5000 | |
startUrl |
http or https URL, up to 2048 |
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Shop DE","os":"windows","browser":"chrome","tags":["shop"],"startUrl":"https://shop.example/"}' \
http://127.0.0.1:45100/v1/profiles
Answer: the created profile object, with state: "stopped". Errors:
INVALID_BODY, BROWSER_NOT_ON_OS, NO_WORKSPACE, PLAN_LIMIT (profile
limit), FORBIDDEN (no right to create in that workspace), NOT_FOUND
(unknown workspace or proxy).
POST /v1/profiles/batchCreates up to 50 profiles in one request. Either all are created or none is.
Body: count (required, 1 to 50) and the fields of POST /v1/profiles, with
name required. {n} in name is replaced with the number, from 1; without
{n} the number is added after a space, so "Ads" gives Ads 1, Ads 2.
The longest name that results (with count as the number) must still be at
most 100 characters, or the request is refused with INVALID_BODY.
Each profile gets its own fingerprint and its own random device within any
os or browser you fixed.
{ "count": 3, "name": "Ads {n}", "tags": ["ads"] }
Answer: { "created": [ profile, profile, profile ] }, in order. Errors: as for
POST /v1/profiles; a count outside 1 to 50 is INVALID_BODY.
PATCH /v1/profiles/{id}Changes a profile. Fields left out keep their value, and at least one is
required. os and workspaceId cannot be changed.
| Field | Type and limits | Notes |
|---|---|---|
name |
string, 1 to 100 | |
proxyId |
uuid or null | null removes the proxy |
tags |
up to 20 strings, each 1 to 50 after trimming | Replaces every tag; spaces around a name are cut and a repeated name is kept once |
notes |
string up to 5000, or null | null clears them |
startUrl |
http or https URL up to 2048, or null | null clears it |
{ "proxyId": null, "tags": ["ads", "us"] }
Answer: the updated profile object. Errors: INVALID_PROFILE_ID,
INVALID_BODY (an empty body included), PROFILE_NOT_FOUND, FORBIDDEN,
NOT_FOUND, INVALID_REQUEST (for example a proxy of another workspace).
DELETE /v1/profiles/{id}Moves the profile to the trash, as the app does; you can restore it in the app. A profile you reach only through a workspace it was shared to is removed from that workspace instead.
{ "profileId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "movedToTrash": true }
Errors: INVALID_PROFILE_ID, PROFILE_NOT_FOUND, FORBIDDEN, and
PROFILE_RUNNING (it is starting, running, stopping or syncing on this
computer; nothing is changed, stop it first).
POST /v1/profiles/{id}/cloneCopies the profile's notes, start page, tags, fingerprint (with a new seed),
hardware and runtime into a new profile, as the app's Clone does. The copy is
named "<name> (1)", or the next free number. No body. When the source sits
on someone else's plan, the copy goes into one of your own workspaces and the
proxy is copied only if the copy stays in the source's workspace. Answer: the
new profile object. Errors: INVALID_PROFILE_ID, PROFILE_NOT_FOUND,
CLONE_UNAVAILABLE (the source has no saved fingerprint yet), PLAN_LIMIT,
FORBIDDEN.
POST /v1/profiles/{id}/startOptional body:
| Field | Meaning |
|---|---|
startUrl |
An http or https URL to open instead of the profile's own start page, or null. |
localPassword |
The profile's local password, if it has one (up to 256 characters), or null. |
selenium |
true when the script uses Selenium. The answer then carries a chromedriver. |
headless |
true for no window, false for a window, for this start only. Left out, the profile's own setting applies, and the saved profile is not changed. |
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -d '{"headless":true}' http://127.0.0.1:45100/v1/profiles/PROFILE_ID/start
{
"profileId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc",
"sessionId": "5c1e…",
"cdp": {
"port": 51234,
"http": "http://127.0.0.1:51234",
"ws": "ws://127.0.0.1:51234/devtools/browser/…",
"debuggerAddress": "127.0.0.1:51234"
},
"chromedriver": { "path": "/Users/you/Library/Caches/MultiSession/chromedriver/155.0.8059.84/macos-arm64/chromedriver", "version": "155.0.8059.84" }
}
cdp.http is what Playwright's connectOverCDP and Puppeteer's browserURL
take. cdp.ws is the DevTools WebSocket. cdp.debuggerAddress is the same
port in the form Selenium's ChromeOptions takes. The port is different on
every start. chromedriver is there only when the request said
"selenium": true: Selenium needs a chromedriver that matches the browser's
build, so the app downloads the right one from Google's Chrome for Testing the
first time, checks it against a checksum built into the app, and keeps it.
Do not let Selenium Manager pick a driver itself. warnings, when present,
lists what the app would have shown as a notice, such as an extension that
could not be loaded.
A start through the API is the same start as a click in the app: it takes the
profile's lock, counts against the plan and restores saved cookies and
extensions. Starting a profile that the API already started returns the same
answer again, so a script that lost its connection can simply ask; a
different headless choice does not restart it.
Errors: INVALID_PROFILE_ID, INVALID_BODY, INVALID_START_URL,
INVALID_LOCAL_PASSWORD, INVALID_SELENIUM, INVALID_HEADLESS,
PROFILE_NOT_FOUND, PROFILE_LOCKED, PROFILE_BUSY,
RUNNING_WITHOUT_AUTOMATION, START_CANCELLED, LOCAL_PASSWORD_REQUIRED,
LOCAL_PASSWORD_INVALID, LAUNCH_BLOCKED, LAUNCH_FAILED,
SESSION_FAILED, CHROMEDRIVER_UNAVAILABLE.
POST /v1/profiles/{id}/stopCloses the browser, uploads the profile's data and releases its lock. Answer:
{ "profileId": "…" }. Allow up to a few minutes for a profile with a lot of
saved data. Detach your automation library first: in Puppeteer that is
browser.disconnect(); browser.close() would close the whole browser.
Errors: INVALID_PROFILE_ID, NOT_RUNNING, PROFILE_BUSY.
POST /v1/profiles/startStarts up to 20 profiles, at most three at a time, each exactly as the single start would.
| Field | Meaning |
|---|---|
ids |
Required. 1 to 20 profile ids, each once (compared without regard to case). |
selenium |
Optional boolean. The driver is fetched once and added to every started profile. |
headless |
Optional boolean, as for the single start, for every profile. |
startUrl and localPassword are not taken: each profile opens its own start
page, and a profile with a local password answers LOCAL_PASSWORD_REQUIRED in
its result.
{ "ids": ["0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "6a1d1b0e-41a4-4d1c-9a35-2a8a3e0c8a11"], "headless": true }
{ "results": [
{ "profileId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "ok": true,
"data": { "profileId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "sessionId": "5c1e…", "cdp": { "port": 51234, "http": "http://127.0.0.1:51234", "ws": "ws://127.0.0.1:51234/devtools/browser/…", "debuggerAddress": "127.0.0.1:51234" } } },
{ "profileId": "6a1d1b0e-41a4-4d1c-9a35-2a8a3e0c8a11", "ok": false,
"error": { "code": "PROFILE_LOCKED", "message": "Someone else is using this profile",
"details": { "lockedBy": { "name": "Anna", "email": "[email protected]" }, "lockedAt": "2026-11-15T10:00:00.000Z" } } }
] }
The answer is 200 even when some profiles are refused, and the started ones
stay started. Whole-request errors: INVALID_BODY, INVALID_IDS,
INVALID_SELENIUM, INVALID_HEADLESS, CHROMEDRIVER_UNAVAILABLE (nothing
started) and APP_NOT_READY (the app window is closed or signed out, so
none could be tried). A per-profile error can carry any code of the single
start, including APP_TIMEOUT and APP_NOT_READY for a window that did not
answer that profile (that start is cancelled); the other profiles are still
tried.
POST /v1/profiles/stopBody: { "ids": [ … ] }, 1 to 20 distinct profile ids. Each is stopped as the
single stop would be, at most three at a time. Answer: { "results": [ … ] }
in the same shape as the bulk start, with data: { "profileId" } on success.
This stops a profile opened by hand too. Per-profile errors: NOT_RUNNING,
PROFILE_BUSY (still starting), APP_NOT_READY, APP_TIMEOUT, APP_ERROR.
A profile that is already closing answers ok.
POST /v1/profiles/stop-allNo body. Stops every profile on this computer that was started through the
API, and none opened by hand. Answers { "results": [ … ] }, one per profile
it tried to stop; { "results": [] } when there is none. A start still under
way answers PROFILE_BUSY. It keeps working after the app window reloads.
GET /v1/profiles/runningQuery: page, pageSize. Lists what runs on this computer in every state but
stopped, whether opened by hand or through the API. Not counted against the
rate limit.
{ "items": [
{ "profileId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "sessionId": "5c1e…", "state": "running", "startedByApi": true,
"cdp": { "port": 51234, "http": "http://127.0.0.1:51234", "ws": "ws://127.0.0.1:51234/devtools/browser/…", "debuggerAddress": "127.0.0.1:51234" } },
{ "profileId": "6a1d1b0e-41a4-4d1c-9a35-2a8a3e0c8a11", "sessionId": "9f2a…", "state": "running", "startedByApi": false, "cdp": null }
], "page": 1, "pageSize": 50, "total": 2 }
cdp is null for a profile opened by hand or one still starting.
A proxy object: id, workspaceId, name, type (HTTP, HTTPS or
SOCKS5), host, port, username (or null), hasPassword (boolean),
country (or null) and lastCheck ({ "ok", "at" } or null). The password
is never returned. Every proxy endpoint takes workspaceId (uuid): in the
query for list, change, delete and check, and in the body for create.
GET /v1/proxies?workspaceId=…Query: workspaceId (required), page, pageSize.
{ "items": [ { "id": "5d6c9a1e-0c1b-4c1d-8e2f-3a4b5c6d7e8f", "workspaceId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "name": "DE one", "type": "SOCKS5", "host": "10.0.0.1", "port": 1080,
"username": "user", "hasPassword": true, "country": "DE", "lastCheck": { "ok": true, "at": "2026-11-15T10:00:00.000Z" } } ],
"page": 1, "pageSize": 50, "total": 1 }
Errors: INVALID_QUERY (missing or bad workspaceId), INVALID_PAGE, INVALID_PAGE_SIZE.
POST /v1/proxies| Field | Type and limits |
|---|---|
workspaceId |
required, uuid |
type |
required, HTTP, HTTPS or SOCKS5 (upper case) |
host |
required, string, 1 to 255 after trimming; spaces around it are cut, blank is refused |
port |
required, whole number, 1 to 65535 |
name |
string, 1 to 255 after trimming, blank is refused; default host:port |
username, password |
strings, up to 255 each |
{ "workspaceId": "0b4b38ca-dd2d-47f8-aa50-f48bd1e1a7bc", "type": "SOCKS5", "host": "10.0.0.1", "port": 1080, "username": "user", "password": "secret" }
Answer: the proxy object, with hasPassword: true. Errors: INVALID_BODY,
PLAN_LIMIT (the plan's proxy limit is reached), NOT_FOUND (unknown workspace).
PATCH /v1/proxies/{id}?workspaceId=…Body: any non-empty subset of type, host, port, name, username,
password, with the limits above. Answer: the updated proxy object. Errors:
INVALID_PROXY_ID, INVALID_QUERY, INVALID_BODY (an empty body included),
PROXY_NOT_FOUND.
DELETE /v1/proxies/{id}?workspaceId=…Answer: { "id": "…" }. Errors: INVALID_PROXY_ID, INVALID_QUERY,
PROXY_NOT_FOUND, CONFLICT if the service refuses.
POST /v1/proxies/{id}/check?workspaceId=…Tests the proxy connection now. No body.
{ "ok": true, "latencyMs": 120, "ip": "203.0.113.7", "country": "DE" }
latencyMs, ip and country are there only when known. Errors:
INVALID_PROXY_ID, INVALID_QUERY, PROXY_NOT_FOUND.
A tag is { "id", "name", "createdAt" }.
GET /v1/tags: query page, pageSize. Answers the paged list.
Errors: INVALID_PAGE, INVALID_PAGE_SIZE.POST /v1/tags: body { "name": "vip" }, 1 to 50 characters, not blank,
no other field. Answers the tag. Errors: INVALID_BODY, CONFLICT (the name
exists).DELETE /v1/tags/{id}: answers { "id": "…" }. The tag also leaves the
profiles that carry it. Errors: INVALID_TAG_ID, TAG_NOT_FOUND.{ "items": [ { "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b", "name": "vip", "createdAt": "2026-11-01T10:00:00.000Z" } ], "page": 1, "pageSize": 50, "total": 1 }
POST /v1/profiles/{id}/cookiesSaves cookies onto a stopped profile, as importing a file in the profile's settings does. Nothing goes into the browser now: the browser takes the cookies on the profile's next start, and the app then removes them from the profile. A new import replaces any cookies still waiting. The body can be up to 2 MB and the saved cookies up to 1,000,000 characters. Send one of two formats.
JSON:
{ "format": "json", "cookies": [
{ "name": "sid", "value": "abc123", "domain": ".example.com", "path": "/", "expires": 1900000000, "httpOnly": true, "secure": true, "sameSite": "Lax" }
] }
cookies holds 1 to 5000 objects. Each needs name and domain (non-empty
strings). Optional: value (default empty), path (default /), expires
(seconds since 1970; null or missing is a session cookie; expirationDate
and expiry are read too, for browser-extension exports), httpOnly,
secure (forced true when sameSite is None), sameSite (Strict, Lax
or None, any case; no_restriction means None; anything else is Lax).
Netscape cookies.txt:
{ "format": "netscape", "text": "# Netscape HTTP Cookie File\n.example.com\tTRUE\t/\tTRUE\t1900000000\tsid\tabc123" }
One cookie per line, seven tab-separated fields: domain, include-subdomains
flag, path, secure (TRUE or FALSE), expires (seconds, 0 for a session
cookie), name, value. Blank lines and # comments are skipped; a #HttpOnly_
prefix marks an HttpOnly cookie. At most 5000 cookies.
Answer: { "profileId": "…", "imported": 2 }. Errors: INVALID_PROFILE_ID,
INVALID_BODY, INVALID_COOKIES (with details.index or details.line where
it applies; a cookie's value is never echoed; nothing is saved on any
refusal), BODY_TOO_LARGE, PROFILE_RUNNING (stop the profile first),
PROFILE_NOT_FOUND.
GET /v1/profiles/{id}/cookiesReads the cookies from the running browser of a profile that is running on this computer and was started through the API. No body.
{ "cookies": [
{ "name": "sid", "value": "abc123", "domain": ".example.com", "path": "/", "expires": 1900000000, "httpOnly": true, "secure": true, "sameSite": "Lax" },
{ "name": "pref", "value": "1", "domain": "example.com", "path": "/", "expires": null, "httpOnly": false, "secure": false, "sameSite": null }
] }
expires is seconds since 1970, or null for a session cookie. sameSite is
Strict, Lax, None or null. Errors: INVALID_PROFILE_ID, NOT_RUNNING,
RUNNING_WITHOUT_AUTOMATION (it was opened by hand and has no automation
port; close it and start it through the API).
DELETE /v1/profiles/{id}/cookiesRemoves the cookies saved onto the profile that its browser has not taken yet
(the app's "clear session cookies"). Cookies already in the browser and the
saved session stay. Works in any state. Answer: { "profileId": "…" }.
Errors: INVALID_PROFILE_ID, PROFILE_NOT_FOUND, FORBIDDEN.
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_BODY |
The body is not JSON, not a JSON object, or has a missing, bad or unknown field. |
| 400 | INVALID_REQUEST |
The MultiSession service refused the request as invalid. details.reason says why. |
| 400 | INVALID_QUERY |
A query parameter is missing or bad. |
| 400 | INVALID_PAGE, INVALID_PAGE_SIZE |
page is not a whole number from 1, or pageSize is not 1 to 100. |
| 400 | INVALID_PROFILE_ID, INVALID_PROXY_ID, INVALID_TAG_ID |
The id in the path is not a uuid. |
| 400 | INVALID_IDS |
ids is not 1 to 20 distinct uuids. |
| 400 | INVALID_START_URL, INVALID_LOCAL_PASSWORD, INVALID_SELENIUM, INVALID_HEADLESS |
A start option has the wrong type or value. |
| 400 | INVALID_COOKIES |
The cookies could not be read. details points at the entry. |
| 400 | BROWSER_NOT_ON_OS |
The browser is not offered on that operating system. |
| 401 | UNAUTHORIZED |
No token, or a wrong one. |
| 403 | FORBIDDEN_ORIGIN |
The request came from a web page. |
| 403 | FORBIDDEN_HOST |
The request was not addressed to 127.0.0.1, [::1] or localhost. |
| 403 | FORBIDDEN |
Your role does not allow this. |
| 403 | PLAN_LIMIT |
Your plan's limit is reached. |
| 403 | INSUFFICIENT_BALANCE |
Not enough balance. |
| 403 | NO_WORKSPACE |
There is no workspace where you can create profiles. |
| 403 | LAUNCH_BLOCKED |
The plan does not allow this start. reason says why. |
| 403 | LOCAL_PASSWORD_REQUIRED, LOCAL_PASSWORD_INVALID |
Send localPassword. |
| 404 | PROFILE_NOT_FOUND, PROXY_NOT_FOUND, TAG_NOT_FOUND |
Your account cannot see such an item. |
| 404 | NOT_FOUND |
No such endpoint, or the service did not find the item (an unknown workspace, for example). |
| 405 | METHOD_NOT_ALLOWED |
The path exists with another method. The Allow header lists it. |
| 409 | PROFILE_LOCKED |
Someone else has it open. lockedBy names them (name, email); lockedAt says since when. |
| 409 | RUNNING_WITHOUT_AUTOMATION |
The profile was opened by hand. Close it, then start it through the API. |
| 409 | PROFILE_BUSY |
It is starting or closing. Try again in a moment. |
| 409 | PROFILE_RUNNING |
The profile is running on this computer. Stop it first. |
| 409 | NOT_RUNNING |
The profile is not running here. |
| 409 | ALREADY_RUNNING |
The profile is already running. |
| 409 | START_CANCELLED |
The start was cancelled before the browser opened. |
| 409 | CLONE_UNAVAILABLE |
The profile has no saved fingerprint yet. |
| 409 | CONFLICT |
The service refused because of the current state, such as a duplicate name. |
| 413 | BODY_TOO_LARGE |
The body is over 64 KB (2 MB for the cookie import). |
| 415 | UNSUPPORTED_MEDIA_TYPE |
The body was sent with a Content-Type that is not JSON, plain text or a form. Send the body as JSON. |
| 426 | APP_UPDATE_REQUIRED |
This version of the app is too old for the service. Update it. |
| 429 | RATE_LIMITED |
Over 600 requests a minute. Wait Retry-After seconds. |
| 500 | LAUNCH_FAILED |
The browser did not start. reason carries the cause. |
| 502 | SESSION_FAILED, APP_ERROR |
The app could not reach the service, or failed. |
| 502 | CHROMEDRIVER_UNAVAILABLE |
selenium was asked for and the driver could not be downloaded. Nothing was started. |
| 503 | APP_NOT_READY |
The app window is closed, loading, or signed out. |
| 504 | APP_TIMEOUT |
The app did not finish in time. A start that timed out is cancelled, so the profile does not open later. |
The API never takes a profile over from a teammate. That stays a decision for a person in the app.
Attaching a library does not change the profile's fingerprint. We checked
with our own fingerprint check and with public checkers
(docs/notes/fs15-local-api-cdp-spike.md).
The library itself is another matter. Stock Playwright and Puppeteer switch
on a part of the DevTools protocol that a page can notice, and pages that
test for automation do notice it. Selenium is the easiest of the three to
notice: on top of the same signal, chromedriver adds its own variables to
every page. That is how those libraries work and the browser cannot hide it. Patchright
is a drop-in replacement for Playwright that does not send that signal; it
attaches the same way, with connectOverCDP. Use it for QA of pages that
treat test automation differently from a person.
cdp address has
no password of its own. That is how the DevTools protocol works. Any
program running under your user account that finds the port can control
that browser. Profiles you open by hand have no such port.