Browser Interaction

Download Page (.md)

The Browser Interaction API lets you navigate web pages, run JavaScript in a browser context, extract page content, export PDFs, and capture screenshots. All endpoints operate against a browser instance identified by browser_id and support multi-tab workflows.

Each endpoint accepts a browser_id query parameter referencing an existing instance. The start parameter controls whether the instance is auto-created: in default mode instances are created on first use; pass start=false to require a pre-existing instance, or start=true when auto-start has been disabled globally.

`GET /api/v1/browser/browse`

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

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/browse?browser_id=0&url=https%3A%2F%2Fexample.com&active=true"

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.
`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`

Response

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

{
  "error": "URL is required",
  "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 /api/v1/browser/browse`

Opens a new tab (or reuses an existing one) and navigates to a URL. The URL and tab options are supplied in the JSON request body.

cURL
SDK

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

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.

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`

{
  "url": "https://example.com/dashboard",
  "tabId": 1,
  "active": true,
  "onlyIfNotExists": true,
  "ignoreGetParameters": false
}

Response

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

{
  "error": "URL is required",
  "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

Script Execution

`GET /api/v1/browser/eval`

Executes a JavaScript snippet in the context of the last active tab. The script is passed as a query parameter and may be base64-encoded.

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/eval?browser_id=0&script=ZG9jdW1lbnQudGl0bGU="

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.
`script`	query	string	Yes	JavaScript code to execute (can be base64 encoded)

Response

{
  "result": "Example Domain"
}

{
  "error": "Script parameter is required",
  "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

{
  "error": "Browser instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "5"
  }
}

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 /api/v1/browser/eval`

Executes a JavaScript snippet provided in the request body. Send either an application/json body with a script field or a raw text/plain JavaScript body.

cURL
SDK

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

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.

Request Body

The request body is required. Send application/json with a script field, or text/plain with raw JavaScript code.

Field	Type	Required	Description
`script`	string	No	JavaScript code to execute

{
  "script": "document.querySelectorAll('a').length"
}

Response

{
  "result": 42
}

{
  "error": "Script field is required",
  "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 /api/v1/browser/html`

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

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/html?browser_id=0"

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.

Response

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example Domain</title>
  </head>
  <body>
    <div>
      <h1>Example Domain</h1>
    </div>
  </body>
</html>

The response is served as text/html with the raw HTML string as the body.

`GET /api/v1/browser/text`

Returns the visible text content of the page, equivalent to document.body.innerText.

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/text?browser_id=0&tabId=2"

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.

Response

Example Domain

This domain is for use in illustrative examples in documents...

The response is served as text/plain with the extracted text string as the body.

Export

`GET /api/v1/browser/pdf`

Generates a PDF of the current page. Supports paper format, orientation, background inclusion, and margins. Pass url to navigate to a different page before generating the PDF.

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/pdf?browser_id=0&format=A4&landscape=true&printBackground=true&margin=1cm" \
  --output page.pdf

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.
`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`)

Response

The response is served as application/pdf with the raw PDF binary as the body. Save the response directly to a .pdf file.

Screenshots

`GET /api/v1/browser/screenshot`

Navigates to a URL (when provided) and captures a screenshot of a browser tab. If url is omitted, the current page state is captured.

Smart tab management: pass onlyIfNotExists=true to avoid creating duplicate tabs.
Output formats: choose png, jpeg, or base64.
Full page capture: pass fullPage=true to capture the entire scrollable page.
JPEG quality: control compression with the quality parameter (0–100).

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

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/browser/screenshot?browser_id=0&url=https%3A%2F%2Fexample.com&format=png&fullPage=true" \
  --output page.png

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

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`. In default mode, instances are created automatically. Set to `false` to prevent creation. When auto-start is disabled globally, set to `true` to create an instance.
`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. Allowed values: `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`

Response

The response is the raw image bytes. Save the response body directly to a file (e.g. page.png or page.jpg).

For format=base64, the response is JSON:

{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
}

{
  "error": "Invalid screenshot parameters",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "quality",
    "constraint": "Must be between 0 and 100"
  }
}

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

{
  "error": "Browser instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "7"
  }
}

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`

Navigation

GET /api/v1/browser/browse

Parameters

Response

POST /api/v1/browser/browse

Parameters

Request Body

Response

Script Execution

GET /api/v1/browser/eval

Parameters

Response

POST /api/v1/browser/eval

Parameters

Request Body

Response

Page Content

GET /api/v1/browser/html

Parameters

Response

GET /api/v1/browser/text

Parameters

Response

Export

GET /api/v1/browser/pdf

Parameters

Response

Screenshots

GET /api/v1/browser/screenshot

Parameters

Response

`GET /api/v1/browser/browse`

`POST /api/v1/browser/browse`

`GET /api/v1/browser/eval`

`POST /api/v1/browser/eval`

`GET /api/v1/browser/html`

`GET /api/v1/browser/text`

`GET /api/v1/browser/pdf`

`GET /api/v1/browser/screenshot`