Documentation menu · Local API reference

Documentation

Local API reference

Everything the MCP connector and the Python client do goes through one JSON-RPC endpoint on your PC. You can call it directly from any language.

Basics

  • Wisp listens on 127.0.0.1, default port 9777 (if it is taken, the next free port up to 9797).
  • Port, token and URL are written to %APPDATA%\Wisp\api.json while Wisp runs. The token itself is kept in api-token in the same folder.
  • Every call needs Authorization: Bearer <token>. Requests with an Origin header (that is, from web pages) and requests to any host name other than 127.0.0.1 or localhost are refused.
  • GET /health answers without a token: {"name":"Wisp","ok":true}.
  • Responses are {"result": ...} or {"error": "..."}.
HTTP
POST http://127.0.0.1:9777/rpc
Authorization: Bearer <token>
Content-Type: application/json

{"method": "tabs.new", "params": {"url": "https://example.com"}}
PowerShell
$info = Get-Content "$env:APPDATA\Wisp\api.json" | ConvertFrom-Json
$body = @{ method = "tabs.new"; params = @{ url = "https://example.com" } } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $info.url -Headers @{ Authorization = "Bearer $($info.token)" } -ContentType "application/json" -Body $body

Methods

App and profiles

MethodParameters and result
statusName, version, Chromium and Electron versions, window visibility, ad blocker state, tab count, current profile, graphics mode, data folder.
profiles.listAll profiles with name, id, whether current, and tab count.
profiles.addname. Creates a profile.
profiles.removename. Closes its tabs and deletes its logins and site data. The first profile cannot be removed.
profiles.switchname. Shows that profile’s tabs.
app.quitQuits Wisp.

Tabs

MethodParameters and result
tabs.listAll tabs: tab, url, title, loading, active, agent, asleep, profile.
tabs.newurl, profile, activate (default false), muted, wait (default true), timeout. Opens a background tab marked as an agent tab and waits for it to load.
tabs.closetab.
tabs.activatetab. Makes it the visible tab.
tabs.sleeptab. Unloads the page to free memory.
MethodParameters and result
navigateurl (an address or a search phrase), tab (optional: defaults to the tab an agent used last, then the active tab), wait, timeout.
back / forward / reloadtab (optional: defaults to the tab an agent used last, then the active tab)

Reading

MethodParameters and result
texttab (optional: defaults to the tab an agent used last, then the active tab), selector, max_chars (default 50,000). Visible text, main content first.
htmltab (optional: defaults to the tab an agent used last, then the active tab), selector, max_chars (default 200,000).
snapshottab (optional: defaults to the tab an agent used last, then the active tab), viewport_only, max (default 400). Interactive elements with ref, role, name, and value, checked, href, disabled where relevant. Password field values are never included.
screenshottab (optional: defaults to the tab an agent used last, then the active tab), full_page, format (png or jpeg), quality, path. Returns base64, or saves to path. Works while Wisp is in the background.
dialogstab (optional: defaults to the tab an agent used last, then the active tab). JavaScript alerts and confirms the page showed (they are accepted automatically once DevTools Protocol is attached).

Acting

MethodParameters and result
clicktab (optional: defaults to the tab an agent used last, then the active tab), and one of ref, selector, text, or x/y.
typetext, tab (optional: defaults to the tab an agent used last, then the active tab), ref or selector (omit both for the focused element), clear (default true), submit.
keykey, e.g. Enter, Escape, Tab, ArrowDown, PageDown, ctrl+a. tab (optional: defaults to the tab an agent used last, then the active tab).
scrolltab (optional: defaults to the tab an agent used last, then the active tab), dy (default most of a screen), dx.
waittab (optional: defaults to the tab an agent used last, then the active tab), and selector, text or ms; timeout (default 15 s).
evalcode, tab (optional: defaults to the tab an agent used last, then the active tab), timeout. Runs JavaScript in the page; promises are awaited.
cdpmethod, params, tab (optional: defaults to the tab an agent used last, then the active tab). Raw Chrome DevTools Protocol.

Window and UI

MethodParameters and result
window.show / window.hideShow the window, or move it out of sight (Wisp keeps running).
window.screenshotCapture Wisp’s own UI to a PNG, for diagnostics.
ui.eval / ui.keyRun script in, or send a key to, the browser’s own UI (used for testing).

Sleeping tabs

Tabs can be asleep ("asleep": true in tabs.list): restored tabs and tabs unloaded by the memory saver. Any page method on a sleeping tab wakes it and waits for it to load. Tabs an agent used recently are not put to sleep by the memory saver.

Limits

  • snapshot covers the main document and open shadow roots, not cross-origin iframes (use cdp or eval for those).
  • The API cannot send input events to a tab while DevTools is open on it; clicks fall back to scripted clicks.
  • Saved passwords are not reachable through the API, and Wisp will not fill a password into a tab an agent drove in the last few seconds.

MCP tool names

The MCP connector maps its tools onto these methods: wisp_tabs → tabs.list, wisp_open → tabs.new, wisp_read → text, wisp_navigate → navigate, and so on. See the tool list.