BrowserHive Capture API (1.0.0)

Target URL to capture

Display labels (used for filename)

Correlation ID provided by the client for tracking

Capture format flags. At least one must be true.

Value to send as the upstream Accept-Language header for this capture only. Useful for sites whose content varies by language (locale-redirecting corporate top pages, search engines, Wikipedia, etc.).

Format follows IETF BCP 47 quality-list syntax, e.g. ja-JP,ja;q=0.9,en-US;q=0.8,en;q=0.7.

When omitted, no Accept-Language header is set explicitly and the upstream Chromium uses its built-in default (controlled by its --lang startup flag / OS locale).

Run banner / modal dismissal before capturing. Removes known consent-management-platform overlays and large fixed/sticky overlays via heuristic.

Two shapes are accepted:

• boolean — false (or omitted) skips dismissal entirely; true is equivalent to { "useDefaults": true } (the curated CMP list plus the default heuristic).
• DismissSpec — inline customization. Use extraSelectors to add page-specific overlay selectors, excludeFrameworks to suppress a noisy default, or heuristic.enabled: false to disable the size/z-index fallback.

When enabled, the server log line for the completed task includes a dismissReport:

{
  "msg": "Task completed",
  "url": "https://www.theguardian.com",
  "dismissReport": {
    "framework": "Sourcepoint",
    "removedSelectors": ["[id^=\"sp_message_container\"]"],
    "removedOverlayCount": 1
  }
}

• framework — matched CMP name, "custom" when only an extraSelectors entry fired, "heuristic" when only the fallback fired, or null when nothing matched.
• removedSelectors — exact CSS selectors whose elements were removed in the CMP-selector pass (includes both default-CMP and custom extraSelectors matches).
• removedOverlayCount — number of elements removed by the heuristic pass (fixed/sticky elements with high z-index covering ≥minViewportCoverageRatio of the viewport, excluding semantic landmarks).

By default best-effort: dismissal failures (in-page evaluate timeout, the page.evaluate promise rejecting, or an invalid CSS selector in extraSelectors raising SyntaxError) are swallowed and the offending entry is skipped, so a malformed page or a typo cannot fail the capture.

Set dismissBanners.failOnError: true to opt out — failures then fail the entire capture (status: "failed" or "timeout" in the worker log) and dismissReport is not present on the result; inspect errorDetails instead. The failure is treated like any other capture failure for retry accounting (consumes one slot of --max-retry-count).

Per-request browser viewport in CSS pixels. When provided, page.setViewport is called with these dimensions before navigating to the target URL — useful for sites whose layout varies by viewport size (responsive top pages, mobile-only content) or for capturing at a specific resolution.

When omitted, the server-side default applies (configured via --viewport-width / --viewport-height / BROWSERHIVE_VIEWPORT_*; the built-in default is 1280 × 800).

Bounds (1–7680 × 1–4320) cover up to 8K rendering and exist only as a sanity guard against runaway memory use in Chromium — typical values are 1280 × 800 (desktop default), 1920 × 1080 (Full HD), or 375 × 667 (iPhone SE).

When true, the PNG / WebP screenshot extends below the viewport to capture the full document height (Chromium scrolls and stitches the result). When false or omitted, only the viewport-sized region is captured.

When omitted, the server-side default applies (configured via --screenshot-full-page / BROWSERHIVE_SCREENSHOT_FULL_PAGE; the built-in default is false).

Has no effect on the html / links formats.