Browser reference
Section titled “Browser reference”Lookup tables for Hoody Browser. Every route, field and response is in the API reference.
Instances and addresses
Section titled “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
Section titled “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 /actionandPOST /wait. They answer404when no instance runs, whateverstartsays, except that/snapshot,/actionand/waitanswer409 INSTANCE_CHANGEDifinstanceGenerationis supplied. /history: never creates an instance; it reads stored history whether or not one runs.instanceGeneration:/browse,/snapshot,/actionand/waitcheck it against the running instance and return409 INSTANCE_CHANGEDif it differs. On ordinary proxied routes, including those four and/eval, supplying it prevents auto-start and returns409 INSTANCE_CHANGEDwhen no instance exists, after request validation. Other routes can behave differently:/viewportreturns404when no instance exists./restarton an empty address: omittedstartcreates one (unless disabled),start=falseis404 NOT_FOUND,start=truecreates one.
Start options
Section titled “Start options”The instance API 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 <id>.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
Section titled “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 Largewith no JSON body and no CORS headers, so a browser page sees a network error. /startand/restarttake only query parameters. For a larger option set, send it in the JSON body of thePOST /browse,POST /evalorPOST /cookiesthat creates the instance.
Lifecycle
Section titled “Lifecycle”Idle stop
Section titled “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
Section titled “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
Section titled “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
Section titled “URLs and local files”- Accepted: absolute
http,https,data,about:blank, andchrome: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 otherabout:page (Firefox’sabout:reader?url=file:…loads a local file),chrome:on Firefox, a value that is not an absolute URL or not a string, and an emptyurl=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 refusedandurl 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/hostnameis400, not404) and before/pdf’s501. - Cookies:
POST /cookiesentries needhttporhttpsURLs;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 showsnet::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 blockjar: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 forfile:only. No request can turn it on, and with it on any client that can drive the browser can read local files.
Markdown
Section titled “Markdown”The interaction API 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 <base>. 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 <base href> 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
Section titled “Screenshots and PDF”The interaction API has every parameter.
- Background tabs can be captured too.
maskcolour ismaskColor, an opaque hex colour.- A
maskorhidematching nothing covers nothing and still succeeds. scale=cssgives one image pixel per CSS pixel./pdfformat: Letter, Legal, Tabloid, Ledger or A0 to A6.
JavaScript
Section titled “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: <name>: <message>. 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
Section titled “Agent actions”The interaction API 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 <value hidden>; an empty control shows no value. A plain native <select> keeps its option names; other comboboxes are masked. |
| Budget | timeoutMs 10000 by default, 30000 at most. Expiry is 504 TIMEOUT with details.phase; an /action target seen absent is 404 ELEMENT_NOT_FOUND. A /wait timeout reports phase: "wait" without an outcome. |
TAB_BUSY | A second /action, /browse or /snapshot on a busy tab is 409 TAB_BUSY. /wait is never gated. /eval, CDP clients and a person on the display are not gated. |
| Dialogs | The dialog policy covers the first dialog the action raises, if it matches; it never requires one. Others are dismissed and the call is 409 UNEXPECTED_DIALOG, or the action’s own error with details.dialog. An unrelated dialog first uses up the policy. |
details.outcome
Section titled “details.outcome”| Value | Meaning |
|---|---|
not-started | Never reached the page; retry is safe. |
unknown | The action may have taken effect; input dispatch is not confirmed. Snapshot and check before retrying, or it may run twice. |
completed | Finished before the other failure. |
409 STALE_SNAPSHOT with details.reason comes from reusing a ref after a newer snapshot or a top-document navigation (nothing sent), or from a navigation landing while the action waited. A navigation the action itself causes (a link, a form, Enter, a script changing the URL) is its 200 result, with url after the action; the issuing ref is stale afterward.
Tabs, cookies and viewport
Section titled “Tabs, cookies and viewport”- Cookies: each needs
name,valueand either an absoluteurlordomainwithpath. A bad cookie is400 VALIDATION_ERRORnaming the field, such ascookies[1].sameSite. - Close: a malformed
tabIdis400 VALIDATION_ERROR; one that names no open tab is404 TAB_NOT_FOUND. - Viewport: an instance starts with a fixed emulated viewport, so resizing the window does not change the page and the fingerprint stays stable.
GET /viewportreturnsviewport,source,tabs,converged. With no instance, both routes answer404withdetails.reason: "no_instance". - Resize:
POST /viewportwith{"viewport":{"width":1280,"height":800}}. Tabs apply it at the same time, each within 5 seconds; a tab that does not (a page stuck in its own script) is listed indetails.failedTabsof a502 VIEWPORT_APPLY_INCOMPLETE. - Responsive at runtime:
{"viewport":null}works only on Chromium created responsive (/start?noViewport=true). Fixed-created is409 REQUIRES_RESTART; Firefox is501 NOT_SUPPORTED./metadatathen reports"viewport": nullandviewportSource.
Console, network and history
Section titled “Console, network and history”| Item | Rule |
|---|---|
/console | Console lines and uncaught page errors of every tab, including the first load of a tab the page opened, logged objects with their content. On a stealth instance "capture": "partial" with a reason: browser-reported lines only (failed loads, CSP violations), not the page’s console.log, console.info, console.warn and console.error calls, uncaught errors or rejections, so an empty logs proves nothing. Other instances: "capture": "available". |
| Buffers | 500 entries each. dropped counts discarded entries since start or the last clear=true. |
since | ISO 8601, such as 2026-10-05T12:00:00Z. Omitted or empty applies no timestamp filter; other invalid values are 400 VALIDATION_ERROR. |
tabId | Filters one open tab: malformed 400 VALIDATION_ERROR, not open 404 TAB_NOT_FOUND. |
| First load | /network and /history include the first request and page of a tab a page or CDP client opened. |
/history | since, domain, limit, offset. |
| Page loads | Every page load is an entry of its own, whoever started it: a link, a form, a script redirect, back or forward to another document. A tab that loads more than 10 pages within any one second (a redirect loop) has the excess not recorded. |
| Same-document changes | URL changes a page makes without loading a new document (History API updates, hash changes) are written at most once a second per tab; of those inside one second only the newest is kept. Such changes on one site less than a second apart (for a data: page, one document), with no change to another site in between, are one entry with the newest URL and title and the time of the first change, for at most 60 seconds. Stored url and requestedUrl are cut to 8192 characters. |
DELETE /history | Also covers same-document changes made before it that were not yet written: they are not recorded afterwards. |
DevTools Protocol
Section titled “DevTools Protocol”| Item | Rule |
|---|---|
| On demand | Reading a cold cdp-N discovery endpoint (/, /json, /json/list, /json/version) starts the instance with debugging on and the default stealth. A later default /start returns it; stealth=false is 409 INSTANCE_BACKEND_MISMATCH until stopped. For plain Playwright over CDP, /start?stealth=false first. |
| Attach only | A WebSocket, /json/protocol and the DevTools frontend never start one. Cross-site and same-site requests from a web page cannot auto-start one; same-origin requests to the discovery endpoints can. With CDP auto-start off, call /start first. |
501 | Firefox, or Chromium with useRemoteDebuggingPort=false. /devtools-url on Firefox is 200 with null fields. |
| Tabs | A page opened with no context named, or in a client-created context, shows in /tabs, /history, /network, /console. Target.createTarget with a url loads before the server sees it: in /history, not in network or console. Open a blank page and navigate instead. |
| Paths | %2F, %2E, %5C or backslashes in the path: 400 CDP_BAD_PATH (400 CDP_BAD_WS_PATH on upgrade). The query string is not checked, so an encoded ws= works. |
| Close code | Reason | Meaning |
|---|---|---|
1001 | instance stopped, instance restarting, instance idle timeout, server shutting down | Ended on purpose; reconnect when the instance is back. |
1000 | none | Closed normally by the browser. |
1011 | such as browser exited, chrome connect timeout, chrome backpressure | Failure: the browser exited, could not be reached or could not keep up. |
Validation
Section titled “Validation”Values are checked before the operation. Some checks, including repeated scalar query parameters, timeoutMs and navigation URLs, run before an auto-start; other route-specific checks run after it. An invalid screenshot, PDF, scriptBase64, since or clear value, or a non-absolute url on GET /cookies, is 400 VALIDATION_ERROR naming it, and so is repeating one. Invalid CSS in selector, mask or hide is caught by the page’s parser, so with url it fails after navigating.
Metrics
Section titled “Metrics”GET /metrics includes open tabs across instances and maxTabsPerInstance.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
502 PAGE_CRASHED | The tab’s page crashed; /tabs shows crashed: true and POST /viewport skips it | Open a new tab, then close the crashed tab with /tab/close?tabId=<crashedTabId> |
502 BROWSER_DISCONNECTED | The tab or browser closed mid-request, as in /stop or /restart | Open a new tab or start the instance |
409 PAGE_NAVIGATED | The page navigated during /eval, /html, /text or /markdown | Run it again on the new page |
504 TIMEOUT on /html, /text or /pdf, details.phase engine | The page did not answer within 30 seconds (60 for a /pdf print), for example a script stuck in a loop. A /pdf with url frees the tab with that answer | Open a new tab, then close the unresponsive tab with /tab/close?tabId=<unresponsiveTabId> |
/eval gives undefined | Stealth isolated world | Read the DOM, or call /stop followed by /start?stealth=false and reopen the page |
| Empty console | Stealth partial capture | Call /stop, then /start?stealth=false, and reopen the page to capture its console output |
| No downloaded file | Downloads are not supported | Fetch the file another way |
501 on /pdf | Headful or Firefox | showBrowser=false on Chromium |
409 INSTANCE_BACKEND_MISMATCH | Different stealth on a running instance | /stop, then start again |
Version differs from chromiumVersion | Unresolved major treated as omitted | Read browserFullVersion, pass a full version |
431 in a browser shows as a network error | Request head over 16 KiB | Send options in a POST body |