API Documentation — Privogrid

🔑

1. Enable it in the app

Open API & MCP in the app's sidebar and click Create API key. Give the key a name, choose its permissions (read, control, automation, admin), optionally limit it to certain profiles or folders, set a per-minute rate limit and an expiry. Copy the key — it is shown once and stored hashed (SHA-256).

🖥️

2. It listens locally only

The server binds to http://127.0.0.1:47800 while the app is running. Nothing about it goes over the internet: no cloud relay, no public endpoint. Authenticate with Authorization: Bearer <key> or X-API-Key: <key>.

🎭

3. Playwright, Puppeteer, Selenium

Launch a profile through the API with a key that has the automation permission and the response includes the profile's CDP endpoint. Connect your existing scripts to it (chromium.connectOverCDP, puppeteer.connect, Selenium's debugger address) — the profile keeps its fingerprint, proxy and cookies.

🤖

4. MCP for AI agents

The same server speaks MCP (JSON-RPC over HTTP, protocol 2025-03-26) at POST /mcp, with 15 tools. Point any MCP client that supports the HTTP transport at it, with the API key as bearer token, and the agent can list, launch, navigate, click, type, read and screenshot profiles, and run your RPA processes.

# List your profiles (key with the read permission)
curl http://127.0.0.1:47800/v1/profiles \
  -H "Authorization: Bearer <your key>"

# Create one (control permission)
curl -X POST http://127.0.0.1:47800/v1/profiles \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"name":"shop-eu-01","proxy":"socks5://user:[email protected]:1080"}'

# Launch it (automation permission returns the CDP endpoint for Playwright/Puppeteer/Selenium)
curl -X POST http://127.0.0.1:47800/v1/profiles/<id>/launch -H "Authorization: Bearer <your key>"
→ 200 # { "ok": true, "port": 9xxx, "cdp": "http://127.0.0.1:9xxx", ... }

REST routes (all under http://127.0.0.1:47800)

GET /help	Endpoint list and the MCP tool names (needs a key)
GET /v1/profiles	List profiles and their running state
POST /v1/profiles	Create a profile (name, optional proxy, tag, notes)
DELETE /v1/profiles/:id	Delete a profile and its data (admin permission)
POST /v1/profiles/:id/launch · /stop · /restart	Start, stop or restart a profile
POST /v1/browser/:id/navigate · /click · /type · /read · /screenshot	Drive a running profile without your own CDP client
GET /v1/rpa/processes · POST /v1/rpa/run	List and run your RPA processes on chosen profiles
GET /v1/synchronizer/status · POST /v1/synchronizer/stop	Window Synchronizer status and emergency stop
POST /mcp	MCP endpoint — 15 tools: list / create / delete / launch / stop / restart profile, open URL, click, type, read page, screenshot, list & run RPA processes, synchronizer status & stop

Rate limit per plan: Solo 300, Pro 600, Agency 900 requests per minute (a safety brake, not a meter; you can set a lower limit on any key). A blocked tool or an out-of-scope profile returns 403. Every call — including refused ones — is written to the audit log on the API & MCP page. Free-plan accounts cannot use the API (403).

Hosted cloud API — planned

Everything above runs on your machine. A hosted API at api.privogrid.com — manage profiles, fingerprints and team members without the app running — is planned but not available yet. Tell us your use case and we will let you know when it opens.

[email protected]