# Browser reference **Page:** kit/browser/reference [Download Raw Markdown](./kit/browser/reference.md) --- # Browser reference Lookup tables for [Hoody Browser](/kit/browser/). Every route, field and response is in the [API reference](/api/browser/). ## Instances and addresses | Item | Rule | |---|---| | Hostname | `browser-N` selects instance N. Each has its own tabs, cookies and state. | | `browser_id` | Picks the same hostname in the SDK. A value naming another instance than the hostname is `400 INSTANCE_SELECTOR_CONFLICT`; leave it out or give the same `N`. A `?browser_id=` query never changes which instance a request reaches. | | CLI `--browser-id N` | The `browser-N` hostname. `--browser-id 1` reaches the instance the HTTP examples use; `0` is `browser-0`. | | Derived from N | Internal port 30000 + N, display `display-(500 + N)`, DevTools on `cdp-N`. | ## Auto-start Navigation, content, cookie and log routes create the instance with that request's options plus defaults when none is running, unless the server's operator disabled auto-start. | `start` | Effect | |---|---| | omitted | Auto-create (unless disabled) | | `false` | `404` instead of creating | | `true` | Create even when auto-start is disabled | - **Never create one:** `GET /viewport`, `POST /viewport`, `GET /devtools-url`, `GET /shutdown`, `GET /snapshot`, `POST /action` and `POST /wait`. They answer `404` when no instance runs, whatever `start` says, except that `/snapshot`, `/action` and `/wait` answer `409 INSTANCE_CHANGED` if `instanceGeneration` is supplied. - **`/history`:** never creates an instance; it reads stored history whether or not one runs. - **`instanceGeneration`:** `/browse`, `/snapshot`, `/action` and `/wait` check it against the running instance and return `409 INSTANCE_CHANGED` if it differs. On ordinary proxied routes, including those four and `/eval`, supplying it prevents auto-start and returns `409 INSTANCE_CHANGED` when no instance exists, after request validation. Other routes can behave differently: `/viewport` returns `404` when no instance exists. - **`/restart` on an empty address:** omitted `start` creates one (unless disabled), `start=false` is `404 NOT_FOUND`, `start=true` creates one. ## Start options The [instance API](/api/browser/instance-management/) lists every option. Rules it does not spell out: | Option | Rule | |---|---| | `browser` | `chromium` (default) or `firefox`. Firefox runs through Playwright, ignores `stealth` and rejects `useRemoteDebuggingPort=true`. | | `chromiumVersion` | Omitted: the Chrome major of your `userAgent`, otherwise the build supplied with the computer from its last successful update, which may lag the newest stable; with none supplied, the current stable Chrome for Testing build. A full version (`136.0.7103.113`) or a channel (`stable`, `beta`, `dev`, `canary`; `stable` resolves the newest stable at start) is used as given and downloaded on first use; any other value, or a full version no source has, is `400 VALIDATION_ERROR`. A bare major is looked up in the server's version map, then Chrome for Testing; if neither resolves it is treated as omitted without an error, so check `browserFullVersion` in the metadata. The call waits for the download. | | `fingerprintId` | Names a profile file `.json` in the server's fingerprints directory: 1-64 letters, digits, `-` or `_`. An empty `fingerprintId` selects `default`; any other value outside this pattern is `400 VALIDATION_ERROR`. An unknown id starts with an empty profile, without an error. | | `stealth` | Patchright patches signals such as `navigator.webdriver`. A request, not a guarantee: if Patchright cannot load, the instance falls back to plain Playwright with a warning in the server log, and `/metadata` reports `engine: "playwright"`. | | `launchArguments` | Repeat the key or pass one JSON array. On Chromium each entry must be a switch (`--name` or `--name=value`); a positional URL or path and `--app` are refused unless the server runs with `--allow-file-urls`. A fingerprint profile's own `launchArguments` follow the same rule, and launch settings in its `context` (such as `args`) are ignored. | | `locale`, `timezoneId` | A BCP 47 tag or IANA zone. Empty strings count as unset; other invalid values return `400 VALIDATION_ERROR` naming the option, before launch. | | `geolocation` | A JSON object with both `latitude` and `longitude`, and an `accuracy` in meters of 0 or more when given. The query `geolocation=null` is `400`; `null` in a JSON body counts as omitted. `userProfile.geolocation` gets the same checks. | | `viewport`, `noViewport` | JSON size with optional `deviceScaleFactor`; the `default` profile gives 1920x1080. `noViewport=true` or `viewport=null` follows the real window. Combining `noViewport=true` with a fixed viewport is `400`; combining it with `viewport=null` is allowed. `userProfile.deviceProfile.viewport` gets the same checks as `viewport`. | | Precedence | Top-level option, then `userProfile`, then the fingerprint profile, then the browser default. `/metadata` reports the locale and timezone in effect. The `default` profile sets `en-US` and `UTC`. When no level sets them (for example an unknown `fingerprintId`), it reports the host's values. | | `proxyServer` | `http://`, `https://`, `socks5://` or `socks5h://`, with `proxyUsername`, `proxyPassword`, `proxyBypass`. The browser cannot authenticate to a SOCKS proxy: `proxyUsername` or `proxyPassword` with a `socks4://` or `socks5://` proxy (and `socks5h://` on Firefox) is `400 VALIDATION_ERROR`. | | `enableQuic`, `enableDnsOverHttps`, `dnsOverHttpsUrl` | QUIC off; DNS-over-HTTPS on, resolver Cloudflare by default, any HTTPS resolver accepted. | | `useRemoteDebuggingPort` | Default `true`, fills in `webSocketDebuggerUrl` (`null` on Firefox or when off). The kit picks the port; `remoteDebuggingPort` is ignored. | | `remoteDebuggingAddress` | Default `0.0.0.0`. Connect through the URLs `/devtools-url` returns. | | `showBrowser` | Default `true` (headful). `false` is headless, which `/pdf` requires. | | `display` | On `browser-N` the proxy sets the `display` query parameter to 500 + N (`browser-1` shows on `display-501`), replacing any caller query value. A `display` in a JSON body naming another display returns `400 INSTANCE_SELECTOR_CONFLICT`. Headful with no display from the route or `DISPLAY` is a validation error. | | `extensions`, `extensionsDir`, `extensionsStoreIds` | Chromium only, need `showBrowser=true`. Headless, a missing directory, an `extensionsDir` that is not a directory, or a Web Store ID that is not 32 letters from `a` to `p` or that the store does not offer is `400 VALIDATION_ERROR` naming the option, not retried. Headless and malformed IDs are refused before any browser or extension download. | | `firefoxExecutablePath` | A file that does not exist on the server is `400 VALIDATION_ERROR`, not retried. | ### Option size - One instance's options are capped at 96 KiB (`400 VALIDATION_ERROR`). - The whole request head, request line and every header including those the proxy adds, may be 16 KiB (16,384 bytes). Above that the answer is a bare `431 Request Header Fields Too Large` with no JSON body and no CORS headers, so a browser page sees a network error. - `/start` and `/restart` take only query parameters. For a larger option set, send it in the JSON body of the `POST /browse`, `POST /eval` or `POST /cookies` that creates the instance. ## Lifecycle | Situation | Result | |---|---| | `/start` on a running instance | Returns its metadata and applies no new options only when the requested backend matches. Otherwise returns `409 INSTANCE_BACKEND_MISMATCH`; omitted `stealth` defaults to `true`. Malformed options still return `400`, but launch-time checks such as full version validation do not run. | | `/restart` engine change | Cannot switch between stealth and plain Playwright: `409 INSTANCE_BACKEND_MISMATCH`, instance left as it was. `browser=firefox` counts as a switch for a default instance, even with `stealth=false`. To move to Firefox, `/stop` then `/start?browser=firefox`. | | `/restart` inherited options | An instance started with `chromiumVersion=136` restarts on 136 unless the request says otherwise. | | `/stop`, `/shutdown` on an empty address | `404 NOT_FOUND`; neither starts an instance. | | `/shutdown` | Answers `200 {"message":"Shutting down"}` once shutdown starts. From then `/metadata?start=false` answers `404`, which does not mean the process has exited. The browser gets 10 seconds to close before it is killed. Use `/stop` to wait for teardown. | | Browsing history | Kept on disk, 30 days by default; survives restarts. | ### Idle stop An instance becomes eligible after the server's idle timeout (`--instance-max-age`, one hour by default) and is stopped at the next cleanup check (`--cleanup-interval`, five minutes by default); several idle together can stop a little later. Use means API requests to it until they finish, CDP traffic or an open CDP WebSocket, and page navigations, a person on the display included. Merely running is not use, nor are the health check, `/metrics`, `/history` or the status page's refresh. Stopping discards tabs, cookies and storage. ### Start failures | Answer | Cause | |---|---| | `504 TIMEOUT`, `details.phase` `launch`, `details.outcome` `unknown` | The launch outlasted `--request-timeout`. It carries on: check `/metadata?start=false` before retrying. An auto-starting request that timed out this way was not run. | | `504 TIMEOUT`, `details.phase` `server`, `details.outcome` `unknown` | Work the server does itself outlasted `--request-timeout`, such as a `/stop` waiting for a start of the same instance or a long `/history` read or delete. The work is not cancelled and may still complete. | | `408 TIMEOUT` | `--request-timeout` ran out while the request body was still arriving. Once the instance has the request, the operation's own deadline applies. | | `500 BROWSER_LAUNCH_ERROR` | The launch did not finish within 180 seconds. | | `503 INSTALL_IN_PROGRESS`, `Retry-After: 30` | Still waiting after about 5 minutes on another process's Chrome, Firefox or extension install; retry after the `Retry-After` delay. Any starting request, CDP included; the landing page `/` keeps its HTML body. | | `503 DISPLAY_UNAVAILABLE`, `Retry-After` | Headful start with no display. Not retried; start with `showBrowser=false`, or retry once the display runs. | | `409 PORT_IN_USE` | Another process listens on `browser_port`; the message names host and port. Not retried: stop that process or use another instance number. | ## Navigation | Item | Rule | |---|---| | Response | `tabId`, `url`, `requestedUrl` (before redirects), `title`, `httpStatus`, `created`, `reused`, `elapsedMs`. | | Redaction | Both URLs lose credentials and the value of query or fragment parameters whose name looks secret (`token`, `code`, `state`). A secret under an unrelated name is not redacted. | | `waitUntil` | `commit`, `domcontentloaded` or `load` (default). `networkidle` is not offered. | | `timeoutMs` | Up to 30000. Omitted, the navigation may take up to 30 seconds; given, the whole budget is yours. Either way, running out is `504 TIMEOUT`, `details.phase` `navigation`. | | Other proxied routes | With no deadline of their own, bounded by the same server timeout: `504 TIMEOUT`. | | Site errors | A site's own 404 arrives as `httpStatus: 404` in a `200`. | | Failure | DNS or refused connection: `502 NAVIGATION_ERROR`. A file download: `422 NAVIGATION_IS_DOWNLOAD`, also on `/screenshot`, `/pdf`, `/markdown` with `url`. A download started by a click is dropped silently. | | `onlyIfNotExists` | Matches URL spellings the parser treats as equal: a slash after a bare host (`https://example.com` and `https://example.com/`), case of scheme or host, a default port. A slash at the end of a longer path makes a different URL (`/article` is not `/article/`). | | `tabId` | Accepted by `/browse`, `/eval`, `/html`, `/text`, `/markdown`, `/pdf`, `/screenshot`. Not open: `404 TAB_NOT_FOUND` listing open tabs, with no fallback. Malformed: `400`. Without one, `/browse` opens a new tab (unless `onlyIfNotExists` reuses a tab already on the URL) and the others use the active tab. | | With `url` | `/screenshot`, `/pdf`, `/markdown` wait at most 30 seconds: slower is `504 TIMEOUT`, unreachable `502 NAVIGATION_ERROR`. | ## URLs and local files - **Accepted:** absolute `http`, `https`, `data`, `about:blank`, and `chrome:` on Chromium. The same rule covers `/browse`, `/screenshot?url=`, `/pdf?url=` and `/markdown?url=`. - **Refused with `400 VALIDATION_ERROR`:** `file:` in any spelling, `view-source:`, `javascript:`, `blob:`, every other `about:` page (Firefox's `about:reader?url=file:…` loads a local file), `chrome:` on Firefox, a value that is not an absolute URL or not a string, and an empty `url=` on `/screenshot`, `/pdf`, `/markdown` (omit it for the current tab). Messages: `url must be an http, https or data URL, about:blank, or a chrome URL on Chromium; file and other local schemes are refused` and `url must be an absolute URL, like https://example.com/`. - **Checked first:** before an instance starts, before the tab lookup (`/screenshot?tabId=99999&url=file:///etc/hostname` is `400`, not `404`) and before `/pdf`'s `501`. - **Cookies:** `POST /cookies` entries need `http` or `https` URLs; `GET /cookies?url=` needs only an absolute URL, since it filters. - **In the browser:** a tab cannot open `file:` through `/eval` (`location.href = 'file:///…'`, `window.open`), a CDP client (`Page.navigate`, `Target.createTarget`) or the live view's address bar. Chromium shows `net::ERR_BLOCKED_BY_CLIENT`, `view-source:` of a file included. Firefox blocks it by policy (`NS_ERROR_BLOCKED_BY_POLICY`) and keeps the address. Firefox cannot block `jar:file:` typed by a person in the live view; pages and the API cannot open it. - **`--allow-file-urls`:** a server option, off by default, that lifts both blocks for `file:` only. No request can turn it on, and with it on any client that can drive the browser can read local files. ## Markdown The [interaction API](/api/browser/interaction/) lists the options and limits. | Item | Rule | |---|---| | Response | `markdown`, `title`, `url`, `httpStatus` (`null` without `url`), `fetchedAt`, `truncated`, `chars`, `metadata` (`description`, `author`, `site`, `published`, `language`, `wordCount`); `url` and `title` redacted like `/browse`. | | `maxChars` | Cuts at the last line break, or at the limit when there is none, never splitting a UTF-16 surrogate pair. | | Links | Relative targets are resolved against the page and its ``. A target with a secret-named query keeps its path and loses the query (`https://example.org/cb?***`); one with credentials is removed. `style` attributes, `title` tooltips, CSS and SVG URL attributes and SVG link targets other than a plain id (`#icon`) are removed. Nothing is fetched while converting. Use `/html` for the raw HTML with original URLs. | | `PAGE_TOO_LARGE` | HTML length counts UTF-16 code units, so an emoji counts as two or more. A long `` with many relative links can hit the references limit. `details.limit` names `html`, `elements`, `depth`, `references` or `tableArea`, with `value` and `max`. | | `422 CONVERSION_FAILED` | The converter cannot handle the page. | | Time | A large article takes several seconds, off the main thread, so other tabs keep answering. Including a start, clients wait up to 740 seconds by default. | ## Screenshots and PDF The [interaction API](/api/browser/interaction/) has every parameter. - Background tabs can be captured too. - `mask` colour is `maskColor`, an opaque hex colour. - A `mask` or `hide` matching nothing covers nothing and still succeeds. - `scale=css` gives one image pixel per CSS pixel. - `/pdf` `format`: Letter, Legal, Tabloid, Ledger or A0 to A6. ## JavaScript | Item | Rule | |---|---| | World | `stealth=false`: the page's main world, so page globals and anything the page changed on the JavaScript layer (a shadowed `document.title`, an expando on a node, a replaced DOM method) are visible. Default `stealth=true` (Patchright): an isolated world sharing only the DOM. `/html` and `/text` read the DOM either way. | | No value | `{}` | | `422 EVAL_ERROR` | The script threw, or its promise rejected. `details.name` and `details.message` (cut at 1000 characters); `error` reads `Script error: : `. `details.name` is best effort: Chromium takes it from the stack, Firefox gives only the message. | | `422 RESULT_NOT_SERIALIZABLE` | A BigInt or circular object. | | Timeout | `timeoutMs` 1 to 30000, query or body. After it, `504 TIMEOUT` and the browser tries to stop the script. Chromium keeps the tab (`details.terminated: true` when stopped); Firefox closes the tab (`details.tabClosed: true`). `details.terminated: false`: the script could not be confirmed stopped and the tab may stay busy; close it if needed. `details.started: false`: the page stayed busy and the script never ran. Also stopped when the caller disconnects. | | Missing `script` | `400 VALIDATION_ERROR` (`Missing required parameter: script`), like a missing `url` on `/browse`. | ## Agent actions The [interaction API](/api/browser/interaction/) has every field. | Item | Rule | |---|---| | `/snapshot` | YAML accessibility tree with `[ref=...]` handles, `snapshotId`, `url`, `title`, `truncated`, `chars`. `maxChars` 30000 by default, at most 200000, cut on a line boundary. | | Actions | `click`, `fill`, `type`, `press`, `select`, `check`, `hover`. `fill` and `type` carry `value`, `press` `key`, `select` `values`, `check` `checked`. | | `/wait` kinds | `target`, `text`, `url`, `loadState`. Never true: `504 TIMEOUT`, not `matched: false`. | | Targets | `exact` defaults to `true`. `409 AMBIGUOUS_TARGET` lists up to five candidates when they can be read in time; a candidate's name never includes typed text. Semantic and CSS targets reach the top document; use a `ref` inside an iframe. | | Hidden values | Textbox, searchbox, spinbutton, slider and `contenteditable` contents show `