> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser resources

> Use pages, files, downloads, dialogs, permissions, recordings, events, and artifacts around managed browser runs.

Browser resources are the evidence and control-plane objects around a managed browser. They are how browser work becomes inspectable, reviewable, and useful to another process.

| Resource    | Use it for                                                | Common surface |
| ----------- | --------------------------------------------------------- | -------------- |
| Pages       | Inspect active and open browser pages.                    | SDK, CLI, REST |
| Files       | Stage browser-readable files or retrieve generated files. | SDK, REST      |
| Downloads   | Capture files produced by a site.                         | SDK, CLI, REST |
| Dialogs     | Accept or dismiss JavaScript dialogs.                     | SDK, CLI, REST |
| Permissions | Grant, deny, clear, or reset browser permissions.         | SDK, REST      |
| Recordings  | Replay a browser run after it finishes.                   | SDK, CLI, REST |
| Events      | Follow runtime activity over time.                        | SDK, REST      |

Browser-agent workflows surface important resources through `result.artifacts`, `result.steps`, status, and browser IDs. Use direct resource APIs when your application needs lower-level control.

## Common recipes

### Upload a file

```ts theme={null}
const file = await browser.files.createFromPath("./contract.pdf", {
  name: "contract.pdf",
});

await browser.playwright.execute({
  code: `
    const inputPath = await files.path("${file.id}");
    await page.getByLabel("Upload").setInputFiles(inputPath);
  `,
});
```

Inside browser-code execution, use `files.path(fileId)` to resolve a staged file to a runtime-local path. Prefer staged files over embedding large data directly into prompts.

### Save a download

```ts theme={null}
const downloads = await browser.downloads.list();
const firstDownload = downloads.data[0];

if (firstDownload) {
  await browser.downloads.save(firstDownload.id, "./downloaded-report.pdf");
}
```

Use `maxBytes` and `overwrite` in production:

```ts theme={null}
await browser.downloads.save(firstDownload.id, "./downloads/report.pdf", {
  maxBytes: 25_000_000,
  overwrite: true,
});
```

### Handle a dialog

```ts theme={null}
const dialogs = await browser.dialogs.list({ status: "open" });
const dialog = dialogs.data[0];

if (dialog?.type === "confirm") {
  await browser.dialogs.dismiss(dialog.id);
}
```

Handle dialogs deliberately. A confirm dialog can represent a destructive or irreversible action.

### Grant and clear permissions

```ts theme={null}
await browser.permissions.grant({
  origin: "https://example.com",
  permissions: ["geolocation"],
  geolocation: { latitude: 37.7749, longitude: -122.4194 },
});

await browser.permissions.clear({ origin: "https://example.com" });
```

Grant permissions only for the origin that needs them, then clear overrides when the workflow is done.

### Inspect events

```ts theme={null}
const events = await browser.events({
  category: "browser",
  limit: 50,
});

console.log(events.data);
```

Use events and recordings together when a run needs an audit trail.

### Download recording evidence

```ts theme={null}
const segments = await browser.recordings.segments({ limit: 5 });
const segment = segments.data[0];

if (segment) {
  await browser.recordings.download(segment.id, "./recordings", {
    overwrite: true,
  });
}
```

Recordings require `recording: true` when the browser is created.

### Inspect pages

```ts theme={null}
const pages = await browser.pages();
const active = pages.find((page) => page.active);

console.log(active?.url, active?.title);
```

Use page IDs only when targeting a known non-active page. Ordinary browser-code execution should use the active page.

### Check blockers and CAPTCHA state

```ts theme={null}
const status = await browser.status();
const captcha = await browser.captcha.status();

return {
  readiness: status.readiness,
  blocker: status.blocker?.state,
  captcha: captcha.captcha?.state,
};
```

Return blocker evidence when a workflow cannot continue. Do not describe CAPTCHA or WAF handling as guaranteed access.

Reference: [SDK resources reference](/reference/sdk-resources-reference), [SDK browser reference](/reference/sdk-browser-reference), and [API reference](/api-reference/overview).