Browser Interaction

The Hoody Browser service exposes a REST API for navigating pages, evaluating JavaScript, extracting rendered content, and exporting the visible document. All endpoints target the in-container Browser service reached through the Hoody proxy at the container hostname — they are not part of the control-plane Hoody API.

Every operation requires a browser_id query parameter selecting the browser instance (a 0-based index). Instance creation is automatic unless explicitly disabled with start=false.

Browsing

GET /api/v1/browser/browse

Opens a new tab (or reuses an existing one) and navigates to a URL. Returns the resolved tab ID and final 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. Instances are created automatically unless set to false. 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

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/browse?browser_id=0&url=https%3A%2F%2Fexample.com&active=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

200

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

400

{
  "error": "Missing required parameter: url",
  "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 using a JSON request body. Useful when the URL is long or you prefer POST semantics for navigation requests.

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. Instances are created automatically unless set to false. 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

cURL

curl -X POST "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/browse?browser_id=0" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "active": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.browser.interaction.browsePost({ url: 'https://example.com', active: true }, { browser_id: '0' });

200

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

400

{
  "error": "Missing required field: url",
  "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 Evaluation

GET /api/v1/browser/eval

Executes a JavaScript snippet in the context of the last active tab and returns the result. The script parameter accepts base64-encoded input for binary-safe transport.

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. Instances are created automatically unless set to false. 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)

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/eval?browser_id=0&script=document.title" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.browser.interaction.evalGet({ browser_id: '0', script: 'document.title' });

200

{
  "result": "Example Domain"
}

400

{
  "error": "Missing required parameter: script",
  "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

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

Executes a JavaScript snippet provided in the request body. The body may be JSON (application/json) with a script field or raw JavaScript (text/plain).

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. Instances are created automatically unless set to false. When auto-start is disabled globally, set to true to create an instance.

Request Body

The body is required. It may be sent as JSON or raw text:

• application/json — object with a script field
• text/plain — raw JavaScript source

Field	Type	Required	Description
script	string	No	JavaScript code to execute. The server rejects requests that omit this field with the MISSING_SCRIPT error code, so it should always be supplied even though the schema marks it optional.

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

200

{
  "result": 42
}

400

{
  "error": "Missing required field: script",
  "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.

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. Instances are created automatically unless set to false. When auto-start is disabled globally, set to true to create an instance.

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/html?browser_id=0" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.browser.page.getHtml({ browser_id: '0' });

200

<!DOCTYPE html>
<html>
<head><title>Example Domain</title></head>
<body>
<h1>Example Domain</h1>
</body>
</html>

GET /api/v1/browser/text

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

Parameters

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/text?browser_id=0" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.browser.page.getText({ browser_id: '0' });

200

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

PDF Export

GET /api/v1/browser/pdf

Generates a PDF of the current page. Supports paper format, orientation, background graphics, and uniform margin control.

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. Instances are created automatically unless set to false. 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)

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/pdf?browser_id=0&format=A4&landscape=true&printBackground=true&margin=1cm" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  --output page.pdf

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

200

%PDF-1.4
%binary PDF content returned in response body (Content-Type: application/pdf)

Screenshots

GET /api/v1/browser/screenshot

Navigates to a URL and/or captures a screenshot of a browser tab. The response format depends on the format parameter:

• png (default) — raw PNG bytes (image/png)
• jpeg — raw JPEG bytes (image/jpeg)
• base64 — JSON envelope with a data field containing the base64-encoded image

When url is provided, the browser navigates first and waits for the page to load before capturing. When url is omitted, a screenshot of the current page state is taken.

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. Instances are created automatically unless set to false. 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

cURL

curl -X GET "https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com/api/v1/browser/screenshot?browser_id=0&url=https%3A%2F%2Fexample.com&format=base64&fullPage=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.browser.interaction.takeScreenshot({ browser_id: '0', url: 'https://example.com', format: 'base64', fullPage: true });

200 (base64)

{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}

400

{
  "error": "Invalid value for parameter: format",
  "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

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

The binary responses from /html, /text, and /pdf return their native content types. When piping screenshots or PDFs to disk with curl, add --output <file> with the appropriate extension so the file is saved correctly.