Browser Interaction

Browser Interaction endpoints let you drive a managed Chromium instance exposed through the Hoody Browser container service. Use these operations to navigate to URLs, run arbitrary JavaScript against the active tab, extract structured page content, generate PDFs, and capture screenshots. All requests are served by the container’s browser service through the Hoody proxy.

Navigate to URL

`GET /api/v1/browser/browse`

Opens a new tab (or uses 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 (default: `true`)	Controls instance creation behavior. 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 (default: `true`)	Make the tab active (focused) after navigation
`onlyIfNotExists`	query	boolean	No (default: `false`)	Only create a new tab if no tab with the same URL exists
`ignoreGetParameters`	query	boolean	No (default: `false`)	Ignore query parameters when checking for existing URL

curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/browse?browser_id=0&url=https%3A%2F%2Fexample.com"

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

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

{
  "error": "Missing required query 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 uses an existing one) and navigates to a URL using the POST method. Identical to the GET variant but accepts the navigation options in a JSON body, which is convenient when the URL or other parameters are long or contain characters that are awkward to encode into a query string.

Parameters

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

curl -X POST "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/browse?browser_id=0" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "tabId": 1,
    "active": true,
    "onlyIfNotExists": true
  }'

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

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

{
  "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

Execute JavaScript

`GET /api/v1/browser/eval`

Executes a JavaScript snippet in the context of the last active tab. The script parameter can be passed as a URL-encoded string or as a base64-encoded payload.

Parameters

Name	In	Type	Required	Description
`browser_id`	query	string	Yes	Unique identifier for the browser instance (0-based index)
`start`	query	boolean	No (default: `true`)	Controls instance creation behavior. 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)

curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/eval?browser_id=0&script=document.title"

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

{
  "result": "Hoody Dashboard - Overview"
}

{
  "error": "Missing required query 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

{
  "error": "No browser instance exists 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. Use this variant when the script is large or contains characters that are awkward to place in a URL. The body can be sent as either application/json (with a script field) or as text/plain with the raw JavaScript code as the 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 (default: `true`)	Controls instance creation behavior. 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
`script`	string	No	JavaScript code to execute. When sending `application/json`, pass as the `script` field. When sending `text/plain`, place the raw code in the body.

curl -X POST "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/eval?browser_id=0" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Array.from(document.querySelectorAll(\"a\")).map(a => a.href)"
  }'

await client.browser.interaction.evalPost(
  { script: "Array.from(document.querySelectorAll('a')).map(a => a.href)" },
  { browser_id: "0" }
);

{
  "result": [
    "https://example.com/",
    "https://example.com/about",
    "https://example.com/contact"
  ]
}

{
  "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. Useful for scraping, diffing, or feeding into downstream text processing.

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 (default: `true`)	Controls instance creation behavior. 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.

curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/html?browser_id=0"

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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hoody Dashboard</title>
  </head>
  <body>
    <main id="app">
      <h1>Welcome back</h1>
      <p>You have 3 unread notifications.</p>
    </main>
  </body>
</html>

`GET /api/v1/browser/text`

Returns the visible text content of the page, equivalent to document.body.innerText. Useful for summarisation, search-indexing, or feeding into an LLM context window.

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 (default: `true`)	Controls instance creation behavior. 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.

curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/text?browser_id=0"

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

Welcome back

You have 3 unread notifications.

`GET /api/v1/browser/pdf`

Generates a PDF of the current page. Optionally navigate to a URL first, then export. Supports paper format, orientation, margins, and inclusion of background graphics.

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 (default: `true`)	Controls instance creation behavior. 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 (default: `"Letter"`)	Paper format (e.g. `A4`, `Letter`)
`landscape`	query	boolean	No (default: `false`)	Use landscape orientation
`printBackground`	query	boolean	No (default: `false`)	Include background graphics
`margin`	query	string	No	Uniform margin (e.g. `1cm`, `0.5in`)

curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/pdf?browser_id=0&url=https%3A%2F%2Fexample.com%2Finvoice&format=A4&landscape=false&printBackground=true&margin=1cm" \
  --output invoice.pdf

const pdfBytes = await client.browser.page.exportPdf({
  browser_id: "0",
  url: "https://example.com/invoice",
  format: "A4",
  printBackground: true,
  margin: "1cm"
});

Binary PDF document (Content-Type: application/pdf). Pipe the response body to a file with --output (cURL) or write the returned buffer to disk.

`GET /api/v1/browser/screenshot`

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

Navigation + Screenshot workflow

If url is provided: navigate to the URL, wait for page load, then capture.
If url is omitted: capture a 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 JSON.
Full-page capture with fullPage=true.
Quality control for JPEG compression.

Common use cases include visual regression testing, website monitoring, and 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 (default: `true`)	Controls instance creation behavior. 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 (default: `false`)	Only create a new tab if no tab with the same URL exists
`ignoreGetParameters`	query	boolean	No (default: `false`)	Ignore query strings when checking for existing URL
`format`	query	string	No (default: `"png"`)	Output format. One of: `png`, `jpeg`, `base64`.
`quality`	query	integer	No	Image quality for JPEG format (0-100)
`fullPage`	query	boolean	No (default: `false`)	Capture the entire scrollable page

# Binary PNG
curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/screenshot?browser_id=0&url=https%3A%2F%2Fexample.com&format=png&fullPage=true" \
  --output page.png

# Base64 JSON
curl -X GET "https://proj-abc123-cont-xyz789-browser-1.eu-west-1.containers.hoody.icu/api/v1/browser/screenshot?browser_id=0&format=base64"

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

// Base64 JSON
const base64 = await client.browser.interaction.takeScreenshot({
  browser_id: "0",
  format: "base64"
});

Binary image, served as image/png or image/jpeg depending on the format parameter. Write the response body to a file directly.

Returned as application/json when format=base64.

{
  "data": "iVBORw0KGgoAAAANSUhEUgAA..."
}

{
  "error": "Invalid value for parameter 'format': expected one of png|jpeg|base64",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "format",
    "expected": ["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

{
  "error": "No browser instance exists 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`