Local API reference: manage browser profiles from your scripts.

Overview

The local API is a Prism Pro feature for managing profiles in bulk from your own scripts: create profiles from your own data, start them in order, check their status and close them when you are done. It manages profiles only — it does not read cookies, passwords, proxy credentials or page content, and it offers no Puppeteer / Playwright debugging endpoint. To let an AI read pages, click and fill in forms, use MCP.

Quick start

1. Start the local API

   In Prism, open “Automation API” on the left and click “Start Local API”. This feature requires Prism Pro.

2. Copy the address and token

   The window shows the “API Address” and the “Session Access Token”. The token is shown only once, when the API starts, so copy it right away; to get a new token later, stop and restart the API.

3. Send your first request

   Set two variables in a terminal, then check the service status and list your profiles. A response containing "state": "running" means the address and token work.

PRISM_API='http://127.0.0.1:43123'   # the API address shown in Prism
PRISM_TOKEN='<token>'                # the token shown in Prism

curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/status"
curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles"

In Windows PowerShell, curl is an alias for a different command: type curl.exe instead, or use PowerShell’s built-in Invoke-RestMethod:

$api = 'http://127.0.0.1:43123'
$headers = @{ Authorization = 'Bearer <token>' }
(Invoke-RestMethod -Uri "$api/v1/profiles" -Headers $headers).result | Format-Table serialNumber, name, status

Request rules

The API accepts only requests sent by scripts or programs on this computer. A request that breaks one of these rules is not executed and returns the error shown:

Prism handles local API and MCP requests one at a time, in the order received. Starting a profile includes a proxy check and opening the browser, which usually takes a few seconds; later requests wait in line. Wait for each request to return before sending the next.

Endpoints

{id} is a profile ID, taken from the result of GET /v1/profiles. Successful responses use HTTP status 200; except for GET /v1/status, the result is in the result field. The API has no endpoints for editing or deleting profiles.

Profile object

The profile list, profile status, start and close all return the same profile object:

{
  "result": {
    "id": "8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70",
    "serialNumber": 12,
    "name": "Shop A",
    "group": "Project A",
    "tags": ["automation"],
    "status": "running",
    "lastOpenedAt": "2026-10-02T08:30:00.000Z"
  }
}

Responses never include proxy addresses or credentials, fingerprint settings, cookies, passwords, site data or extension data.

Query, start and close

GET /v1/status

Returns the service status, to confirm that the address and token work. This is the only response not wrapped in result:

{
  "state": "running",
  "transport": "loopback",
  "protocolVersion": 1
}

GET /v1/profiles

Returns an array of profile objects, most recently modified first. Profiles in the Trash are not included.

GET /v1/profiles/{id}/status

Returns the current state of one profile. A profile that does not exist or is in the Trash returns 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Works like clicking “Open” in the app: Prism checks the kernel and the Pro kernel license, tests the proxy and exit IP changes, then opens the browser window. On success it returns the profile object with status running.
• If the profile is already running, its current state is returned and nothing is opened twice.
• Prism handles the next request only after a start request returns. To start many profiles, call the endpoint for each in turn; how many can run at the same time depends on your computer’s memory and CPU.
• If the kernel is missing, the proxy check fails, the proxy exit IP has changed (with the block policy) or a leftover process remains, the start fails with 502 and error.message explains why.
• Cases where the app would ask you to confirm fail outright through the API — for example, when geolocation sources disagree about the proxy exit. For these errors, open the profile in the Prism app or switch its network identity to manual.
• Profiles you call the start endpoint for (including ones that were already running) are tracked, and “Emergency Stop” in the “Automation API” window closes them. “Stop API” and the stop and emergency-stop buttons in the MCP window only stop the API; these profiles stay open.

POST /v1/profiles/{id}/close

Closes the browser window, keeps the profile data and returns the profile object with status closed; if the profile is not running, closed is returned right away. If the browser has not exited after 8 seconds and still holds the data folder, the status is orphaned; calling close again ends the leftover process.

PROFILE_ID='8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70'   # an id from GET /v1/profiles
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/start"
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/close"

Create profiles

The creation endpoints save new profiles in the closed state; no browser is opened. Every field is optional: omitted fields take the same defaults as “New Profile” in the app, and each profile gets a new fingerprint seed. Unknown fields are rejected.

Create one profile

curl -X POST "$PRISM_API/v1/profiles" \
  -H "Authorization: Bearer $PRISM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-b-001" \
  -d '{
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "startUrls": ["https://example.com/"],
    "proxy": { "protocol": "socks5", "host": "203.0.113.10", "port": 1080, "username": "user", "password": "pass" }
  }'

On success, the new profile is returned:

{
  "result": {
    "id": "3b1f7a52-9c4e-4d2b-8f60-1a2b3c4d5e6f",
    "serialNumber": 13,
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "status": "closed"
  }
}

Create in batches

The body of POST /v1/profiles/batch is a profiles array of 1–50 items, each written like a single creation, except that requestKey goes at the top level or in the header. Prism validates every profile first: if any is invalid, nothing is created and the error names the profile and the field (profiles[1] is the second profile; counting starts at 0). Results are returned in input order:

{
  "requestKey": "shops-batch-001",
  "profiles": [
    { "name": "Shop C", "group": "Project A" },
    { "name": "Shop D", "group": "Project A", "fingerprint": { "platform": "windows" } }
  ]
}

{
  "result": {
    "profiles": [
      { "id": "…", "serialNumber": 14, "name": "Shop C", "group": "Project A", "tags": [], "status": "closed" },
      { "id": "…", "serialNumber": 15, "name": "Shop D", "group": "Project A", "tags": [], "status": "closed" }
    ],
    "count": 2
  }
}

Profile fields

Proxy fields

Fingerprint fields

Hardware templates

A template that does not match platform is rejected. Window position and size, cookies, extension data and similar settings cannot be set through the API; change them in the Prism app after creation.

Safe retries

When the network drops or a request times out, you may not know whether the profile was created. Give each creation a request key, and a retry will never create it twice:

• Send a key in the Idempotency-Key header or the requestKey body field: 8–128 characters made of ASCII letters, digits and . _ : -. If you send both, they must match.
• Retrying with the same key and the same content within 24 hours returns the profiles created the first time (HTTP 200), even after Prism restarts.
• The same key with different content returns 409 IDEMPOTENCY_CONFLICT. If a profile from the first request has been deleted (including moved to the Trash), the API returns 409 IDEMPOTENCY_RESULT_GONE instead of quietly creating it again; use a new key to create it again.
• After 24 hours, the same key counts as a new request.
• Up to 1,000 keyed requests are kept for 24 hours, a limit shared with MCP creation (each MCP creation uses one); at the limit the API returns 429 IDEMPOTENCY_CAPACITY until old records expire.
• Keys and request contents are kept on this computer only as keyed digests, never as plain text, so no proxy password is stored with them.

Build keys from your own data, such as a spreadsheet row or an order number: shop-b-001.

Errors

When a request is rejected at the entrance (see “Request rules”), error is a string such as {"error":"unauthorized"}. When Prism fails while handling a request, error is an object:

{
  "error": {
    "code": "INVALID_PROFILE_INPUT",
    "message": "Invalid profile creation request; see details",
    "retryable": false,
    "details": [
      { "path": "profiles[1].proxy.port", "message": "Too big: expected number to be <=65535" }
    ]
  }
}

Programs should rely on the HTTP status and code; message is a human-readable explanation, partly in Chinese, and its wording may change between versions. When retryable is true, the same request can be retried later. details appears only for invalid creation fields, with at most 20 entries, and never repeats the submitted values.

MCP_REQUEST_FAILED is a general error name used inside Prism; the local API uses it too.

Code examples

Replace the address and token in the examples with the values shown in Prism. The examples create profiles, then start and close the new one.

Python

Requires requests (pip install requests):

import requests

API = "http://127.0.0.1:43123"   # the API address shown in Prism
TOKEN = "<token>"                # the token shown in Prism

session = requests.Session()
session.headers["Authorization"] = f"Bearer {TOKEN}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=70, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code}: {body['error']}")
    return body.get("result", body)

created = call("POST", "/v1/profiles/batch",
               headers={"Idempotency-Key": "shops-batch-002"},
               json={"profiles": [{"name": "Shop C"}, {"name": "Shop D"}]})
for profile in created["profiles"]:
    print("created", profile["serialNumber"], profile["id"])

profiles = call("GET", "/v1/profiles")
for profile in profiles:
    print(profile["serialNumber"], profile["name"], profile["status"])

first = created["profiles"][0]["id"]
print(call("POST", f"/v1/profiles/{first}/start")["status"])   # running
print(call("POST", f"/v1/profiles/{first}/close")["status"])   # closed

Node.js

Node.js 18 and later include fetch, so nothing needs to be installed:

// prism.mjs — run with: node prism.mjs (Node.js 18 or later)
const API = 'http://127.0.0.1:43123' // the API address shown in Prism
const TOKEN = '<token>'              // the token shown in Prism

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(70_000),
  })
  const data = await response.json()
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data.error)}`)
  return data.result ?? data
}

const profile = await call('POST', '/v1/profiles', {
  name: 'Shop E',
  fingerprint: { language: 'en-US', timezone: 'America/New_York', networkIdentityMode: 'manual' },
}, { 'Idempotency-Key': 'shop-e-001' })
console.log('created', profile.serialNumber, profile.id)

console.log((await call('POST', `/v1/profiles/${profile.id}/start`)).status) // running
console.log((await call('POST', `/v1/profiles/${profile.id}/close`)).status) // closed

Local API and MCP

The local API is meant for your own scripts; AI clients should connect to Prism through MCP. MCP has its own token and permissions: only the profiles allowed in “Local AI · MCP” are visible to the AI, and the AI cannot call the local API. Both share the same local service and the limit of 120 requests per 60 seconds; stopping MCP or using its emergency stop also stops the local API.

An AI can also create profiles with the MCP tools prism_create_profile and prism_create_profiles, which take the same fields as this page. This requires turning on “Allow AI to create profiles” in “Local AI · MCP” (off by default); whether the AI may control the new profiles depends on your profile access mode. MCP and the local API keep separate request keys but share the limit of 1,000 records per 24 hours.

Security

• The token is the key to managing profiles on this computer: keep it out of code repositories, logs and chats. If it may have leaked, stop and restart the API; the old token stops working immediately.
• The API listens only on 127.0.0.1, so other devices on your network or the internet cannot reach it directly. The Host check mainly stops browsers and accidental misuse and is not access control; do not expose the API through port forwarding or a reverse proxy.
• Other programs on this computer can call the API if they get the token. Enable it only on computers you trust, and click “Stop API” when you are done.
• “Emergency Stop” in the “Automation API” window stops the API and closes the profiles started through the API in this session that are still running.
• Every request Prism executes is written to the local audit log vault/logs/automation-audit.jsonl (in the Prism data folder) with the time, action, result, request ID, profile IDs and failure reason — never the token, request content or page content. Requests rejected by the request rules and GET /v1/status are not logged.

FAQ

Can I call the API from a web page or a browser extension?

No. Requests sent by a browser carry an Origin header, which the API rejects. Call it from a terminal, a script or a local program.

Why does localhost return 403?

The API requires the Host header to match 127.0.0.1 and the port of the API address exactly, so localhost is rejected. Use 127.0.0.1 as the host name.

The “Automation API” window shows the API running but no token. What should I do?

With MCP enabled, Prism automatically starts the local service that the API and MCP share, so the window shows only the address. The token is shown only once, when “Start Local API” succeeds: click “Stop API”, then “Start Local API” to get a new token. MCP is disconnected while the service is stopped.

Does the old token still work after Prism restarts?

No. Every API start creates a new port and token; stopping the API or quitting Prism invalidates the old token.

Can the API edit or delete profiles?

No. The API can create, query, start and close profiles; edit and delete profiles in the Prism app.

Can I connect Puppeteer, Playwright or Selenium?

No. The API provides no debugging port or WebDriver address. For page-level actions, let an AI client do them through MCP.

Can I start many profiles at once?

Call the start endpoint for each profile in turn. Prism handles requests one at a time and moves on once a profile has started; how many can run together depends on your computer’s memory and CPU.

Does it work on Windows?

Yes. Prism Pro provides the same local API on macOS and Windows. In Windows PowerShell, use curl.exe or Invoke-RestMethod.

Related features and guides