Last checked against the contract: September 2026
Released, and in the build you can download today — on macOS and on Windows alike. The switch is in the app’s settings and the API stays off until you turn it on. Which calls that build answers is marked on every operation and on every example below, rather than written into a sentence here that the next release would make wrong.
A script on the same machine turns a profile’s browser into something it can drive. The interface is one service, one key and one address file — described first, because everything stands on them — and a handful of routes over the top: find a profile, open it, connect Puppeteer, Playwright or Selenium to the address it answers with, close it again.
Off by default, and reachable from this computer only.
Settings → API & Automation and turn on Local API. Until you do, nothing listens: the port is not opened, and a script gets a refused connection rather than an empty answer.127.0.0.1 and nowhere else. Another machine on your network cannot reach it, and there is no setting that opens it up — a script runs beside Liminal, not against it over the network.48361, a port of Liminal’s own so it does not collide with another browser already listening on the machine. Type a different one, or press Random free port and let the app pick. The change takes effect at once, without restarting Liminal.port_in_use. Nothing listens until you choose another port, so a script that reads the file knows the difference between "off" and "could not start".One key, shown once, kept where your operating system keeps secrets.
64 lowercase hexadecimal characters and shows it once. Leave the screen and it is hidden: the app cannot show it again, it can only issue a new one.Authorization: Bearer followed by the key itself. There is no query parameter and no cookie, and a request without the header is refused like a request with a wrong key.The app writes its address to a file, so nothing has to be typed twice.
Local API/status.json inside Liminal’s user-data directory. Read it instead of hardcoding a port: it follows the port you set and the one Random free port picked.enabled, status, address, port — and no secret of any kind.{"enabled":true,"status":"running","address":"http://127.0.0.1:48361","port":48361}off with an empty address and no port. The same shape, a different state — a script reads one file to learn everything.{"enabled":false,"status":"off","address":"","port":0}The call to start from: is Liminal running, and is anyone signed in.
/v1/status at the address from the file, with the key in the header.curl -H 'Authorization: Bearer <key>' http://127.0.0.1:48361/v1/status200, with the running build’s version and whether the app has someone signed in. A false signedIn is not an error — the API answers; it is the operations that read the catalog or open a profile that need an account.{"status":"running","version":"<version>","signedIn":true}401, and the code invalid_key — permanent, and the thing to branch on. The message beside it is the app’s own wording for a person reading a log; treat it as text that can change, not as part of the contract.{"error":{"code":"invalid_key","message":"Неверный ключ"}}127.0.0.1 and the port from the file. A request that arrives naming any other host is not answered, even when it reaches the same port — the service replies to its own address only.off.Said plainly, so nothing here reads as a promise it is not.
What each route is for, what it takes, what it answers, and every refusal it can give. The badge beside an operation says whether the build you can download today answers it at all.
Is Liminal running, and is anyone signed in
The cheapest call there is, and the one to poll while you wait for the app. It answers without an account: a false signedIn is a state, not an error.
None.
{
"status": "running",
"version": "<version>",
"signedIn": true
}The profiles in the catalog, filtered and paged
Reads the same catalog the app shows. Filters combine, and every one of them is exact except name, which matches any profile whose name contains what you typed, in any case.
{
"page": 1,
"pageSize": 100,
"total": 1,
"items": [
"<profile>"
]
}One profile, with its proxy and its fingerprint
The same object the list returns, for one identifier. The proxy address is shown; its password never is.
{
"id": "<profile-id>",
"name": "Shop EU",
"workspaceId": "<workspace-id>",
"folderId": "<folder-id>",
"status": "running",
"health": "ok",
"proxy": {
"id": "<proxy-id>",
"name": "Residential DE",
"type": "socks5",
"host": "proxy.example.net",
"port": 1080,
"working": true,
"lastCheckedExternalIp": "203.0.113.10",
"lastCheckedCountryCode": "DE"
},
"fingerprint": {
"platform": "MacIntel",
"language": "de-DE",
"timezone": "Europe/Berlin"
},
"lastOpenedAt": "2026-09-30T08:15:00.000Z"
}Open a profile and get the address a driver connects to
Starts the profile the way the app does — its fingerprint, its proxy, its cookies — and answers with the CDP address once the browser is up. The call waits; it does not return a job to poll.
{
"id": "<profile-id>",
"status": "running",
"cdpDiscoveryUrl": "http://127.0.0.1:48361/devtools/<token>/json/version",
"cdpBrowserUrl": "ws://127.0.0.1:9222/devtools/browser/<token>",
"seleniumDebuggerUrl": "127.0.0.1:9222",
"chromedriverPath": "/Applications/Liminal.app/.../chromedriver",
"debugPort": 9222,
"debugAddress": "127.0.0.1:9222",
"externalIp": "203.0.113.10",
"countryCode": "DE"
}Get a driver address for a profile that is already open
For a profile you opened by hand and now want to drive. It does not restart anything: the session, its tabs and its cookies stay as they are.
{
"id": "<profile-id>",
"status": "running",
"cdpDiscoveryUrl": "http://127.0.0.1:48361/devtools/<token>/json/version",
"cdpBrowserUrl": "ws://127.0.0.1:9222/devtools/browser/<token>",
"seleniumDebuggerUrl": "127.0.0.1:9222",
"chromedriverPath": "/Applications/Liminal.app/.../chromedriver",
"debugPort": 9222,
"debugAddress": "127.0.0.1:9222",
"externalIp": "203.0.113.10",
"countryCode": "DE"
}Close a profile the way its window would
Lets the session finish writing its state. This is the one to call between scripted runs on the same profile.
{
"id": "<profile-id>",
"status": "closed"
}Close a profile that will not close
The same answer, without waiting for the session to settle. Reach for it when a stop did not return, not as a matter of course.
{
"id": "<profile-id>",
"status": "closed"
}What is open right now, and what can be driven
Every profile that is open, whether a window or a call opened it — startedBy says which — with its driver address when one is available. Reconnect from here after your script restarts.
None.
{
"items": [
{
"id": "<profile-id>",
"workspaceId": "<workspace-id>",
"status": "running",
"automationAvailable": true,
"startedBy": "api",
"cdpBrowserUrl": "ws://127.0.0.1:9222/devtools/browser/<token>",
"seleniumDebuggerUrl": "127.0.0.1:9222",
"chromedriverPath": "/Applications/Liminal.app/.../chromedriver",
"debugPort": 9222,
"debugAddress": "127.0.0.1:9222"
}
]
}Each block is whole: it reads the address file, calls the API and connects the driver. Copy one, put the name of your own profile in it, and it runs. The badge says whether the build you can download today answers everything that block needs.
Connects over CDP to the address the start answered with. The closest thing to a script already written against AdsPower or Octo.
Calls /v1/profiles · /v1/profiles/{id}/start
import { readFileSync } from 'node:fs'
import puppeteer from 'puppeteer-core'
// Local API/status.json, inside Liminal's user-data directory. The settings
// screen shows the absolute path; that path and the key are your script’s to
// keep — the app puts neither into the environment for you.
const { address } = JSON.parse(readFileSync(process.env.LIMINAL_ADDRESS_FILE, 'utf8'))
async function call(path, init) {
const response = await fetch(address + path, {
...init,
headers: { Authorization: `Bearer ${process.env.LIMINAL_API_KEY}` },
})
const body = await response.json()
if (!response.ok) throw new Error(body.error.code)
return body
}
const { items } = await call('/v1/profiles?name=' + encodeURIComponent('Shop EU'))
const started = await call(`/v1/profiles/${items[0].id}/start`, { method: 'POST' })
const browser = await puppeteer.connect({ browserWSEndpoint: started.cdpBrowserUrl })
const page = await browser.newPage()
await page.goto('https://example.com')
console.log(await page.title())
await browser.disconnect()
The same connection through Playwright’s CDP entry point, into the context the profile already has rather than a fresh one.
Calls /v1/profiles · /v1/profiles/{id}/start
import { readFileSync } from 'node:fs'
import { chromium } from 'playwright'
// Local API/status.json, inside Liminal's user-data directory. The settings
// screen shows the absolute path; that path and the key are your script’s to
// keep — the app puts neither into the environment for you.
const { address } = JSON.parse(readFileSync(process.env.LIMINAL_ADDRESS_FILE, 'utf8'))
async function call(path, init) {
const response = await fetch(address + path, {
...init,
headers: { Authorization: `Bearer ${process.env.LIMINAL_API_KEY}` },
})
const body = await response.json()
if (!response.ok) throw new Error(body.error.code)
return body
}
const { items } = await call('/v1/profiles?name=' + encodeURIComponent('Shop EU'))
const started = await call(`/v1/profiles/${items[0].id}/start`, { method: 'POST' })
const browser = await chromium.connectOverCDP(started.cdpBrowserUrl)
const page = await browser.contexts()[0].newPage()
await page.goto('https://example.com')
console.log(await page.title())
await browser.close()
The Python side of the same thing, reading the address file with nothing outside the standard library.
Calls /v1/profiles · /v1/profiles/{id}/start
import json
import os
import urllib.parse
import urllib.request
from playwright.sync_api import sync_playwright
# Local API/status.json, inside Liminal's user-data directory. The settings
# screen shows the absolute path; that path and the key are your script’s to
# keep — the app puts neither into the environment for you.
with open(os.environ["LIMINAL_ADDRESS_FILE"], encoding="utf-8") as handle:
address = json.load(handle)["address"]
def call(path, method="GET"):
request = urllib.request.Request(address + path, method=method)
request.add_header("Authorization", "Bearer " + os.environ["LIMINAL_API_KEY"])
with urllib.request.urlopen(request) as response:
return json.load(response)
profile = call("/v1/profiles?name=" + urllib.parse.quote("Shop EU"))["items"][0]
started = call(f"/v1/profiles/{profile['id']}/start", method="POST")
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(started["cdpBrowserUrl"])
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
Selenium attaches to a browser that is already running, by the debugger address, and takes the chromedriver the answer points at — nothing is downloaded and nothing is guessed.
Calls /v1/profiles · /v1/profiles/{id}/start
import json
import os
import urllib.parse
import urllib.request
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
# Local API/status.json, inside Liminal's user-data directory. The settings
# screen shows the absolute path; that path and the key are your script’s to
# keep — the app puts neither into the environment for you.
with open(os.environ["LIMINAL_ADDRESS_FILE"], encoding="utf-8") as handle:
address = json.load(handle)["address"]
def call(path, method="GET"):
request = urllib.request.Request(address + path, method=method)
request.add_header("Authorization", "Bearer " + os.environ["LIMINAL_API_KEY"])
with urllib.request.urlopen(request) as response:
return json.load(response)
profile = call("/v1/profiles?name=" + urllib.parse.quote("Shop EU"))["items"][0]
started = call(f"/v1/profiles/{profile['id']}/start", method="POST")
options = webdriver.ChromeOptions()
options.debugger_address = started["seleniumDebuggerUrl"]
driver = webdriver.Chrome(service=Service(started["chromedriverPath"]), options=options)
driver.get("https://example.com")
print(driver.title)
driver.quit()
The same for Node: both the debugger address and the path to a matching chromedriver come out of the start answer.
Calls /v1/profiles · /v1/profiles/{id}/start
import { readFileSync } from 'node:fs'
import { Builder } from 'selenium-webdriver'
import chrome from 'selenium-webdriver/chrome.js'
// Local API/status.json, inside Liminal's user-data directory. The settings
// screen shows the absolute path; that path and the key are your script’s to
// keep — the app puts neither into the environment for you.
const { address } = JSON.parse(readFileSync(process.env.LIMINAL_ADDRESS_FILE, 'utf8'))
async function call(path, init) {
const response = await fetch(address + path, {
...init,
headers: { Authorization: `Bearer ${process.env.LIMINAL_API_KEY}` },
})
const body = await response.json()
if (!response.ok) throw new Error(body.error.code)
return body
}
const { items } = await call('/v1/profiles?name=' + encodeURIComponent('Shop EU'))
const started = await call(`/v1/profiles/${items[0].id}/start`, { method: 'POST' })
const driver = await new Builder()
.forBrowser('chrome')
.setChromeOptions(new chrome.Options().debuggerAddress(started.seleniumDebuggerUrl))
.setChromeService(new chrome.ServiceBuilder(started.chromedriverPath))
.build()
await driver.get('https://example.com')
console.log(await driver.getTitle())
await driver.quit()
The same contract as a file, at one address that does not move: OpenAPI, in JSON, generated from the data this page renders. Import it into Postman or Insomnia, or generate a client from it. Every operation in it carries the same availability as the badge above.
openapi.jsonThe release that shipped it, and every release that extends it, is in the changelog. A question about the contract, or a value here that does not match what your build does: [email protected].