### start()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/crawl.md

Initiates a new crawl job. You can specify the starting URL, limits, allowed domains, exclusion patterns, and browser/scraping options.

```APIDOC
## start()

### Description
Start a new crawl job.

### Method
POST (assumed, based on 'start' operation)

### Endpoint
/crawl/start (assumed)

### Parameters
#### Request Body
- **url** (string) - Required - Root URL to start crawling from
- **limit** (number) - Optional - Maximum number of pages to crawl
- **allowedDomains** (string[]) - Optional - Limit crawling to specific domains
- **excludePatterns** (string[]) - Optional - URL patterns to exclude
- **sessionOptions** (CreateSessionParams) - Optional - Browser session configuration
- **scrapeOptions** (ScrapeOptions) - Optional - Scrape options for collected pages

### Request Example
```json
{
  "url": "https://example.com",
  "limit": 100,
  "allowedDomains": ["example.com"],
  "scrapeOptions": {
    "formats": ["markdown", "links"]
  }
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the created crawl job

#### Response Example
```json
{
  "jobId": "crawl-job-id"
}
```
```

--------------------------------

### Install Hyperbrowser SDK

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/README.md

Install the Hyperbrowser SDK using npm or yarn.

```bash
npm install @hyperbrowser/sdk
# or
yarn add @hyperbrowser/sdk
```

--------------------------------

### Start Browser Use Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a Browser Use task. Provide the starting URL, a goal description, and optional session configurations, LLM model, or agent version.

```typescript
async start(params: StartBrowserUseTaskParams): Promise<StartBrowserUseTaskResponse>
```

--------------------------------

### start()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a new HyperAgent task for automated browser interactions and goal completion. It requires a starting URL and a description of the task goal, with optional parameters for session configuration, LLM selection, agent version, and maximum steps.

```APIDOC
## start()

### Description
Start a new HyperAgent task.

### Method
POST

### Endpoint
/agents/hyperagent/start

### Parameters
#### Request Body
- **url** (string) - Required - Starting URL for the agent
- **goal** (string) - Required - Description of the task to perform
- **sessionOptions** (CreateSessionParams) - Optional - Browser session configuration
- **llm** (HyperAgentLlm) - Optional - LLM model to use. Options include: gpt-5.5, gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-4o, gpt-4o-mini, claude-sonnet-4-5, claude-sonnet-4-6, gemini-2.5-flash, gemini-3-flash-preview
- **version** (HyperAgentVersion) - Optional - Agent version ("0.8.0" or "1.1.0")
- **maxSteps** (number) - Optional - Maximum action steps

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the started task

### Request Example
```json
{
  "url": "https://example.com",
  "goal": "Find and click the 'Sign Up' button, fill in the email field with test@example.com",
  "llm": "gpt-5",
  "version": "1.1.0"
}
```
```

--------------------------------

### Install Hyperbrowser SDK via npm

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

Install the Hyperbrowser SDK using npm. This is the first step before using the SDK in your Node.js project.

```bash
npm install @hyperbrowser/sdk
```

--------------------------------

### Install Dependencies

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/AGENTS.md

Installs project dependencies and automatically runs the build script. Ensure TypeScript errors are resolved if the build fails.

```bash
yarn install
```

--------------------------------

### Start Gemini Computer Use Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a Gemini Computer Use task. Requires a starting URL and a task description. Optional session and LLM configurations can be provided.

```typescript
async start(params: StartGeminiComputerUseTaskParams): Promise<StartGeminiComputerUseTaskResponse>
```

--------------------------------

### Initialize HyperbrowserClient with Environment Variable

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/client.md

Initialize the HyperbrowserClient using the HYPERBROWSER_API_KEY environment variable for authentication. This is the simplest way to get started if the environment variable is already set.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";

// Using environment variable
const client = new Hyperbrowser();
```

--------------------------------

### Start CUA Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a Cua task. Requires a starting URL and a task description. Optional session and LLM configurations can be provided.

```typescript
async start(params: StartCuaTaskParams): Promise<StartCuaTaskResponse>
```

--------------------------------

### Install Hyperbrowser SDK via yarn

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

Install the Hyperbrowser SDK using yarn. This is an alternative to npm for package management.

```bash
yarn add @hyperbrowser/sdk
```

--------------------------------

### Manage Volumes and Mounts

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

Create, list, and get volumes, then mount a volume into a sandbox for persistent storage.

```typescript
const volume = await client.volumes.create({ name: "project-cache" });
const volumes = await client.volumes.list();
const sameVolume = await client.volumes.get(volume.id);

const sandbox = await client.sandboxes.create({
  imageName: "node",
  mounts: {
    "/workspace/cache": {
      id: sameVolume.id,
      type: "rw",
      shared: true,
    },
  },
});

await sandbox.stop();
```

--------------------------------

### Start and Wait for Browser Use Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Browser Use task and waits for its completion, returning the final result.

```typescript
async startAndWait(params: StartBrowserUseTaskParams): Promise<BrowserUseTaskResponse>
```

--------------------------------

### batchStart

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/scrape.md

Starts a batch scrape job for a list of URLs. It returns a jobId to track the job's progress.

```APIDOC
## batchStart()

### Description
Start a batch scrape job.

### Method
POST (assumed)

### Endpoint
/scrape/batch (assumed)

### Parameters
#### Request Body
- **urls** (string[]) - Required - Array of URLs to scrape
- **sessionOptions** (CreateSessionParams) - Optional - Browser session configuration
- **scrapeOptions** (ScrapeOptions) - Optional - Scrape options

### Request Example
```json
{
  "urls": [
    "https://example.com",
    "https://example.com/page2",
    "https://example.com/page3"
  ],
  "scrapeOptions": {
    "formats": ["markdown", "screenshot"]
  }
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the batch job
```

--------------------------------

### Create and Interact with a Sandbox

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

Demonstrates creating a sandbox, executing commands, managing files, watching directories, starting processes, and interacting with a terminal.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const sandbox = await client.sandboxes.create({
    imageName: "ubuntu-24-node",
    region: "us-west",
    cpu: 4,
    memoryMiB: 4096,
    diskMiB: 8192,
  });

  // Provide exactly one launch source:
  // snapshotName or imageName.
  // snapshotId requires snapshotName and imageId requires imageName.
  // cpu, memoryMiB, and diskMiB are only available for image launches.

  const version = await sandbox.exec("node -v");
  console.log(version.stdout.trim());

  await sandbox.files.writeText("/tmp/hello.txt", "hello from sdk");

  const content = await sandbox.files.readText("/tmp/hello.txt");
  console.log(content);

  const watch = await sandbox.files.watchDir(
    "/tmp",
    (event) => {
      if (event.type === "write") {
        console.log(event.name);
      }
    },
    {
      recursive: false,
    }
  );

  await sandbox.files.writeText("/tmp/watch-demo.txt", "watch me");
  await watch.stop();

  const proc = await sandbox.processes.start(
    "echo process-started && sleep 1 && echo process-finished",
    {
      runAs: "root",
    }
  );

  for await (const event of proc.stream()) {
    if (event.type === "stdout") {
      process.stdout.write(event.data);
    }
  }

  const terminal = await sandbox.terminal.create({
    command: "bash",
    cols: 120,
    rows: 30,
  });

  const connection = await terminal.attach();
  await connection.write("echo terminal-ok\n");

  for await (const event of connection.events()) {
    if (event.type === "output" && event.data.includes("terminal-ok")) {
      break;
    }
  }

  await connection.close();

  const snapshot = await sandbox.createMemorySnapshot();
  console.log(snapshot.snapshotId);

  await sandbox.stop();
};

main().catch(console.error);
```

--------------------------------

### Start and Wait for Gemini Computer Use Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Gemini Computer Use task and waits for its completion, returning the final result.

```typescript
async startAndWait(params: StartGeminiComputerUseTaskParams): Promise<GeminiComputerUseTaskResponse>
```

--------------------------------

### SandboxProcessesApi.start()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sandboxes.md

Starts a long-running process within the sandbox. It returns a handle to the process, allowing streaming of its output.

```APIDOC
## SandboxProcessesApi.start()

### Description
Start a long-running process within the sandbox.

### Method
`async`

### Signature
`processes.start(command: string, options?: SandboxExecOptions): Promise<SandboxProcessHandle>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **command** (string) - Required - The command to execute.
- **options** (SandboxExecOptions) - Optional - Execution options, such as `runAs`.

### Request Example
```typescript
const proc = await sandbox.processes.start(
  "echo process-started && sleep 1 && echo process-finished",
  { runAs: "root" }
);

for await (const event of proc.stream()) {
  if (event.type === "stdout") {
    process.stdout.write(event.data);
  }
}
```

### Response
#### Success Response
- **SandboxProcessHandle** - A handle to the started process, allowing interaction and streaming.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### ClaudeComputerUseService.start

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Claude Computer Use task with the specified parameters. This is the primary method for initiating a new Claude-based computer interaction task.

```APIDOC
## ClaudeComputerUseService.start

### Description
Starts a Claude Computer Use task with the specified parameters. This is the primary method for initiating a new Claude-based computer interaction task.

### Method
start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string, required): Starting URL
- **goal** (string, required): Task description
- **sessionOptions** (CreateSessionParams, optional): Session configuration
- **llm** (ClaudeComputerUseLlm, optional): Claude model
- **apiKey** (string, optional): Anthropic API key if using external Claude

### Request Example
```json
{
  "url": "http://example.com",
  "goal": "Analyze the page and provide a summary",
  "sessionOptions": {},
  "llm": "claude-opus-4-5",
  "apiKey": "sk-xxxxxxxx"
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the started job

#### Response Example
```json
{
  "jobId": "abcdef12-3456-7890-abcd-ef1234567890"
}
```
```

--------------------------------

### ScrapeService.start()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/scrape.md

Starts a new web scraping job. It takes a URL and optional configuration for session and scraping options.

```APIDOC
## ScrapeService.start()

### Description
Start a new scrape job.

### Method
POST

### Endpoint
/scrape/start

### Parameters
#### Request Body
- **url** (string) - Required - URL to scrape
- **sessionOptions** (CreateSessionParams) - Optional - Browser session configuration
- **scrapeOptions** (ScrapeOptions) - Optional - Scrape-specific options
  - **formats** (ScrapeFormat[]) - Optional - Output formats: "markdown", "html", "links", "screenshot"
  - **includeTags** (string[]) - Optional - HTML tags to include
  - **excludeTags** (string[]) - Optional - HTML tags to exclude
  - **onlyMainContent** (boolean) - Optional - Extract only main content
  - **waitFor** (number) - Optional - Wait time in milliseconds
  - **timeout** (number) - Optional - Timeout in milliseconds
  - **waitUntil** (ScrapeWaitUntil) - Optional - "load", "domcontentloaded", "networkidle"
  - **screenshotOptions** (ScreenshotOptions) - Optional - Screenshot configuration
  - **storageState** (StorageStateOptions) - Optional - Storage state (localStorage, sessionStorage)

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the created scrape job.

### Request Example
```json
{
  "url": "https://example.com",
  "scrapeOptions": {
    "formats": ["markdown", "html", "screenshot"],
    "waitUntil": "networkidle"
  }
}
```

### Response Example
```json
{
  "jobId": "generated-job-id"
}
```
```

--------------------------------

### Start Claude Computer Use Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a Claude Computer Use task. Requires a starting URL and goal, with optional session configurations, Claude model, or an Anthropic API key.

```typescript
async start(params: StartClaudeComputerUseTaskParams): Promise<StartClaudeComputerUseTaskResponse>
```

--------------------------------

### BrowserUseService.startAndWait

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Browser Use task and waits for its completion, returning the final result.

```APIDOC
## BrowserUseService.startAndWait

### Description
Starts a Browser Use task and waits for its completion, returning the final result.

### Method
startAndWait

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string, required): Starting URL
- **goal** (string, required): Task description
- **sessionOptions** (CreateSessionParams, optional): Session configuration
- **llm** (BrowserUseLlm, optional): LLM model
- **version** (BrowserUseVersion, optional): Agent version

### Request Example
```json
{
  "url": "http://example.com",
  "goal": "Summarize the page content",
  "sessionOptions": {},
  "llm": "gpt-4o",
  "version": "v1"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the completed task.

#### Response Example
```json
{
  "result": {
    "summary": "The page content is about..."
  }
}
```
```

--------------------------------

### Start a Sandbox Process

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sandboxes.md

Starts a long-running process within the sandbox. Use this to execute commands that require continuous operation or output streaming. The process can be configured to run as a specific user.

```typescript
async processes.start(command: string, options?: SandboxExecOptions): Promise<SandboxProcessHandle>
```

```typescript
const proc = await sandbox.processes.start(
  "echo process-started && sleep 1 && echo process-finished",
  { runAs: "root" }
);

for await (const event of proc.stream()) {
  if (event.type === "stdout") {
    process.stdout.write(event.data);
  }
}
```

--------------------------------

### batchFetch.start

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Starts a batch fetch job for multiple URLs. It allows configuration of output formats, browser settings, navigation options, and caching.

```APIDOC
## batchFetch.start

### Description
Starts a batch fetch job for multiple URLs. It allows configuration of output formats, browser settings, navigation options, and caching.

### Method
POST

### Endpoint
/web/batchFetch/start

### Parameters
#### Request Body
- **urls** (string[]) - Required - Array of URLs to fetch
- **outputs** (FetchOutputOptions) - Optional - Output format configuration
- **browser** (FetchBrowserOptions) - Optional - Browser configuration
- **navigation** (FetchNavigationOptions) - Optional - Navigation options
- **cache** (FetchCacheOptions) - Optional - Cache options

### Request Example
```json
{
  "urls": [
    "https://example.com",
    "https://example.org",
    "https://example.net"
  ],
  "outputs": {
    "formats": [
      { "type": "markdown" },
      { "type": "links" }
    ]
  }
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the created batch fetch job
```

--------------------------------

### startAndWait()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/crawl.md

Starts a crawl job and waits for its completion, optionally fetching all paginated results automatically.

```APIDOC
## startAndWait()

### Description
Start a crawl job and wait for completion with automatic pagination.

### Method
POST (assumed, based on 'start' operation)

### Endpoint
/crawl/startAndWait (assumed)

### Parameters
#### Request Body
- **params** (StartCrawlJobParams) - Required - Crawl job parameters (see `start()` method for details)
- **returnAllPages** (boolean) - Optional - Fetch all pages automatically; default is true

### Request Example
```json
{
  "params": {
    "url": "https://example.com",
    "limit": 50,
    "scrapeOptions": {
      "formats": ["markdown"]
    }
  },
  "returnAllPages": true
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the crawl job
- **status** (string) - The status of the crawl job
- **data** (array of CrawledPage objects) - An array of crawled page objects (potentially all pages if `returnAllPages` is true)

#### Response Example
```json
{
  "jobId": "crawl-job-id",
  "status": "completed",
  "data": [
    {
      "url": "https://example.com/page1",
      "status": "completed",
      "markdown": "# Page 1 Content"
    },
    {
      "url": "https://example.com/page2",
      "status": "completed",
      "markdown": "# Page 2 Content"
    }
  ]
}
```
```

--------------------------------

### POST /crawl

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/endpoints.md

Starts a new crawl job. This endpoint initiates a web crawling task, specifying a starting URL and crawl limitations.

```APIDOC
## POST /crawl

### Description
Start a crawl job.

### Method
POST

### Endpoint
/crawl

### Parameters
#### Request Body
- **method** (POST) - Required - 
- **body** (StartCrawlJobParams) - Required - `{ url: "...", limit: 100, ... }`

### Response
#### Success Response (200)
- **Response** (StartCrawlJobResponse) - Description
```

--------------------------------

### BrowserUseService.start

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Browser Use task with the specified parameters. This is the primary method for initiating a new browser automation task.

```APIDOC
## BrowserUseService.start

### Description
Starts a Browser Use task with the specified parameters. This is the primary method for initiating a new browser automation task.

### Method
start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - Starting URL
- **goal** (string) - Required - Task description
- **sessionOptions** (CreateSessionParams) - Optional - Session configuration
- **llm** (BrowserUseLlm) - Optional - LLM model
- **version** (BrowserUseVersion) - Optional - Agent version

### Request Example
```json
{
  "url": "http://example.com",
  "goal": "Summarize the page content",
  "sessionOptions": {},
  "llm": "gpt-4o",
  "version": "v1"
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The ID of the started job

#### Response Example
```json
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000"
}
```
```

--------------------------------

### ClaudeComputerUseService.startAndWait

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a Claude Computer Use task and waits for its completion, returning the final result.

```APIDOC
## ClaudeComputerUseService.startAndWait

### Description
Starts a Claude Computer Use task and waits for its completion, returning the final result.

### Method
startAndWait

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string, required): Starting URL
- **goal** (string, required): Task description
- **sessionOptions** (CreateSessionParams, optional): Session configuration
- **llm** (ClaudeComputerUseLlm, optional): Claude model
- **apiKey** (string, optional): Anthropic API key if using external Claude

### Request Example
```json
{
  "url": "http://example.com",
  "goal": "Analyze the page and provide a summary",
  "sessionOptions": {},
  "llm": "claude-opus-4-5",
  "apiKey": "sk-xxxxxxxx"
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the completed task.

#### Response Example
```json
{
  "result": {
    "analysis": "The page content analysis is..."
  }
}
```
```

--------------------------------

### Start a HyperAgent Task

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Initiates a new AI agent task for browser automation. Specify the starting URL, the goal, and optionally configure the LLM, agent version, and session settings.

```typescript
async start(params: StartHyperAgentTaskParams): Promise<StartHyperAgentTaskResponse>
```

```typescript
const task = await client.agents.hyperAgent.start({
  url: "https://example.com",
  goal: "Find and click the 'Sign Up' button, fill in the email field with test@example.com",
  llm: "gpt-5",
  version: "1.1.0",
});
console.log(task.jobId);
```

--------------------------------

### Start and Wait for Batch Fetch Job

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Starts a batch fetch job and waits for its completion, optionally retrieving all pages of results. This is a convenience method for synchronous-like batch processing.

```typescript
async batchFetch.startAndWait(params: StartBatchFetchJobParams, returnAllPages?: boolean): Promise<BatchFetchJobResponse>
```

--------------------------------

### batchFetch.startAndWait

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Starts a batch fetch job and waits for its completion before returning the results. Optionally returns all pages of results.

```APIDOC
## batchFetch.startAndWait

### Description
Starts a batch fetch job and waits for its completion before returning the results. Optionally returns all pages of results.

### Method
POST

### Endpoint
/web/batchFetch/startAndWait

### Parameters
#### Request Body
- **urls** (string[]) - Required - Array of URLs to fetch
- **outputs** (FetchOutputOptions) - Optional - Output format configuration
- **browser** (FetchBrowserOptions) - Optional - Browser configuration
- **navigation** (FetchNavigationOptions) - Optional - Navigation options
- **cache** (FetchCacheOptions) - Optional - Cache options
- **returnAllPages** (boolean) - Optional - If true, returns all pages of results; otherwise, returns the first page.

### Response
#### Success Response (200)
- **results** (array) - An array of fetch results
```

--------------------------------

### Start and Wait for Agent Task, Then Handle Failures

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/errors.md

This code starts a new agent task and waits for its completion. If the task fails, it logs the error and iterates through the step history to help diagnose the issue.

```typescript
const result = await client.agents.hyperAgent.startAndWait({
  url: "https://example.com",
  goal: "Task description",
  maxSteps: 50,
});

if (result.status === "failed") {
  console.error("Agent failed:", result.error);
  // Examine step history to understand what went wrong
  result.data?.steps?.forEach((step, i) => {
    console.log(`Step ${i}:`, step.action, step.result);
  });
}
```

--------------------------------

### get()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sandboxes.md

Retrieve details of a specific sandbox by its ID.

```APIDOC
## get()

### Description
Retrieve details of a specific sandbox by its ID.

### Method
`GET`

### Endpoint
`/sandboxes/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - Sandbox ID

### Response
#### Success Response (200)
- **SandboxDetail** - An object containing detailed information about the sandbox.
```

--------------------------------

### Start Crawl Job and Wait for Completion

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/crawl.md

Starts a crawl job and automatically waits for it to complete, optionally fetching all paginated results. Simplifies the process of running a crawl and getting all its data.

```typescript
async startAndWait(params: StartCrawlJobParams, returnAllPages?: boolean): Promise<CrawlJobResponse>
```

```typescript
const result = await client.crawl.startAndWait({
  url: "https://example.com",
  limit: 50,
  scrapeOptions: {
    formats: ["markdown"],
  },
});

console.log(`Crawled ${result.data?.length} pages`);
result.data?.forEach(page => {
  console.log(page.url);
  console.log(page.markdown);
});
```

--------------------------------

### crawl.start

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Starts a new web crawl job. This is an asynchronous operation that initiates the crawling process.

```APIDOC
## crawl.start

### Description
Starts a web crawl job.

### Method
POST

### Endpoint
/crawl/start

### Parameters
#### Request Body
- **params** (WebCrawlStartParams) - Required - Parameters for starting a web crawl.

### Response
#### Success Response (200)
- **result** (WebCrawlStartResponse) - The response object containing details about the started crawl job.
```

--------------------------------

### Using Volumes with Sandboxes

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/volumes-extensions.md

Demonstrates how to create a volume, mount it into a sandbox with read-write or read-only access, persist data, and access it from another sandbox.

```typescript
const volume = await client.volumes.create({ name: "workspace-data" });

const sandbox = await client.sandboxes.create({
  imageName: "node",
  mounts: {
    "/workspace/cache": {
      id: volume.id,
      type: "rw",        // read-write access
      shared: true,      // can be shared with other sandboxes
    },
  },
});

// Write to the mounted volume
await sandbox.files.writeText("/workspace/cache/data.json", '{"key":"value"}');

// Data persists in the volume after sandbox stops
await sandbox.stop();

// Create another sandbox with the same volume
const sandbox2 = await client.sandboxes.create({
  imageName: "node",
  mounts: {
    "/workspace/cache": {
      id: volume.id,
      type: "ro",        // read-only access
      shared: true,
    },
  },
});

// Access persisted data
const data = await sandbox2.files.readText("/workspace/cache/data.json");
```

--------------------------------

### GET /web/fetch/batch/{jobId}

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/endpoints.md

Retrieves the results of a previously started batch fetch job using its ID.

```APIDOC
## GET /web/fetch/batch/{jobId}

### Description
Get batch fetch results.

### Method
GET

### Endpoint
/web/fetch/batch/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the batch fetch job.
```

--------------------------------

### ExtensionService.list

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/volumes-extensions.md

Lists all available browser extensions. This provides an overview of all installed extensions.

```APIDOC
## GET /extensions

### Description
List all extensions.

### Method
GET

### Endpoint
/extensions

### Response
#### Success Response (200)
- **extensions** (array) - Array of Extension objects

### Response Example
```json
{
  "extensions": [
    {
      "id": "ext-abc",
      "name": "Custom Blocker",
      "version": "1.0"
    }
  ]
}
```
```

--------------------------------

### Start a Scrape Job

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/scrape.md

Initiates a new web scraping job. Configure output formats, content inclusion/exclusion, and waiting conditions.

```typescript
async start(params: StartScrapeJobParams): Promise<StartScrapeJobResponse>
```

```typescript
const job = await client.scrape.start({
  url: "https://example.com",
  scrapeOptions: {
    formats: ["markdown", "html", "screenshot"],
    waitUntil: "networkidle",
  },
});
console.log(job.jobId);
```

--------------------------------

### Get Scrape Job Status

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/scrape.md

Retrieves the current status of a previously started scrape job using its ID.

```typescript
async getStatus(id: string): Promise<ScrapeJobStatusResponse>
```

```typescript
const status = await client.scrape.getStatus("job-id");
console.log(status.status);
```

--------------------------------

### Get HyperAgent Task Status

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Retrieves the current status of a previously started HyperAgent task using its unique job ID.

```typescript
async getStatus(id: string): Promise<HyperAgentTaskStatusResponse>
```

--------------------------------

### Full Workflow Example

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/computer-action.md

Demonstrates a complete workflow using the Computer Action API, including session creation, navigation, user input simulation, and capturing screenshots. Requires Playwright and a connected session.

```typescript
const session = await client.sessions.create();
const sessionId = session.id;

// Take initial screenshot
let screenshot = await client.computerAction.screenshot(sessionId);
console.log("Initial state captured");

// Navigate to URL using Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = await browser.newPage();
await page.goto("https://example.com");

// Take screenshot after navigation
screenshot = await client.computerAction.screenshot(sessionId);

// Click on an element using computer action
await client.computerAction.click(sessionId, 500, 300);

// Type into form
await client.computerAction.typeText(sessionId, "search query");

// Press enter
await client.computerAction.pressKeys(sessionId, ["Enter"]);

// Wait a bit for response
await new Promise(r => setTimeout(r, 2000));

// Capture result screenshot
screenshot = await client.computerAction.screenshot(sessionId);

await client.sessions.stop(sessionId);
```

--------------------------------

### crawl.startAndWait

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Starts a web crawl job and waits for its completion before returning the results.

```APIDOC
## crawl.startAndWait

### Description
Start web crawl and wait for completion.

### Method
POST

### Endpoint
/crawl/startAndWait

### Parameters
#### Request Body
- **params** (WebCrawlStartParams) - Required - Parameters for starting a web crawl.

### Response
#### Success Response (200)
- **result** (WebCrawlJobResponse) - The response object containing the final results of the completed crawl job.
```

--------------------------------

### StartExtractJobParams Interface

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/types.md

Parameters required to start a data extraction job. A schema or prompt must be provided to guide the extraction process.

```typescript
interface StartExtractJobParams {
  url: string;
  schema?: ZodSchema | JSONSchema;
  prompt?: string;
  sessionOptions?: CreateSessionParams;
  scrapeOptions?: ScrapeOptions;
}
```

--------------------------------

### Get Batch Scrape Job Status

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/scrape.md

Retrieves the current status of a previously started batch scrape job using its unique ID.

```typescript
async getStatus(id: string): Promise<BatchScrapeJobStatusResponse>
```

--------------------------------

### create()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sandboxes.md

Create a new sandbox instance. Supports both image-based and snapshot-based creation with various configuration options.

```APIDOC
## create()

### Description
Create a new sandbox instance. Supports both image-based and snapshot-based creation with various configuration options.

### Method
`POST` (Assumed based on creation operation)

### Endpoint
`/sandboxes` (Assumed based on common REST patterns)

### Parameters
#### Request Body
- **imageName** (string) - Required - Name of the image (e.g., "ubuntu-24-node")
- **imageId** (string) - Optional - Specific image ID
- **snapshotName** (string) - Required - Name of the snapshot (use for snapshot-based creation)
- **snapshotId** (string) - Optional - Specific snapshot ID (use for snapshot-based creation)
- **cpu** (number) - Optional - Number of CPU cores (must be positive integer)
- **memoryMiB** (number) - Optional - Memory in MiB (must be positive integer)
- **diskMiB** (number) - Optional - Disk space in MiB (must be positive integer)
- **region** (SessionRegion) - Optional - Deployment region
- **enableRecording** (boolean) - Optional - Enable recording
- **exposedPorts** (SandboxExposeParams[]) - Optional - Ports to expose with auth
- **mounts** (Record<string, SandboxVolumeMount>) - Optional - Volume mounts
- **timeoutMinutes** (number) - Optional - Session timeout

### Request Example
```json
{
  "imageName": "ubuntu-24-node",
  "region": "us-west",
  "cpu": 4,
  "memoryMiB": 4096,
  "diskMiB": 8192
}
```

### Response
#### Success Response (200)
- **SandboxHandle** - An object representing the created sandbox with methods to interact with it.
```

--------------------------------

### startAndWait()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/agents.md

Starts a HyperAgent task and blocks until the task is completed, returning the full task result. This is a convenience method for synchronous task execution.

```APIDOC
## startAndWait()

### Description
Start a HyperAgent task and wait for completion.

### Method
POST

### Endpoint
/agents/hyperagent/startAndWait

### Parameters
#### Request Body
- **url** (string, required): Starting URL for the agent
- **goal** (string, required): Description of the task to perform
- **sessionOptions** (CreateSessionParams, optional): Browser session configuration
- **llm** (HyperAgentLlm, optional): LLM model to use
- **version** (HyperAgentVersion, optional): Agent version ("0.8.0" or "1.1.0")
- **maxSteps** (number, optional): Maximum action steps

### Response
#### Success Response (200)
- **result** - The full result of the task
- **status** (string) - The final status of the task
- **stepHistory** - A history of the agent's actions during the task

### Request Example
```json
{
  "url": "https://example.com",
  "goal": "Add an item to the shopping cart",
  "llm": "gpt-5.5"
}
```
```

--------------------------------

### GET /extract/{jobId}

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/endpoints.md

Retrieves the result of a previously started extract job using its unique job ID. Use this to fetch the completed extraction data.

```APIDOC
## GET /extract/{jobId}

### Description
Get extract job result.

### Method
GET

### Endpoint
/extract/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The unique identifier of the extract job.

### Response
#### Success Response (200)
- **ExtractJobResponse** (object) - The response object containing the extract job results.

### Response Example
```json
{
  "example": "ExtractJobResponse"
}
```
```

--------------------------------

### start()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/extract.md

Initiates a new data extraction job. Requires either a schema or a prompt to define the extraction structure. Supports configuration for browser sessions and scraping options.

```APIDOC
## start()

### Description
Start a new data extraction job. This method takes parameters to define the URL, the desired output structure (via schema or prompt), and optional session/scraping configurations.

### Method
`async start(params: StartExtractJobParams): Promise<StartExtractJobResponse>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`params` (StartExtractJobParams, required): Parameters for the extraction job.
- `url` (string, required): URL to extract data from.
- `schema` (ZodSchema | JSONSchema, optional): Zod schema or JSON schema defining output structure.
- `prompt` (string, optional): Natural language description of what to extract.
- `sessionOptions` (CreateSessionParams, optional): Browser session configuration.
- `scrapeOptions` (ScrapeOptions, optional): Scrape options.

**Note**: Either `schema` or `prompt` must be provided.

### Request Example
```typescript
// Example with JSON Schema
const job = await client.extract.start({
  url: "https://example.com/product",
  schema: {
    type: "object",
    properties: {
      title: { type: "string" },
      price: { type: "number" },
      description: { type: "string" },
    },
    required: ["title", "price"],
  },
});
console.log(job.jobId);

// Example with Zod schema
import { z } from "zod";
const ProductSchema = z.object({
  title: z.string(),
  price: z.number(),
  description: z.string(),
  inStock: z.boolean(),
});
const job = await client.extract.start({
  url: "https://example.com/product",
  schema: ProductSchema,
});

// Example with prompt
const job = await client.extract.start({
  url: "https://example.com",
  prompt: "Extract the main article title, publication date, and author information",
});
```

### Response
#### Success Response (200)
`StartExtractJobResponse` with `jobId` (string).

#### Response Example
```json
{
  "jobId": "extract-job-id-123"
}
```
```

--------------------------------

### create()

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sessions.md

Create a new browser session with optional configuration parameters.

```APIDOC
## create()

### Description
Create a new browser session.

### Method
POST

### Endpoint
/sessions

### Parameters
#### Request Body
- **params** (CreateSessionParams) - Optional - Configuration parameters for the new session
  - **profile** (SessionProfile) - Optional - Browser profile to use with the session
  - **launchState** (SessionLaunchState) - Optional - Initial launch configuration
    - **useProxy** (boolean) - Optional
    - **solveCaptchas** (boolean) - Optional
    - **adblock** (boolean) - Optional

### Request Example
```json
{
  "launchState": {
    "useProxy": true,
    "solveCaptchas": true,
    "adblock": true
  }
}
```

### Response
#### Success Response (200)
- **SessionDetail** - Details of the created session, including wsEndpoint, computerActionEndpoint, and webdriverEndpoint.
  - **id** (string)
  - **wsEndpoint** (string)
  - **computerActionEndpoint** (string)
  - **webdriverEndpoint** (string)
  - **status** (string)

#### Response Example
```json
{
  "id": "session-id",
  "wsEndpoint": "ws://example.com/session-id",
  "computerActionEndpoint": "http://example.com/session-id/actions",
  "webdriverEndpoint": "http://example.com/session-id/webdriver",
  "status": "running"
}
```
```

--------------------------------

### Start Web Crawl Job

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/web.md

Initiates a web crawl job. Use this to begin a new crawling task.

```typescript
async crawl.start(params: WebCrawlStartParams): Promise<WebCrawlStartResponse>
```

--------------------------------

### Create Browser Session

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/sessions.md

Creates a new browser session with optional launch configurations. Use this to start a new automated browsing instance.

```typescript
const session = await client.sessions.create({
  launchState: {
    useProxy: true,
    solveCaptchas: true,
    adblock: true,
  }
});

console.log(session.id);
console.log(session.wsEndpoint);
```

--------------------------------

### Get Extract Job Status

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/extract.md

Retrieves the current status of a previously started data extraction job using its unique job ID. The status can be 'pending', 'running', 'completed', or 'failed'.

```typescript
const status = await client.extract.getStatus("extract-job-id");
console.log(status.status);
```

--------------------------------

### List All Browser Extensions

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/volumes-extensions.md

Retrieves a list of all installed browser extensions. The response includes the name and ID of each extension.

```typescript
const result = await client.extensions.list();
result.extensions.forEach(ext => {
  console.log(ext.name, ext.id);
});
```

--------------------------------

### Start a New Crawl Job

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/api-reference/crawl.md

Initiates a new crawl job with specified parameters like URL, limits, and allowed domains. Use this to begin a crawl and get a job ID for tracking.

```typescript
async start(params: StartCrawlJobParams): Promise<StartCrawlJobResponse>
```

```typescript
const job = await client.crawl.start({
  url: "https://example.com",
  limit: 100,
  allowedDomains: ["example.com"],
  scrapeOptions: {
    formats: ["markdown", "links"],
  },
});
console.log(job.jobId);
```

--------------------------------

### Configure Session Launch State

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/configuration.md

Create a new session with specific launch configurations. This example demonstrates enabling proxy, captcha solving, ad blocking, and setting screen resolution.

```typescript
const session = await client.sessions.create({
  launchState: {
    useProxy: true,
    solveCaptchas: true,
    adblock: true,
    acceptCookies: true,
    screen: {
      width: 1920,
      height: 1080,
    },
  },
});
```

--------------------------------

### Use Hyperbrowser SDK with Puppeteer

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

This example shows how to integrate the Hyperbrowser SDK with Puppeteer for browser automation. It covers session creation, navigation, and logging page titles. Ensure Puppeteer-core and dotenv are installed, and your HYPERBROWSER_API_KEY is configured.

```typescript
import { connect } from "puppeteer-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create();

  try {
    const browser = await connect({
      browserWSEndpoint: session.wsEndpoint,
      defaultViewport: null,
    });

    const [page] = await browser.pages();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });

    await page.goto("https://example.com");
    console.log("Page 2:", await page.title());
    await page.evaluate(() => {
      console.log("Page 2:", document.title);
    });

    await page.goto("https://apple.com");
    console.log("Page 3:", await page.title());
    await page.evaluate(() => {
      console.log("Page 3:", document.title);
    });

    await page.goto("https://google.com");
    console.log("Page 4:", await page.title());
    await page.evaluate(() => {
      console.log("Page 4:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

```

--------------------------------

### GET /volume

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/endpoints.md

Lists all available volumes. This operation is accessible via the SDK's `client.volumes.list` method.

```APIDOC
## GET /volume

### Description
Lists all available volumes.

### Method
GET

### Endpoint
/volume

### Response
#### Success Response (200)
* **VolumeListResponse** (object) - A list of volumes.
```

--------------------------------

### Use Hyperbrowser SDK with Playwright

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/README.md

This example demonstrates how to use the Hyperbrowser SDK with Playwright to create a browser session, navigate to multiple websites, and log page titles. Ensure you have Playwright and dotenv installed, and your HYPERBROWSER_API_KEY is set in your environment variables.

```typescript
import { chromium } from "playwright-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create();

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);

    const defaultContext = browser.contexts()[0];
    const page = await defaultContext.newPage();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });

    await page.goto("https://example.com");
    console.log("Page 2:", await page.title());
    await page.evaluate(() => {
      console.log("Page 2:", document.title);
    });

    await page.goto("https://apple.com");
    console.log("Page 3:", await page.title());
    await page.evaluate(() => {
      console.log("Page 3:", document.title);
    });

    await page.goto("https://google.com");
    console.log("Page 4:", await page.title());
    await page.evaluate(() => {
      console.log("Page 4:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

```

--------------------------------

### POST /extract

Source: https://github.com/hyperbrowserai/node-sdk/blob/main/_autodocs/endpoints.md

Starts a new extraction job by providing a URL and schema. This is the entry point for initiating data extraction processes.

```APIDOC
## POST /extract

### Description
Start an extract job.

### Method
POST

### Endpoint
/extract

### Parameters
#### Request Body
- **body** (StartExtractJobParams) - Required - The parameters for starting an extract job, including the URL and schema.

### Request Example
```json
{
  "url": "...",
  "schema": {...}
}
```

### Response
#### Success Response (200)
- **StartExtractJobResponse** (object) - The response object indicating the start of the job.

### Response Example
```json
{
  "example": "StartExtractJobResponse"
}
```
```