Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Hoody Browser. Every route, field and response is in the API reference.

ItemRule
Hostnamebrowser-N selects instance N. Each has its own tabs, cookies and state.
browser_idPicks 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 NThe browser-N hostname. --browser-id 1 reaches the instance the HTTP examples use; 0 is browser-0.
Derived from NInternal port 30000 + N, display display-(500 + N), DevTools on cdp-N.

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.

startEffect
omittedAuto-create (unless disabled)
false404 instead of creating
trueCreate 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.

The instance API lists every option. Rules it does not spell out:

OptionRule
browserchromium (default) or firefox. Firefox runs through Playwright, ignores stealth and rejects useRemoteDebuggingPort=true.
chromiumVersionOmitted: 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.
fingerprintIdNames 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.
stealthPatchright 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".
launchArgumentsRepeat 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, timezoneIdA BCP 47 tag or IANA zone. Empty strings count as unset; other invalid values return 400 VALIDATION_ERROR naming the option, before launch.
geolocationA 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, noViewportJSON 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.
PrecedenceTop-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.
proxyServerhttp://, 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, dnsOverHttpsUrlQUIC off; DNS-over-HTTPS on, resolver Cloudflare by default, any HTTPS resolver accepted.
useRemoteDebuggingPortDefault true, fills in webSocketDebuggerUrl (null on Firefox or when off). The kit picks the port; remoteDebuggingPort is ignored.
remoteDebuggingAddressDefault 0.0.0.0. Connect through the URLs /devtools-url returns.
showBrowserDefault true (headful). false is headless, which /pdf requires.
displayOn 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, extensionsStoreIdsChromium 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.
firefoxExecutablePathA file that does not exist on the server is 400 VALIDATION_ERROR, not retried.
  • 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.
SituationResult
/start on a running instanceReturns 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 changeCannot 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 optionsAn instance started with chromiumVersion=136 restarts on 136 unless the request says otherwise.
/stop, /shutdown on an empty address404 NOT_FOUND; neither starts an instance.
/shutdownAnswers 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 historyKept on disk, 30 days by default; survives restarts.

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.

AnswerCause
504 TIMEOUT, details.phase launch, details.outcome unknownThe 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 unknownWork 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_ERRORThe launch did not finish within 180 seconds.
503 INSTALL_IN_PROGRESS, Retry-After: 30Still 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-AfterHeadful start with no display. Not retried; start with showBrowser=false, or retry once the display runs.
409 PORT_IN_USEAnother process listens on browser_port; the message names host and port. Not retried: stop that process or use another instance number.
ItemRule
ResponsetabId, url, requestedUrl (before redirects), title, httpStatus, created, reused, elapsedMs.
RedactionBoth 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.
waitUntilcommit, domcontentloaded or load (default). networkidle is not offered.
timeoutMsUp 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 routesWith no deadline of their own, bounded by the same server timeout: 504 TIMEOUT.
Site errorsA site’s own 404 arrives as httpStatus: 404 in a 200.
FailureDNS 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.
onlyIfNotExistsMatches 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/).
tabIdAccepted 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.
  • 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.

The interaction API lists the options and limits.

ItemRule
Responsemarkdown, title, url, httpStatus (null without url), fetchedAt, truncated, chars, metadata (description, author, site, published, language, wordCount); url and title redacted like /browse.
maxCharsCuts at the last line break, or at the limit when there is none, never splitting a UTF-16 surrogate pair.
LinksRelative 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_LARGEHTML 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_FAILEDThe converter cannot handle the page.
TimeA 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.

The interaction API 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.
ItemRule
Worldstealth=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_ERRORThe 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_SERIALIZABLEA BigInt or circular object.
TimeouttimeoutMs 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 script400 VALIDATION_ERROR (Missing required parameter: script), like a missing url on /browse.

The interaction API has every field.

ItemRule
/snapshotYAML accessibility tree with [ref=...] handles, snapshotId, url, title, truncated, chars. maxChars 30000 by default, at most 200000, cut on a line boundary.
Actionsclick, fill, type, press, select, check, hover. fill and type carry value, press key, select values, check checked.
/wait kindstarget, text, url, loadState. Never true: 504 TIMEOUT, not matched: false.
Targetsexact 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 valuesTextbox, 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.
BudgettimeoutMs 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_BUSYA 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.
DialogsThe 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.
ValueMeaning
not-startedNever reached the page; retry is safe.
unknownThe action may have taken effect; input dispatch is not confirmed. Snapshot and check before retrying, or it may run twice.
completedFinished 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.

  • Cookies: each needs name, value and either an absolute url or domain with path. A bad cookie is 400 VALIDATION_ERROR naming the field, such as cookies[1].sameSite.
  • Close: a malformed tabId is 400 VALIDATION_ERROR; one that names no open tab is 404 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 /viewport returns viewport, source, tabs, converged. With no instance, both routes answer 404 with details.reason: "no_instance".
  • Resize: POST /viewport with {"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 in details.failedTabs of a 502 VIEWPORT_APPLY_INCOMPLETE.
  • Responsive at runtime: {"viewport":null} works only on Chromium created responsive (/start?noViewport=true). Fixed-created is 409 REQUIRES_RESTART; Firefox is 501 NOT_SUPPORTED. /metadata then reports "viewport": null and viewportSource.
ItemRule
/consoleConsole 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".
Buffers500 entries each. dropped counts discarded entries since start or the last clear=true.
sinceISO 8601, such as 2026-10-05T12:00:00Z. Omitted or empty applies no timestamp filter; other invalid values are 400 VALIDATION_ERROR.
tabIdFilters 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.
/historysince, domain, limit, offset.
Page loadsEvery 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 changesURL 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 /historyAlso covers same-document changes made before it that were not yet written: they are not recorded afterwards.
ItemRule
On demandReading 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 onlyA 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.
501Firefox, or Chromium with useRemoteDebuggingPort=false. /devtools-url on Firefox is 200 with null fields.
TabsA 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 codeReasonMeaning
1001instance stopped, instance restarting, instance idle timeout, server shutting downEnded on purpose; reconnect when the instance is back.
1000noneClosed normally by the browser.
1011such as browser exited, chrome connect timeout, chrome backpressureFailure: the browser exited, could not be reached or could not keep up.

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.

GET /metrics includes open tabs across instances and maxTabsPerInstance.

SymptomCauseFix
502 PAGE_CRASHEDThe tab’s page crashed; /tabs shows crashed: true and POST /viewport skips itOpen a new tab, then close the crashed tab with /tab/close?tabId=<crashedTabId>
502 BROWSER_DISCONNECTEDThe tab or browser closed mid-request, as in /stop or /restartOpen a new tab or start the instance
409 PAGE_NAVIGATEDThe page navigated during /eval, /html, /text or /markdownRun it again on the new page
504 TIMEOUT on /html, /text or /pdf, details.phase engineThe 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 answerOpen a new tab, then close the unresponsive tab with /tab/close?tabId=<unresponsiveTabId>
/eval gives undefinedStealth isolated worldRead the DOM, or call /stop followed by /start?stealth=false and reopen the page
Empty consoleStealth partial captureCall /stop, then /start?stealth=false, and reopen the page to capture its console output
No downloaded fileDownloads are not supportedFetch the file another way
501 on /pdfHeadful or FirefoxshowBrowser=false on Chromium
409 INSTANCE_BACKEND_MISMATCHDifferent stealth on a running instance/stop, then start again
Version differs from chromiumVersionUnresolved major treated as omittedRead browserFullVersion, pass a full version
431 in a browser shows as a network errorRequest head over 16 KiBSend options in a POST body