The Browser Interaction API provides endpoints to navigate to URLs, execute JavaScript in the browser context, extract page content (HTML, text, PDF), and capture screenshots. Use these endpoints to automate web interactions, scrape content, run scripts, and generate visual or document exports from a controlled browser instance.

All endpoints require a browser_id query parameter identifying the target browser instance, plus a start parameter that controls automatic instance creation. The start parameter works as follows: in default mode instances are created automatically (set start=false to prevent creation); when auto-start is disabled globally, set start=true to explicitly create a new instance.

---

Navigation

GET /browse

Opens a new tab (or reuses an existing one) and navigates to a URL.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
start	query	boolean	No	Controls instance creation behavior. Default: true
url	query	string	No	The URL to navigate to
tabId	query	integer	No	The ID of the tab to interact with
active	query	boolean	No	Make the tab active (focused) after navigation. Default: true
onlyIfNotExists	query	boolean	No	Only create a new tab if no tab with the same URL exists. Default: false
ignoreGetParameters	query	boolean	No	Ignore query parameters when checking for existing URL. Default: false

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/browse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "active=true"

SDK

const result = await client.browser.interaction.browse({
  browser_id: "0",
  url: "https://example.com",
  active: true
});

Response (200)

{
  "tabId": 2,
  "url": "https://example.com/",
  "created": true,
  "reused": false
}

Response (400)

{
  "error": "Missing URL parameter",
  "code": "MISSING_URL",
  "details": {
    "parameter": "url"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation	Check the error details for the specific parameter and constraint that failed
MISSING_URL	Missing URL	The required url parameter was not provided	Provide a valid url parameter in the request

---

POST /browse

Opens a new tab (or reuses an existing one) and navigates to a URL. Identical behavior to GET /browse, but accepts the parameters as a JSON request body.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
start	query	boolean	No	Controls instance creation behavior. Default: true

Request Body

Field	Type	Required	Description
url	string	Yes	The URL to navigate to
tabId	integer	No	The ID of the tab to interact with
active	boolean	No	Make the tab active (focused) after navigation. Default: true
onlyIfNotExists	boolean	No	Only create a new tab if no tab with the same URL exists. Default: false
ignoreGetParameters	boolean	No	Ignore query parameters when checking for existing URL. Default: false

cURL

curl -X POST "https://api.hoody.com/api/browser/interaction/browse?browser_id=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "active": true
  }'

SDK

const result = await client.browser.interaction.browsePost({
  browser_id: "0",
  data: {
    url: "https://example.com",
    active: true
  }
});

Response (200)

{
  "tabId": 3,
  "url": "https://example.com/",
  "created": true,
  "reused": false
}

Response (400)

{
  "error": "Missing url field in request body",
  "code": "MISSING_URL",
  "details": {
    "field": "url"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation	Check the error details for the specific parameter and constraint that failed
MISSING_URL	Missing URL	The required url field was not provided in the request body	Provide a valid url field in the JSON request body

---

JavaScript Execution

GET /eval

Executes a JavaScript snippet in the context of the last active tab.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
start	query	boolean	No	Controls instance creation behavior. Default: true
script	query	string	Yes	JavaScript code to execute (can be base64 encoded)

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/eval" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0" \
  --data-urlencode "script=document.title"

SDK

const result = await client.browser.interaction.evalGet({
  browser_id: "0",
  script: "document.title"
});

Response (200)

{
  "result": "Example Domain"
}

Response (400)

{
  "error": "Missing script parameter",
  "code": "MISSING_SCRIPT",
  "details": {
    "parameter": "script"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation	Check the error details for the specific parameter and constraint that failed
MISSING_SCRIPT	Missing Script	The required script parameter was not provided	Provide a valid script parameter in the query string

Response (404)

{
  "error": "No browser instance found for browser_id=0",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

Error Code	Title	Description	Resolution
INSTANCE_NOT_FOUND	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

---

POST /eval

Executes a JavaScript snippet provided in the request body. Accepts either a JSON body with a script field or a raw text/plain body containing the JavaScript code directly.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
start	query	boolean	No	Controls instance creation behavior. Default: true

Request Body

Field	Type	Required	Description
script	string	No	JavaScript code to execute (when using application/json)

Alternatively, send raw JavaScript as a text/plain body.

cURL

curl -X POST "https://api.hoody.com/api/browser/interaction/eval?browser_id=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "document.querySelectorAll(\"a\").length"
  }'

SDK

const result = await client.browser.interaction.evalPost({
  browser_id: "0",
  data: {
    script: "document.querySelectorAll(\"a\").length"
  }
});

Response (200)

{
  "result": 27
}

Response (400)

{
  "error": "Missing script field in request body",
  "code": "MISSING_SCRIPT",
  "details": {
    "field": "script"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation	Check the error details for the specific parameter and constraint that failed
MISSING_SCRIPT	Missing Script	The required script field was not provided in the request body	Provide a valid script field in the JSON request body or raw JavaScript in the text/plain body

---

Page Content

GET /html

Returns the full HTML content of the active page (equivalent to document.documentElement.outerHTML).

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
tabId	query	integer	No	The ID of the tab to interact with
start	query	boolean	No	Controls instance creation behavior. Default: true

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0"

SDK

const html = await client.browser.page.getHtml({
  browser_id: "0"
});

Response (200)

<!DOCTYPE html>
<html>
<head><title>Example Domain</title></head>
<body>
<div>
  <h1>Example Domain</h1>
  <p>This domain is for use in illustrative examples in documents.</p>
</div>
</body>
</html>

---

GET /text

Returns the visible text content of the active page (equivalent to document.body.innerText).

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
tabId	query	integer	No	The ID of the tab to interact with
start	query	boolean	No	Controls instance creation behavior. Default: true

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/text" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0"

SDK

const text = await client.browser.page.getText({
  browser_id: "0"
});

Response (200)

Example Domain
This domain is for use in illustrative examples in documents.
You may use this domain in literature without prior coordination or asking for permission.
More information...

---

GET /pdf

Generates a PDF of the current page. Supports format, landscape, margins, and background options.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
tabId	query	integer	No	The ID of the tab to interact with
start	query	boolean	No	Controls instance creation behavior. Default: true
url	query	string	No	Optional URL to navigate to before generating the PDF
format	query	string	No	Paper format (e.g. A4, Letter). Default: "Letter"
landscape	query	boolean	No	Use landscape orientation. Default: false
printBackground	query	boolean	No	Include background graphics. Default: false
margin	query	string	No	Uniform margin (e.g. ‘1cm’, ‘0.5in’)

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0" \
  --data-urlencode "format=A4" \
  --data-urlencode "landscape=false" \
  --data-urlencode "printBackground=true" \
  --data-urlencode "margin=1cm" \
  -o page.pdf

SDK

const pdf = await client.browser.page.exportPdf({
  browser_id: "0",
  format: "A4",
  landscape: false,
  printBackground: true,
  margin: "1cm"
});

Response (200)

The response is a binary application/pdf document. Save the response body to a file (e.g. page.pdf) to view the rendered page.

---

Screenshots

GET /screenshot

Navigates to a URL and/or captures a screenshot of a browser tab.

Navigation + Screenshot workflow:

• If url is provided: Navigate to URL → Wait for page load → Capture screenshot
• If url is omitted: Capture screenshot of the current page state

Key features:

• Smart tab management with onlyIfNotExists to avoid duplicate tabs
• Multiple output formats: PNG, JPEG, or Base64-encoded
• Full page capture with fullPage=true
• Quality control for JPEG compression

Common use cases: visual regression testing, website monitoring, content verification.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index)
start	query	boolean	No	Controls instance creation behavior. Default: true
url	query	string	No	The URL to navigate to
tabId	query	integer	No	The ID of the tab to interact with
onlyIfNotExists	query	boolean	No	Only create a new tab if no tab with the same URL exists. Default: false
ignoreGetParameters	query	boolean	No	Ignore query strings when checking for existing URL. Default: false
format	query	string	No	Output format. One of png, jpeg, base64. Default: "png"
quality	query	integer	No	Image quality for JPEG format (0-100)
fullPage	query	boolean	No	Capture the entire scrollable page. Default: false

This endpoint takes no request body.

cURL

curl -G "https://api.hoody.com/api/browser/interaction/screenshot" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "browser_id=0" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "format=png" \
  --data-urlencode "fullPage=true" \
  -o screenshot.png

SDK

const screenshot = await client.browser.interaction.takeScreenshot({
  browser_id: "0",
  url: "https://example.com",
  format: "png",
  fullPage: true
});

Response (200 - binary)

The response body is a binary image/png (or image/jpeg depending on format). Save it to a file:

screenshot.png

For the base64 format, the response is JSON:

{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}

Response (400)

{
  "error": "Invalid format value",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "format",
    "allowed": ["png", "jpeg", "base64"]
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation	Check the error details for the specific parameter and constraint that failed

Response (404)

{
  "error": "No browser instance found for browser_id=0",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

Error Code	Title	Description	Resolution
INSTANCE_NOT_FOUND	Instance Not Found	No browser instance exists for the specified browser_id	Verify the browser_id value, or create a new instance using /start

Tip

For visual regression testing, use fullPage=true together with a deterministic format=base64 to capture a reproducible image of the entire scrollable page. Combine with a stable url and onlyIfNotExists=true to ensure the test always runs against the same tab.