# PageBolt

> PageBolt is a web capture API platform for developers. One API key gives you access to 11 endpoints: screenshot capture, PDF generation, OG image creation, multi-step browser automation (sequences), video recording, agent page observation, page inspection, content extraction, accessibility audits, ARIA tree capture, and visual diffing — plus an MCP server for AI coding assistants.

## What PageBolt Does

PageBolt lets developers capture, render, and automate the web through a simple REST API. Instead of managing headless browsers, Puppeteer scripts, or multiple vendor integrations, you make a single POST request and get back screenshots, PDFs, OG images, or structured browser automation results.

### 11 APIs + MCP

1. **Screenshot API** — Capture full-page or viewport screenshots in PNG, JPEG, or WebP. Supports 25+ device presets (iPhone, Pixel, MacBook, etc.), dark mode, ad blocking, cookie/chat widget blocking, geolocation emulation, custom headers/cookies, and metadata extraction.
2. **PDF Generation API** — Convert any URL or HTML into a PDF. Configurable page size, margins, headers/footers, and print backgrounds.
3. **OG Image API** — Generate Open Graph social preview images from built-in or custom HTML templates with dynamic text and colors.
4. **Sequence Builder API** — Define multi-step browser automations: navigate, click, fill forms, wait for selectors, take screenshots or PDFs at any step. Useful for capturing authenticated pages or multi-page flows.
5. **Video Recording API** — Record professional demo videos of multi-step browser automation with cursor highlighting, click effects, step notes (guided tour annotations), optional Audio Guide with per-step narration text, 10+ professional voices, speaking styles, browser frame chrome (macOS/Windows/minimal), background gradients, and configurable pace. Outputs MP4, WebM, or GIF. Each video costs 3 API requests.
6. **Agent Observation API** (`POST /api/v1/observe`) — The agent perception endpoint. In one page load, returns a compact, token-budgeted observation: id-indexed interactive elements (role, name, CSS selector, state), a heuristic page-type classification (login, signup, search, article, form, generic), and grouped suggested actions — plus optional readable content (Markdown), ARIA tree, and a screenshot. The headless perception layer for the agentic web: turns any un-instrumented URL into agent-ready structure, far more token-efficient than a raw screenshot or full DOM.
7. **Page Inspection API** — Inspect any web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector. Ideal for AI agents to discover page elements before automating with Sequences or Video.
8. **Content Extraction API** (`POST /api/v1/extract`) — Extract clean, structured content from any URL: readable text, title, metadata, and links. Renders JavaScript first, so it works on SPAs and dynamic pages. Ideal for giving AI agents verified page content instead of raw HTML.
9. **Accessibility Audit API** (`POST /api/v1/audit`) — Run an axe-core accessibility audit on any URL and get back WCAG violations with severity, affected elements, and remediation guidance. Useful for CI gates and compliance reporting.
10. **ARIA Tree API** (`POST /api/v1/aria`) — Capture the accessibility (ARIA) tree of a page — the semantic structure assistive technologies and AI agents see. Accepts a URL or raw HTML.
11. **Visual Diff API** (`POST /api/v1/diff`) — Pixel-compare two URLs (or two HTML snapshots) and get the percentage changed, changed-pixel count, and a highlighted diff image. Built for visual regression testing and detecting unexpected UI changes between deploys.
12. **MCP Server** — A built-in Model Context Protocol server that lets AI coding assistants (Claude Desktop, Cursor, Windsurf) call PageBolt directly from your IDE.

## Key Differentiators

- **Interactive Playground**: Test the APIs directly from the dashboard at https://pagebolt.dev/dashboard — no API key or code required.
- **11 APIs for the price of 1**: Most competitors offer only screenshot capture. PageBolt includes screenshots, PDFs, OG images, sequences, video recording, agent page observation, page inspection, content extraction, accessibility audits, ARIA trees, visual diffing, and MCP in every plan.
- **30+ parameters per request**: Device presets, ad blocking, cookie banner blocking, chat widget blocking, dark mode, geolocation, custom CSS injection, JavaScript execution, and more.
- **Metadata extraction**: Every screenshot request can optionally return page title, description, and HTTP status code alongside the image.
- **AI-native**: Built-in MCP server so AI coding assistants can use PageBolt without writing integration code.
- **No surprise overages**: By default, hitting your monthly limit returns a clear 402 error — you are never surprise-billed. Paid plans can optionally enable overage and keep a prepaid balance, so production traffic keeps flowing past the limit, charged per request from that balance.

## Pricing

All plans include access to all six APIs.

| Plan | Price | Monthly Requests | Rate Limit |
|------|-------|-----------------|------------|
| Free | $0/mo | 100 | 10 req/min |
| Starter | $29/mo | 5,000 | 60 req/min |
| Growth | $79/mo | 25,000 | 120 req/min |
| Scale | $199/mo | 100,000 | 300 req/min |

Starter and Growth plans include a 14-day free trial. No credit card required for the Free plan.

## Quick Start

1. Sign up at https://pagebolt.dev/signup
2. Get your API key from the dashboard
3. Make a POST request:

```
POST https://pagebolt.dev/api/v1/screenshot
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Body: { "url": "https://example.com", "format": "webp", "blockAds": true }
```

## Links

- Homepage: https://pagebolt.dev
- API Playground: https://pagebolt.dev/dashboard (test all APIs interactively)
- API Documentation: https://pagebolt.dev/docs
- Changelog: https://pagebolt.dev/changelog
- Sign Up: https://pagebolt.dev/signup
- Login: https://pagebolt.dev/login
- Terms of Service: https://pagebolt.dev/terms
- Privacy Policy: https://pagebolt.dev/privacy
- Support: support@pagebolt.dev

## Style API (NEW)

POST to `/api/v1/style` to apply styling (frame, background, shadow, theme) to an existing screenshot. Accepts a base64-encoded image and returns the styled result. **Does not count toward monthly quota** — image processing only, no browser needed. Use this to iterate on styles without recapturing.

### Style Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image | string | Yes | Base64-encoded image (PNG/JPEG/WebP, max 10MB) |
| format | string | No | Output format: png, jpeg, webp. Default: png |
| style | object | Yes | Style config — use `theme` or individual properties |
| style.theme | string | No | Preset: notion, paper, vercel, glass, ocean, sunset, linear, arc, glassDark, neonBlue, neonPurple, neonGreen, spotlight, lavender, ember, dots, grid |
| style.frame | string | No | macos, windows, minimal, none |
| style.background | string | No | ocean, sunset, forest, midnight, aurora, lavender, peach, arctic, ember, slate, neon, glass, solid, spotlight, dots, grid, noise, none |
| style.shadow | string | No | none, xs, sm, md, lg, xl, 2xl |
| style.padding | integer | No | 0–120 pixels. Default: 40 |
| style.borderRadius | integer | No | 0–40 pixels. Default: 12 |
| style.bgColor | string | No | Hex color for solid background, e.g. #1e3a5f |
| response_type | string | No | "json" for base64 JSON response. Default: binary image |

## Video Recording API

POST to `/api/v1/video` with a `steps` array (same actions as sequences: navigate, click, fill, select, hover, scroll, wait, wait_for, evaluate — but no screenshot/pdf). Returns a video of those steps being performed with professional effects.

### Video Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| steps | array | (required) | Array of step objects |
| async | boolean | false | Return 202 + job_id immediately instead of blocking. Result is delivered as a hosted video URL. Poll GET /api/v1/jobs/:id, or register a webhook (POST /api/v1/webhooks) for job.completed / job.failed events. Quota is charged only on success; max 5 pending jobs per account. |
| viewport | object | 1280×720 | {width, height} |
| format | string | mp4 | mp4, webm, or gif |
| framerate | number | 30 | 24, 30, or 60 |
| pace | number or string | 1.0 | Controls video speed. Number 0.25–6.0 (higher = slower/more deliberate) or preset: "fast" (0.5×), "normal" (1×), "slow" (2×), "dramatic" (3×), "cinematic" (4.5×). Scales cursor movement, pauses, typing speed, and all cosmetic delays. |
| darkMode | boolean | false | Emulate dark color scheme |
| blockBanners | boolean | true | Auto-hide cookie consent banners |
| deviceScaleFactor | number | 1 | Pixel ratio 1–3 |
| cursor.visible | boolean | true | Show animated cursor |
| cursor.style | string | highlight | highlight, circle, spotlight, or dot |
| cursor.color | string | #3B82F6 | Cursor color (hex) |
| cursor.size | number | 20 | Cursor size in pixels (8–60) |
| cursor.smoothing | boolean | true | Smooth cursor movement |
Per-step zoom: add `zoom: { enabled: true, level: 1.5 }` to individual click/dblclick steps.
| zoom.easing | string | ease-in-out | ease-in-out, linear, or ease |
| zoom.trigger | string | click | Zoom on clicks only |
| frame.enabled | boolean | false | Add browser window frame chrome overlay |
| frame.style | string | macos | macos, windows, or minimal |
| frame.theme | string | auto | light, dark, or auto (matches darkMode) |
| frame.showUrl | boolean | true | Show URL in the frame's address bar |
| background.enabled | boolean | false | Add decorative background behind viewport |
| background.type | string | gradient | gradient or solid |
| background.gradient | string | ocean | Preset: ocean, sunset, forest, midnight, aurora, or custom |
| background.color | string | #1e3a5f | Background color for solid type (hex) |
| background.colors | array | — | Array of 2 hex colors for custom gradient |
| background.padding | number | 40 | Padding around viewport (0–120 px) |
| background.borderRadius | number | 12 | Border radius of viewport (0–40 px) |
| clickEffect.enabled | boolean | true | Show visual feedback on clicks |
| clickEffect.style | string | ripple | ripple, pulse, or ring |
| clickEffect.color | string | cursor color | Click effect color (hex) |

### Step Notes (Guided Tour Annotations)

Add `"note": "text"` (max 500 chars) to any step to show a text overlay in the video before the action executes. Available on: navigate, click, dblclick, fill, hover, scroll. Auto-scroll: off-screen targets are scrolled into view automatically.

### Video Plan Limits

Duration scales with step count: effective timeout = base + (steps × per-step budget × pace).

| Plan | Base + Per-Step Budget | Max Steps | Formats |
|------|----------------------|-----------|---------|
| Free | 20s + 5s/step | 10 | mp4 |
| Starter | 30s + 5s/step | 20 | mp4, webm |
| Growth | 45s + 6s/step | 30 | mp4, webm, gif |
| Scale | 60s + 6s/step | 50 | mp4, webm, gif |

### Video Example

```
POST https://pagebolt.dev/api/v1/video
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Body: {
  "steps": [
    { "action": "navigate", "url": "https://pagebolt.dev" },
    { "action": "scroll", "selector": "#pricing" },
    { "action": "wait", "ms": 3000 },
    { "action": "click", "selector": "#get-started", "note": "Click here to sign up for PageBolt" }
  ],
  "format": "mp4",
  "blockBanners": true,
  "pace": "normal",
  "cursor": { "style": "highlight", "color": "#3B82F6", "persist": true },
  "clickEffect": { "enabled": true, "style": "ripple" },
  "frame": { "enabled": true, "style": "macos", "showUrl": true },
  "background": { "enabled": true, "type": "gradient", "padding": 120, "borderRadius": 12, "gradient": "sunset" }
}
```

## Agent Observation API

POST to `/api/v1/observe` with a `url` or `html`. The agent perception endpoint: in one page load it returns a compact, token-budgeted observation — id-indexed interactive elements (role, name, CSS selector, state), a heuristic `pageType` (login, signup, search, article, form, generic), grouped `actions` (login flow, search, primary buttons, navigation), and a `stats.estimatedTokens` budget hint. Optional flags `includeContent` (Markdown), `includeAriaTree`, and `includeScreenshot` bundle more in the same request. Costs 1 API request. Available on all plans.

This is the headless, server-side perception layer for AI agents and the agentic web. Unlike in-browser standards (e.g. WebMCP) that require a visible browser tab and only work for sites that instrument themselves, `/observe` turns any un-instrumented URL into agent-ready structure. Feed the returned selectors straight into `/api/v1/sequence` to act.

**FlatDomTree interop (browser-use / page-agent):** pass `format: "flatdomtree"` and the observation returns `dom_text` — the indexed plain-text DOM representation popularized by browser-use and Alibaba's page-agent (`[1]<button>Sign in</button>` …) — plus a `selectors` map (`{"1": "#signin", …}`). Agents built for that ecosystem can consume PageBolt observations directly, and their action traces can be imported back with `POST /api/v1/sequences/import` (`{ trace, selectors, name, save }`) — it converts page-agent/browser-use actions (go_to_url, click_element, input_text, select_dropdown_option, send_keys, scroll_down/up, wait) into a saved, re-runnable PageBolt sequence that can also be recorded as a narrated video. For client-side page-agent apps, the `pagebolt-page-agent` npm package attaches to a PageAgent's lifecycle hooks, records the run, and posts it here automatically.

```
POST https://pagebolt.dev/api/v1/observe
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Body: { "url": "https://example.com/login", "blockBanners": true }
```

## Page Inspection API

POST to `/api/v1/inspect` with a URL or HTML. Returns a structured JSON map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector. Costs 1 API request. Use before `/api/v1/sequence` or `/api/v1/video` to discover reliable selectors. For agent workflows, prefer `/api/v1/observe` — it returns a more compact, action-oriented observation.

## Content Extraction API

POST to `/api/v1/extract` with a `url`. Renders the page (including JavaScript) and returns clean structured content: readable text, title, metadata, and links. Costs 1 API request. Use it to feed AI agents verified page content instead of raw HTML, or to build search/RAG pipelines.

```
POST https://pagebolt.dev/api/v1/extract
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Body: { "url": "https://example.com", "blockBanners": true }
```

## Accessibility Audit API

POST to `/api/v1/audit` with a `url`. Runs an axe-core accessibility audit and returns WCAG violations with severity, affected DOM nodes, and remediation guidance. Costs 1 API request. Wire it into CI to gate deploys on accessibility regressions or to generate compliance evidence.

## ARIA Tree API

POST to `/api/v1/aria` with a `url` or `html`. Returns the accessibility (ARIA) tree — the semantic structure that screen readers and AI agents perceive. Costs 1 API request.

## Visual Diff API

POST to `/api/v1/diff` with `url_a` and `url_b` (or `html_a` / `html_b`). Pixel-compares the two renders and returns `changed_pct`, `changed_pixels`, `total_pixels`, and a base64 `diff_image` highlighting the differences. Optional `threshold` (0–1) controls per-pixel sensitivity. Costs 1 API request. Built for visual regression testing across deploys.

```
POST https://pagebolt.dev/api/v1/diff
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Body: { "url_a": "https://example.com", "url_b": "https://staging.example.com", "threshold": 0.1 }
```

## Signed Embed URLs

POST to `/dashboard/sign-embed` (or the legacy `/dashboard/sign-screenshot`) with `{ "endpoint": "screenshot" | "og-image" | "pdf", "params": {...}, "expiry_hours": 24 }` to mint an HMAC-signed URL. The resulting `GET /api/v1/embed/{endpoint}` URL can be dropped straight into an `<img>` tag (screenshot, og-image) or linked/iframed (pdf) with no API key exposed to the browser. The signature binds every parameter; changing any of them invalidates the URL. Default 24h TTL, max 7 days. Available on Hobby plan and above.

## Technical Details

- **Authentication**: API key via `x-api-key` header
- **Response formats**: Binary image/PDF or base64 JSON (`response_type: "json"`)
- **Infrastructure**: Chromium-based rendering with warm browser pools for low latency
- **Average response times**: Screenshots < 2s, PDFs 1-3s, OG images < 500ms
- **Supported output formats**: PNG, JPEG, WebP (screenshots), PDF, PNG/JPEG/WebP (OG images)