Developer API

The app has a local API and an MCP server. Your scripts can list, create, open and close profiles and run workflows on them, and an AI assistant such as Claude, Cursor or VS Code can do the same for you. Both are on the paid plans: on the Free plan a request with the key is refused with 402.

1. Switch it on and get your key

1. In the app, open Developer API in the sidebar.
2. Turn on the switch under Access. The page shows the base URL and your key, which starts with wx_.
3. Choose Show or Copy to use it.

Send the key on every request as Authorization: Bearer <key>. Without it, or with the switch off, the answer is 401.

• Switching the API off stops the key at once. Switching it back on brings the same key back.
• Regenerating gives a new key. Every script and MCP config using the old one needs the new one.

2. Your first call

List your profiles:

curl http://127.0.0.1:47110/api/v1/profiles \
  -H "Authorization: Bearer wx_..."

Every answer is JSON, with the result under data. An error comes back as { "error": { "code": "...", "message": "..." } }, for example PROFILE_NOT_FOUND.

Open one, then close it:

curl -X POST http://127.0.0.1:47110/api/v1/profiles/<id>/launch \
  -H "Authorization: Bearer wx_..." \
  -H "Content-Type: application/json" \
  -d '{ "mode": "headless" }'

curl -X POST http://127.0.0.1:47110/api/v1/profiles/<id>/stop \
  -H "Authorization: Bearer wx_..."

mode is normal (a window), hidden (a minimised window that keeps running as though on screen) or headless (no window: lighter, but easier for sites to detect).

Connecting Playwright or Puppeteer

On the Chromium and ShardX engines, the launch answer's endpoint is the browser's DevTools address. Connect to it and drive the profile with its own fingerprint, cookies and proxy:

import { chromium } from "playwright";

const headers = { Authorization: "Bearer wx_..." };
const launch = await fetch("http://127.0.0.1:47110/api/v1/profiles/<id>/launch", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ mode: "normal" })
}).then((response) => response.json());

const browser = await chromium.connectOverCDP(launch.data.endpoint);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");

Running a workflow

curl -X POST http://127.0.0.1:47110/api/v1/workflows/<id>/run \
  -H "Authorization: Bearer wx_..." \
  -H "Content-Type: application/json" \
  -d '{ "profileIds": ["<profile id>"], "concurrency": 2, "mode": "hidden", "closeAfter": true }'

It starts the run the way Run automation does and answers as soon as it has started, with a runId. Follow it at /api/v1/automation/runs/<runId>, which shows each profile as queued, running, success or error. The choices are the same as in the app:

• profileIds — the profiles to run on (required, up to 500).
• concurrency — how many run at once, 1 to 20. Also bounded by your plan's browsers open at once.
• staggerMs — a pause between one profile starting and the next.
• repeats — extra passes over the profiles after the first.
• closeAfter — close each profile when its run ends.
• variables — the workflow's parameters, by name. Given, no form is shown; left out, a workflow with parameters asks for them in a window, or takes its defaults in a hidden or headless run.

The WarpX Browser window itself has to be open, because that is where workflows run. If it is not, the answer is 503 DESKTOP_UNAVAILABLE.

What the key can reach

It never reaches cookies, saved logins, backups or your licence, and it cannot create or edit a workflow's blocks. Your plan's limits apply exactly as they do in the app: a request beyond them answers 402. Requests are capped at 600 a minute.

The full list, with every field, is on the Endpoints card of the Developer API page. Each endpoint has Try it and samples in cURL, Python and Node.js. The same description, as OpenAPI, is at http://127.0.0.1:47110/openapi.json — import it into Postman, Insomnia or a code generator. It needs the key too.

MCP for AI assistants

With MCP, an assistant can list and change your profiles, open and close them, and run workflows when you ask it to in plain words — “open the five profiles in the Shop group and run Daily check-in on them”.

1. On the Developer API page, under MCP for AI assistants, choose your assistant: Claude Code, Cursor, VS Code, Windsurf or Claude Desktop.
2. Choose Copy. Your key is already filled in.
3. Paste it where the page says. For Claude Code it is one command to run in a terminal:

claude mcp add --transport http warpx http://127.0.0.1:47110/mcp \
  --header "Authorization: Bearer wx_..."

For Cursor, the JSON goes in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "warpx": {
      "url": "http://127.0.0.1:47110/mcp",
      "headers": { "Authorization": "Bearer wx_..." }
    }
  }
}

Claude Desktop starts its servers as commands, so it reaches WarpX Browser through mcp-remote and needs Node.js installed; the page gives the exact config. Choose Test connection to check the key works.

What an assistant may do on its own

• It has 18 tools: profiles, groups, proxies, workflows, runs, run logs and schedules.
• Deleting a profile, or more than 10 runs at once, is refused until the assistant asks you and confirms.
• It cannot change a workflow. It can only propose a change, which appears in the open editor and is saved only when you press Save.
• Every call it makes is written to logs/mcp-audit.log in the app's data folder, with passwords and keys masked.

Common answers

• 401 — no key, a wrong key, the API is switched off, or the key was regenerated.
• 403 — the key is good, but the route is not part of the developer API.
• 402 — your plan does not allow it, or a limit was reached (profiles, browsers open at once).
• 409 PROFILE_OPEN — a profile's OS cannot be changed while it is open. Close it first.
• 429 — more than 600 requests in a minute. Wait the seconds in Retry-After.
• 503 DESKTOP_UNAVAILABLE — a workflow run needs the WarpX Browser window open.
• Connection refused — WarpX Browser is not running on this computer.