io.github.Custodia-Admin/pagebolt

Give PageBolt a URL and a plain-English GOAL; it runs an observe→plan→act→verify loop server-side until the goal is met, then returns a structured trace of every action it took plus a success/failure status. This is the "hands" on top of observe_page (the "eyes") — you do NOT author selectors or a step list yourself. Use act_on_page when you only know the OUTCOME you want (e.g. "log in and open billing", "accept the cookie banner and start a trial"); use run_sequence when you already know the exact deterministic steps/selectors (cheaper). Available on Starter+ plans. Cost is metered: 2 requests base + 1 per step taken. SECURITY: page text is treated as untrusted — the agent pursues only your goal and ignores instructions embedded in the page. Scope allowedDomains tightly and avoid destructive flows.

Check your current PageBolt API usage and plan limits.

Generate an Open Graph / social card image. Returns an image using built-in templates or custom HTML.

Create a persistent browser session (Starter+ plan required). The session keeps a live browser page open so you can reuse cookies, localStorage, and auth state across multiple take_screenshot or run_sequence calls. Pass the returned session_id to those tools. Sessions expire after 10 minutes of inactivity (hard cap: 30 minutes). Useful for AI agent workflows that log in once and then take multiple screenshots of authenticated pages.

Explicitly destroy a persistent browser session before it expires. Frees the browser page immediately. Use this when you are done with a session to free up capacity.

Turn a list of steps into a PageBolt sequence you (or the user) can edit and re-run: returns JSON to paste into the dashboard Sequence Builder ("Import JSON" - the same place "Edit sequence" opens), and it can optionally save it to the user's Saved Automations (save:true). Use it after you have planned a video/sequence so the user can tweak steps, highlights and narration themselves, or re-run it later with record_video / run_sequence. Does not run the sequence or consume quota. Put {{username}}/{{password}} placeholders in fill steps instead of real credentials; never include cookies.

Generate a PDF from a URL or HTML content. Supports custom margins, headers/footers, page ranges, and scaling. Saves the PDF to disk and returns the file path.

Fetch the status and output of a single async job by id (e.g. an async video render started by record_video). While pending/processing, returns the current status; when completed, returns the job output — for videos, the hosted watch/embed/file URLs. Free (no request quota).

Convert a page-agent/browser-use action trace into a re-runnable PageBolt sequence. Give it the array of actions a page-agent produced (each entry may be either {action, index|selector, value, ...} or the {action_name: {...}} shape) plus, optionally, the selectors map from observe_page with format:"flatdomtree" to resolve indices to CSS selectors. Set save:false for a dry run that returns the translated steps without persisting. This endpoint does NOT consume request quota. Pair with observe_page (format:"flatdomtree") → run an agent → import_agent_trace to turn an ad-hoc agent run into a deterministic, replayable sequence.

Inspect a web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector. Use this BEFORE run_sequence or record_video to discover what elements exist on the page and get reliable selectors. Returns text (not an image), so it is fast and cheap. Costs 1 API request.

List all available device presets for viewport emulation (e.g. iphone_14_pro, macbook_pro_14). Use the returned device names with the viewportDevice parameter in take_screenshot.

List your recent async jobs (e.g. videos enqueued with record_video). Returns each job's id, type, status, and timestamps. Use get_job to fetch a specific job's full output. Free (no request quota).

List all active persistent browser sessions for your API key. Returns session IDs, creation times, and expiry times. Useful for checking which sessions are still alive before reusing them.

Get a compact, token-budgeted "observation" of any web page, purpose-built for AI agents. In ONE request it returns: id-indexed interactive elements (role, name, CSS selector, state), a heuristic page-type classification (login, signup, search, article, form, generic), and grouped "suggested actions" (login flow, search, primary buttons, navigation). Optionally include readable content (Markdown), the ARIA tree, and a screenshot. This is the fastest way for an agent to understand and act on an un-instrumented page — far more token-efficient than a raw screenshot or full DOM. Use the returned selectors with run_sequence to act. Costs 1 API request.

Record a professional demo video of a multi-step browser automation sequence. Produces MP4/WebM/GIF with cursor highlighting, click effects, smooth movement, step notes, browser frame (macOS/Windows), gradient/glass backgrounds, and more. Costs 3 API requests. Saves to disk. BEST PRACTICE: Keep videos concise (5-15 action steps). Do NOT add wait steps between every action — the pace parameter handles timing. Only use wait for page loads or narration holds. Do NOT use zoom unless the user explicitly asks for it.

Execute a multi-step browser automation sequence. Navigate pages, interact with elements (click, fill, select), and capture multiple screenshots/PDFs/diffs in a single browser session. Use the "diff" step to compare the current page state against another URL after automation. Each output counts as 1 API request.

Capture a screenshot of a URL, HTML, or Markdown content. Supports device emulation, ad/chat/tracker blocking, metadata extraction, geolocation, timezone, styling (macOS/Windows frames, gradient/glass backgrounds, shadows), and more. Returns an image (PNG, JPEG, or WebP).

Compare two web pages (or HTML strings) pixel-by-pixel and return a diff image highlighting all visual differences. Supports full-page capture, device emulation, element selectors, and all screenshot-like options. Returns the diff image, changed pixel count, and percentage changed. Costs 1 API request.