Bookmarks API for Scripting and AI

An API add-on for Firefox so agents and scripts can manage your bookmarks while the browser is open.

Repo: git.easygoingaming.com/Davoguha/bookmarks-api

The shipped product is the add-on in extension/. This is not a bookmark sync engine, and it is not a Mozilla product.

Who can use this

The HTTP API listens on 127.0.0.1 only — the same computer that is running this Firefox. A local script, an editor agent, or a session you have opened on that machine (SSH, remote desktop) can call it, if it presents a secret you issued.

It does not work from chatgpt.com or other sites in a browser tab. Those programs run somewhere else and cannot see this port. Pages open in Firefox are also blocked (requests that carry a browser Origin are rejected).

You can sit at a different computer and still use it if your tooling is actually running on the Firefox machine — for example you SSH in and run the client there. Pointing a remote tool at some other host’s loopback will not work.

If this Firefox profile syncs bookmarks with a Mozilla account, edits made here can appear on your other devices. Sync is Firefox’s feature; the API itself still only accepts connections on this machine.

The listen port defaults to 17634. Change it under Manage clients if that port is already taken, and point your tools at the same port (FAB_URL).

What it does

Scripts and local agents call a loopback HTTP API. The add-on performs only browser.bookmarks operations (create, search, move, delete, and related reads). It does not read tabs, history, cookies, or the open web.

Load the add-on.
Toolbar → Manage clients → generate a secret → store that secret yourself.
Register the native host once if scripts should call in (tools/install-native-host.ps1 on Windows).
Keep Firefox open. Call http://127.0.0.1:<port> (default 17634) with Authorization: Bearer <secret>.

POST /v1/call
Authorization: Bearer fab_…
Content-Type: application/json

{"method": "bookmarks.search", "args": [{"title": "Research"}]}

set FAB_TOKEN=fab_…
python tools/client.py meta.methods
python tools/client.py bookmarks.search "[{\"title\":\"Research\"}]"

Method list and failure modes: AGENTS.md. Signing for Firefox Release: docs/signing.md.

Permissions

Permission	Why
`bookmarks`	The only WebExtension API this add-on calls
`storage`	SHA-256 hashes of issued client secrets
`nativeMessaging`	The only inbound path from local scripts (Mozilla does not allow a raw listening socket in the extension)

It does not request tabs, history, cookies, <all_urls>, webRequest, or runtime.onMessageExternal.

Security

HTTP binds 127.0.0.1 only. Requests with a browser Origin header are rejected.
The native host may talk only to this add-on’s gecko id.
The add-on stores hashes, not secrets. Revoke from Manage clients.
Both the host and the add-on allowlist the same meta.* / bookmarks.* methods.

See PRIVACY.md and SECURITY.md.

What this is not

Not bidirectional bookmark sync
Not a general Firefox remote-control surface
Not a reason to edit places.sqlite while Firefox is running

3.4 KiB Raw Blame History Unescape Escape