# Anti-detect browser REST API > Mosaic's anti-detect browser REST API runs on 127.0.0.1 with API keys. Create and start profiles, then attach Puppeteer or Playwright over CDP. Source: https://mosaicbrowser.com/features/rest-api ## Anti-detect browser REST API: profiles from your scripts Mosaic's anti-detect browser REST API runs on 127.0.0.1 with API keys. Create and start profiles, then attach Puppeteer or Playwright over CDP. Mosaic is a desktop app Email yourself the link and open it on your computer. ![Driving a Mosaic profile from Playwright: start it over the local API and attach to its DevTools socket](https://mosaicbrowser.com/shots/api-automation.png) *The API screen’s Automation tab: start a profile over the local API and attach Playwright to it.* Mosaic's anti-detect browser REST API runs on your own computer, at `http://127.0.0.1:7317/api/v1` by default. You make a key on the API screen, send it as `Authorization: Bearer `, and every route answers in JSON. As of 2 November 2026 the reference documents 181 routes, and starting a profile hands back a DevTools endpoint, so Puppeteer and Playwright can attach to a browser that already wears its fingerprint, proxy and cookies. The rule behind it is that the interface, the API and the [MCP server](https://mosaicbrowser.com/features/mcp-server) are peers. Anything the window can do, a script can do, through the same code. When we first measured that, there were 175 REST routes against 122 MCP tools and whole areas missing from one side, so the build now runs a check that maps every route to the tool that does the same job. ## The shortest useful call An empty body is a valid `POST /profiles`. Leave everything out and you get a profile in the system project with a freshly drawn fingerprint. Add a proxy as a plain string and it is attached to that profile alone, without filling the Proxies page with one row per session: ``` curl -X POST -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \ -d '{"name":"Scrape","proxy":"socks5://user:pass@gw.provider.com:1080"}' \ "$BASE/profiles" ``` A profile created with a proxy is drawn for that proxy's exit. Mosaic measures where the proxy really comes out before it generates the identity, and the timezone, languages and geolocation follow that address. Every response carries an `exitMatch` object saying whether a measured exit decided the locale, and why not if it did not. Before that field existed, the same pasted European gateway gave `America/New_York` on one call and `America/Chicago` on the next, and the two responses looked identical. Pass `count` (1 to 500) to create a batch in one call. ![The Mosaic API screen: a local REST API key and the MCP server address](https://mosaicbrowser.com/shots/api-keys.png) *The API screen: keys, the base URL, and the in-app reference.* Mosaic is a desktop app Email yourself the link and open it on your computer. [How it works: REST API](https://mosaicbrowser.com/features/rest-api) ## Starting a profile and attaching Playwright `POST /profiles/:id/start` launches the browser and returns `{ profileId, status, pid, debugPort, wsEndpoint, cdpUrl, startedAt, error }`. Connect to `wsEndpoint` with `puppeteer.connect` or Playwright's `chromium.connectOverCDP`, and you are driving Tesseract Chrome, Mosaic's own engine, with the profile already applied. Two details save time. A profile with a proxy is not started until that proxy has answered and tunnelled a connection; if it has not, the call returns a `502` that names the proxy and quotes what it said, and no browser opens. And for work nobody will watch, pass `"offscreen": true`. The window is parked off the screen but the browser stays headed, so it keeps the real User-Agent and the real GPU. A headless Chrome names itself in its User-Agent, which is why we treat headless as the wrong tool for anything a site will see. If you would rather not use Playwright at all, the page-control routes read the page as an accessibility tree with refs, and click and type through Mosaic's human-input code. They never enable the DevTools `Runtime` domain, which we measured flipping a bot detector's verdict. ## Errors written for the caller A misspelled field and a stored one look the same from outside, so an unknown key is a `400` that names the field. A value out of range is refused, never clamped: `"count": 9000` is an error, not a quiet batch of 500. A `4xx` message is written for whoever sent the request. A `500` means the bug is ours. Destructive routes work the other way round from a PATCH. An absent field on an edit leaves the value alone; an absent scope on something irreversible, such as emptying the trash, is a `400`, never "all of it". We learned that one the hard way, and it is now enforced at every door. ## What the anti-detect browser REST API covers The groups in the reference are the groups in the app: profiles, running a profile, fingerprints, proxy providers, proxies, credentials, cookies, bookmarks, warm-up, human typing, projects and tags, downloads, trash, backups, import and export, extensions and presets, tabs and page control. Bulk routes take lists of ids. Starting or stopping a batch answers `{ ok, skipped, failures }`, with a reason for each profile that failed, because "started 40" over eight failures is not an answer. The full reference is inside the app on the API screen, and the same text can be saved as Markdown. `GET /health` is the one route that needs no key, so a supervisor can check that Mosaic is up without holding a credential. ## Limits The API binds `127.0.0.1` only. It is a desktop app with a local API, not a server you deploy, so there is no Docker image, no cloud endpoint and nothing to reach from another machine. The REST API is part of Pro: $49 a month, one plan, with a 14-day free trial. Free has no API access. Pro does not charge per profile, so a script that makes 500 profiles costs the same as one that makes five. Each proxy still needs to work before a launch, as [checking a proxy before you use it](https://mosaicbrowser.com/guides/how-to-check-a-proxy-before-you-use-it) explains, and [provider accounts](https://mosaicbrowser.com/features/proxy-providers) give each profile in a batch its own exit. ## Questions ### Can Puppeteer or Playwright drive a Mosaic profile? Yes. Starting a profile returns a wsEndpoint. Puppeteer connects with puppeteer.connect and Playwright with chromium.connectOverCDP, and the browser they attach to already has the profile's fingerprint, proxy and cookies. ### Is the REST API on the Free plan? No. The REST API and the MCP server need Pro. Free has every browser feature but no automation surface. ### Can I call the API from another machine or a server? No. It binds 127.0.0.1 only, so scripts run on the same computer as Mosaic. There is no cloud endpoint or Docker image. ## The smaller things it does ### Peers, not a subset The window, the REST API and MCP are kept level: anything one can do, the others can. ### The reference in the app Every route is documented inside Mosaic, and the docs download as Markdown. The API listens on your own computer only. There is no hosted or headless server version. ## Works with ### An AI assistant can make, start and drive your profiles Let an AI assistant create, launch and drive profiles. ### Make 500 profiles in one go, then work on all of them at once 500 profiles per batch; start, edit and type into many. ### Paste one gateway line. Every profile mints its own exit. One gateway line, a separate exit for every profile. [All 29 features](https://mosaicbrowser.com/features) ## REST API is part of Pro Try Pro free for 14 days, then $49 a month for any number of profiles. Cancel before day 14 and you pay nothing. Mosaic is a desktop app Email yourself the link and open it on your computer.