# Browser Interaction

**Page:** api/browser/interaction

[Download Raw Markdown](./api/browser/interaction.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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.



```bash
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"
```


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


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


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



```bash
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
  }'
```


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


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


```json
{
  "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.



```bash
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"
```


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


```json
{
  "result": "Example Domain"
}
```


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


```json
{
  "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.



```bash
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"
  }'
```


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


```json
{
  "result": 27
}
```


```json
{
  "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.



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


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


```html
<!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.



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


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


```text
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.



```bash
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
```


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


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.



```bash
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
```


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


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:

```json
{
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
```


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


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




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.