Local API, keys and webhooks

The local API is a small web server inside the desktop app. Your own programs on the same machine call it over loopback and get an answer.

Everything it works with is on your disk: profiles, cookies, the engine and the proxy bridge. With the network down your scripts keep calling, and the app works offline for 24 hours.

• Drive profiles from your own code

  List, create, start, stop and delete them without touching the window.

• Attach Puppeteer, Playwright or Selenium

  You get back the debugging endpoint for that exact profile.

• Run saved flows from outside

  Your own scheduler or build server can start a flow over named profiles.

• Let an AI client act

  Through the bundled MCP server an AI client takes these same routes, and the API has to be on.

The API is off until you turn it on, because enabling it opens a port. On first run the app writes itself a random token, 24 bytes shown as 48 characters, into a file only your account can read.

You can send the token three ways: as a parameter in the address, as a header, or as a bearer credential. Regenerate it and every script carrying the old one stops, so the app asks you to confirm.

1. 1

   Open the For developers screen

   It shows the switch, the address, the token and the list of routes.

2. 2

   Click Enable local API

   You should see Running, and if the usual port was busy the panel names the one it took.

3. 3

   Copy the address and the token

   The panel offers a ready command line with your own token already in it.

4. 4

   Point your script at it

   Every call you make except the status route carries the token, and a wrong one gets you 401.

Binding to loopback sounds like a boundary. It is not one: the pages you visit run on this same computer, so they can reach that address as well.

So a page in your browser cannot reach it: the app recognises a call like that and refuses. A domain name pointed at loopback does not help either: it arrives under its own name and is turned away.

An answer carries three fields: a code, the payload and a message. The code is 0 on success, and on a refusal you get the reason. The one exception is the call asking whether the API is up: it answers in a short form of its own, without the payload and message fields.

Branch on the code in the envelope rather than on the HTTP status: the status carries refusals at the door, while a refusal on the merits comes back as 200 with a non zero code. A body over a megabyte is not trimmed: it gets 413 with payload_too_large, and loading cookies, a one-time profile and import take up to 16 MB.

You can pass the profile id in the body or in the query string: both examples below use the query string, and neither has to be rewritten. Ask for a run without a window, or send nothing and the profile's own setting decides.

What comes back depends on the engine. On the ARMANOS Browser each profile gets its own debugging endpoint, isolated from every other profile.

• ARMANOS Browser engine

  A port and a socket address for this profile only. Attach your automation library straight to it.

• Built-in engine

  One shared port for the whole app, named in the answer with a warning that it is shared.

• Neither available

  You get an answer saying no endpoint is open and why, rather than an empty field.

The API is not a side door. A profile you create by call goes through the same licence and quota check as one created by the button, and without a licence neither of them starts.

Run a flow and you get back the ids the app does not know, and if it takes no profile into work at all, that is a refusal rather than a success.

The token above drives one installation on one computer. A server key is a different thing: it talks to our server from anywhere, and it never opens a browser window.

You see a key once, at creation, and we keep only enough of it to tell your keys apart. Keys belong to the paid plans, you may hold 20 live ones, and a change of plan reaches a key within a minute.

A webhook is our server calling yours when something happens in your workspace. Subscriptions are created by a person signed in with a password, never by a key, and a new one asks for the password again, and for the two-step code if it is on. You may keep up to ten.

Each call is signed, and fields whose names look like a credential never reach your receiver. An invite code or a password reset link never leaves for a third party server.

• Profiles

  profile.create, profile.update, profile.delete, profile.start, profile.stop, profile.transfer.accept

• Proxies

  proxy.create, proxy.update, proxy.delete

• Keys

  apikey.create, apikey.revoke

• Team

  team.invite, team.remove

• Money

  plan.change

Delivery is honest about failure: three attempts, retried on a server error, on a too many requests refusal and when no answer came at all, and you see the last status on the subscription itself. After fifteen failures in a row the subscription switches itself off.